This project should have a contributing guide (named CONTRIBUTING.adoc). It should explain how to get setup for development (pulling in content from the README), how to run tests, preferred coding style and goals for the project.

We can draw generic content and messaging from other contributing guides in the ecosystem (See https://github.com/asciidoctor/atom-language-asciidoc/blob/master/CONTRIBUTING.adoc and https://github.com/asciidoctor/asciidoctor.js/blob/master/CONTRIBUTING.adoc). What should be unique about this contributing guide is a clear list of goals for the project. Here's a draft of those goals:

• Avoid unnecessary whitespace in the generated AsciiDoc
  • Unnecessary whitespace can be a real nuisance for users.
  • If we handle whitespace well, it's a chance to stand out against pandoc.
  • Tests should verify whitespace accuracy).
• The code should not generate any Ruby warnings
• Follow contribution workflow
  • Every change should be submitted as a pull request (and ideally associated with an issue)
  • Unless it's a very trivial change, pull requests should remain open for ~24 hours to provide a chance for comment and review
  • Pull requests should get a thumbs up from at least one other person in the project. Don't hesitate to mention other members in a comment to prod them.
  • If you want to avoid a merge commit, you can use the "squash and merge" feature 0of the merge button
  • Each change should have one or more tests that can verify it.
• We should generate clean, consistent AsciiDoc, following the recommendations in the Asciidoctor User Manual. (see http://discuss.asciidoctor.org/Joining-the-Docbookrx-project-tp4695p4709.html)

The document doesn't have to be perfect to start. What's most important is that we get it started.

Atomising the Worklog into discreet tasks may just allow some contributors to have a go at resolving them. And it will look great when you do a release: all those bugs!!! ;)

Set default document attributes when the doctype is article (sectnums, toc, icons, experimental, etc). Default attributes are currently only set when the doctype is book.

Text after a <variablelist> tag, contained inside a <para> tag is adjoined to the text of the last <varlistentry>.

docbookrx doesn't seem to properly convert an xref: it adds a cross reference text that is taken from the ID of a section, for example, and not from the contents of the section title.

It would be sufficient to convert the xref without specifying any cross reference text, actually.

Tracked from the issues marked with an asterix in https://github.com/opendevise/docbookrx/blob/master/WORKLOG.adoc

Create a proper API, and include the API inside a Ruby module.

List continuation doesn’t get added if literallayout is delimited (bug)

Tracked from the issues marked with an asterix in https://github.com/opendevise/docbookrx/blob/master/WORKLOG.adoc

Add an option to drop role names for inline literal elements.

This is related to #25:

This is actually a bug.

The format_text method in lib/docbookrx/docbookrx_visitors.rb calls @lines.pop, which causes problems when we have nested elements.

For example:

   <listitem>
     <para>get all process definitions</para>
     <para>
       <programlisting>Collection definitions = runtimeDataService.getProcesses(new QueryContext());</programlisting>
     </para>
   </listitem>
   <listitem>
     <para>get active process instances
       <programlisting>Collection&lt;processinstancedesc> instances = runtimeDataService.getProcessInstances(new QueryContext());</programlisting></para>
   </listitem>

The first listitem is formatted correctly -- while the second is not. The problem is that the code doesn't expect the <para> element to contain the <programlisting>, and pops the formatting for the [source] ("----" in this case), so that you get something that looks like this:

* get all process definitions
+

[source]
----
Collection definitions = runtimeDataService.getProcesses(new QueryContext());
----



[source]
----
 Collection<processinstancedesc> instances = runtimeDataService.getProcessInstances(new QueryContext());
* ----
get active nodes for given process instance

The problem is that we have the following code in format_text:

    if node.is_a? ::Nokogiri::XML::Node
      append_blank_line
      proceed node
      @lines.pop
    else
      nil
    end

and in visit_listitem we have:

 def visit_listitem node
    elements = node.elements.to_a
    item_text = if elements.size > 0
      format_text elements.shift
    else
      format_text node
    end
    # create line with marker and item_text and append it.. 

This means that the text is appended to @lines, then the <programlisting> element is processed (and added to @lines by proceed node in format_text) and only then is the marker added.. which gives us the incorrect asciidoc shown above.

@mojavelinux One of the problems I'm increasingly encountering is the lack of state. This makes dealing with whitespace, continuations and nested elements, among others, hard to deal with. I've tried fixing it with adding more fields, but these fixes end up being band-aids on a larger wound..

I'd like to refactor docbookrx so that it first creates an internal model of the AsciiDoc document before "printing".

Any objections or other issues that I might be missing?

(BTW, I'm definitely not totally sure about this -- I'm just running into a lot of edge cases that seem to suggest that this would be a better approach than what we have currently).

Implement qanda list (i.e., qandaset)

Tracked from the issues marked with an asterix in https://github.com/opendevise/docbookrx/blob/master/WORKLOG.adoc

When I tried to run this against Spring Security's docbook. I got the following error:

$ ruby docbookrx.rb index.xml 
No visitor defined for <info> element! Skipping.
No visitor defined for <preface> element! Skipping.
No visitor defined for <part> element! Skipping.
No visitor defined for <part> element! Skipping.
No visitor defined for <part> element! Skipping.
No visitor defined for <part> element! Skipping.
No visitor defined for <part> element! Skipping.
docbookrx.rb:387:in `generate_id': undefined method `downcase' for nil:NilClass (NoMethodError)
    from docbookrx.rb:366:in `process_section'
    from docbookrx.rb:89:in `visit'
    from /var/lib/gems/1.9.1/gems/nokogiri-1.6.0/lib/nokogiri/xml/node.rb:691:in `accept'
    from docbookrx.rb:320:in `visit_include'
    from docbookrx.rb:85:in `visit'
    from /var/lib/gems/1.9.1/gems/nokogiri-1.6.0/lib/nokogiri/xml/node.rb:691:in `accept'
    from docbookrx.rb:106:in `block in traverse_children'
    from /var/lib/gems/1.9.1/gems/nokogiri-1.6.0/lib/nokogiri/xml/node_set.rb:237:in `block in each'
    from /var/lib/gems/1.9.1/gems/nokogiri-1.6.0/lib/nokogiri/xml/node_set.rb:236:in `upto'
    from /var/lib/gems/1.9.1/gems/nokogiri-1.6.0/lib/nokogiri/xml/node_set.rb:236:in `each'
    from docbookrx.rb:105:in `traverse_children'
    from docbookrx.rb:271:in `process_doc'
    from docbookrx.rb:254:in `visit_book'
    from docbookrx.rb:85:in `visit'
    from /var/lib/gems/1.9.1/gems/nokogiri-1.6.0/lib/nokogiri/xml/node.rb:691:in `accept'
    from docbookrx.rb:905:in `<main>'

The docbook has since been removed, but you can see it at: /github.com/spring-projects/spring-security/tree/df5e03

Only use nested elements on listitem if first element in paragraph; otherwise, treat as inline text.

Honor the inline formatting of content in a table cell, using cell styles where appropriate.

Use a logging API to print warnings and other messages. I think the built-in logging API in Ruby will work.

http://ruby-doc.org/stdlib-2.1.2/libdoc/logger/rdoc/Logger.html

DocBookRx is missing several visitors for properly converting a manpage written in DocBook. Implement the necessary visitors and ensure that the output has the required structure to convert from AsciiDoc to a manpage.

• input: https://git.linuxtv.org/media_tree.git/tree/Documentation/DocBook/media/v4l/func-ioctl.xml
• expected result: https://git.linuxtv.org/mchehab/asciidoc-poc.git/tree/func-ioctl.adoc

When converting a document containing a <bridgehead> tag, I get the following traceback:

/home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:459:in `visit_bridgehead': undefined method `sub' for nil:NilClass (NoMethodError)
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:133:in `visit'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node.rb:595:in `accept'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:144:in `block in traverse_children'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node_set.rb:187:in `block in each'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node_set.rb:186:in `upto'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node_set.rb:186:in `each'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:143:in `traverse_children'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:515:in `process_section'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:133:in `visit'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node.rb:595:in `accept'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:144:in `block in traverse_children'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node_set.rb:187:in `block in each'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node_set.rb:186:in `upto'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node_set.rb:186:in `each'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:143:in `traverse_children'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:515:in `process_section'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:366:in `visit_chapter'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx/docbook_visitor.rb:133:in `visit'
    from /home/tradej/.gem/ruby/gems/nokogiri-1.6.7.2/lib/nokogiri/xml/node.rb:595:in `accept'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx.rb:12:in `convert'
    from /home/tradej/red-hat/git/docbookrx/lib/docbookrx.rb:24:in `convert_file'
    from /home/tradej/red-hat/git/docbookrx/bin/docbookrx:32:in `<main>'

Commented out lines in DocBook XML seem to be dropped silently when converting a doc. It would be nice to either print a warning about this, or better, implement support for AsciiDoc comment blocks.

I found ".ruby-version" file was registered on this git repository.
https://github.com/asciidoctor/docbookrx/blob/0f3c954a7a549cfeafdbbbbc2293f5a673fbdbfb/.ruby-version

However I like the style that .ruby-version file is not registered on the repository.
Because I guess that developers like to use their own ruby version with RVM or Rbenv on their local environment.

Look at the case of popular project nokogiri. nokogiri is addeding .ruby-version to .gitignore file.
https://github.com/sparklemotion/nokogiri/blob/v1.6.8/.gitignore#L11

If you want to restrict used ruby version, you can use
required_ruby_version in gemspec file or Rakefile.
http://guides.rubygems.org/specification-reference/#required_ruby_version

Cases of required_ruby_version
https://github.com/bundler/bundler/blob/v1.12.5/bundler.gemspec#L17
https://github.com/sparklemotion/nokogiri/blob/v1.6.8/Rakefile#L153

Thanks.

When converting a file that includes another file (let's call them parent and child), DocBookRx prepends and suffixes the include::[] commands in the parent with :leveloffset: 1 and :leveloffset: 0 lines to adjust for the shifted levels in the child. That is IMHO not entirely correct, because it resets the leveloffset set in any document that may include the parent.

I believe that the lines preceding and following the inclusion commands in the parent should be :leveloffset: +1 and :leveloffset: -1 as then they would retain the value set in any document that may include the parent.

Create a proper command-line interface to give the user greater control of the script.

Features should include:

• separate library from cli invoker
• usage text
• version text
• pass configuration options
• specify output file or directory

docbookrx doesn't convert a ulink to an external link when nested within a table cell. The content of the ulink is however preserved.

When converting an xref nested within a table cell, the reference link is not generated at all.

Last year, SUSE started to convert its docbook/xml documentation to asciidoc. I have a ton of fixes for docbookrx to make that happen.

Given that docbookrx hasn't seen an update for almost a year, I wonder if this project is still active and would be interested. I'd rather not open PRs for each of these fixes 😉

Any suggestions on how to proceed ?

For example:

<para>
    Before installing Red&nbsp;Hat&nbsp;JBoss&nbsp;Web&nbsp;Server on Red&nbsp;Hat Enterprise&nbsp;Linux, ensure the following prerequisites are met.
<para>

becomes:

Before installing RedHatJBossWebServer on RedHat EnterpriseLinux, ensure the following prerequisites are met.

Implement callouts (i.e, calloutlist)

Tracked from the issues marked with an asterix in https://github.com/opendevise/docbookrx/blob/master/WORKLOG.adoc

I performed below command.
But it seems to be unaware refentry.
I don't know why this error happened.

$ ./bin/docbookrx ./drbd9/drbd.conf.xml 
No visitor defined for <refentry>! Skipping.

drbd.conf.txt

Partition the DocbookVisitor class into separate includes to make it more manageable.

One idea is to split on content types (metadata, section, block, inline). Also split out utilities into a separate include as well.

Currently, lists are all using the same indent level. Fix this to make sure lists are converted with indentation preserved.

Tracked from the issues marked with an asterix in https://github.com/opendevise/docbookrx/blob/master/WORKLOG.adoc

Currently the citetitle and attribution are dropped. Carry over these attributes if specified.

I was trying to setup 'docbookrx' on my Windows environment by following the steps from url: https://github.com/asciidoctor/docbookrx/blob/master/README.adoc

But, I starting getting below error message::
bundler: command not found: docbookrx
Install missing gem executables with bundle install

Screenshot for the reference also attached.

Now that the repository has a proper gem structure, it's time to migrate it to the asciidoctor organization.

When converting Publican-based DocBook XML docs from the Fedora Doc Project, it turned out some of the often-used elements are unsupported:

• productname
• productnumber
• menuchoice
• guimenu
• guisubmenu
• guimenuitem
• userinput
• computeroutput
• option
• systemitem
• remark
• revhistory
• replaceable
• guiicon
• citetitle
• package
• qandaset
• programlistingco
• foreignphrase
• calloutlist
• property
• type
• attribution
• database
• exceptionname
• biblioentry
• quote
• citation
• function

docbookrx swallows an itemizedlist nested within a variablelist, the contents of the itemizedlist are silently dropped.

Given a multi-file docbook project such as the following (truncated):

.
+── Tutorials.xml
\── sections
    +── 01Preface.xml
    +── 05TutorialsIntro.xml
    +── 10General
        +── 10TutorialIntroduction.xml
    +── 10General_autoIndex.xml

Where sections/10General_autoIndex.xml is included by the root document Tutorials.xml as follows:

[...]
<xi:include href="sections/01Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="sections/05TutorialsIntro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="sections/10General_autoIndex.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
    <index/>
</book>

and 10TutorialIntroduction.xml is included by sections/10General_autoIndex.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" >
<chapter id="general">
  <title>General</title>
[...]
<xi:include href="10General/10TutorialIntroduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
[...]
</chapter>

docbookrx fails to locate sections/10General/10TutorialIntroduction.xml.

I must say I'm not an expert in DocBook, but if I read the specification correctly, then it is correct that sections/10General_autoIndex.xml uses a path relative to itself to import sections/10General/10TutorialIntroduction.xml.

So I am not sure why docbookrx fails to load sections/10General/10TutorialIntroduction.xml?

Can it be packaged for "gem install" please?
Reasons:
I can't get the install to work on Ubuntu (Nokogiri again)
I need to install/run it offline

There are certain cases when the output is starting with a blank line. This happens when the input doesn't start with <section>. Leading (and possibly trailing) blank lines should be stripped.

Implement complex children of <varlistentry>. Currently, only simple content is supported, plus some select content such as a figure.

I followed the installation instructions successfully until the bundle command. This command fails with the error from below.

My next attempt will be to try the steps in a Docker Fedora container. I update the issue once I have done this, unfortunately I'm travelling currently and my wifi is very slow.

vogella@Frodo:~/git/docbookrx$ bundle
Fetching gem metadata from https://rubygems.org/.........
Fetching version metadata from https://rubygems.org/..
Resolving dependencies...

Your user account isn't allowed to install to the system Rubygems.
You can cancel this installation and run:

  bundle install --path vendor/bundle

to install the gems into ./vendor/bundle/, or you can enter your password
and install the bundled gems to Rubygems using sudo.

Password:
Installing rake 10.4.2
Installing diff-lcs 1.2.5
Installing mini_portile2 2.0.0
Installing rspec-support 3.4.1
Using bundler 1.11.2
Installing nokogiri 1.6.7.2 with native extensions

Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

/usr/bin/ruby2.1 extconf.rb --use-system-libraries

mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

extconf failed, exit code 1

Gem files will remain installed in /tmp/bundler20160126-24774-6780kenokogiri-1.6.7.2/gems/nokogiri-1.6.7.2 for inspection.
Results logged to /tmp/bundler20160126-24774-6780kenokogiri-1.6.7.2/extensions/x86_64-linux/2.1.0/nokogiri-1.6.7.2/gem_make.out
Installing rspec-core 3.4.1
Installing rspec-expectations 3.4.0
Installing rspec-mocks 3.4.1
An error occurred while installing nokogiri (1.6.7.2), and Bundler cannot continue.
Make sure that gem install nokogiri -v '1.6.7.2' succeeds before bundling.
vogella@Frodo:~/git/docbookrx$ sudo gem install nokogiri -v '1.6.7.2'
[sudo] password for vogella:
Building native extensions. This could take a while...
ERROR: Error installing nokogiri:
ERROR: Failed to build gem native extension.

/usr/bin/ruby2.1 extconf.rb

mkmf.rb can't find header files for ruby at /usr/lib/ruby/include/ruby.h

extconf failed, exit code 1

Gem files will remain installed in /var/lib/gems/2.1.0/gems/nokogiri-1.6.7.2 for inspection.
Results logged to /var/lib/gems/2.1.0/extensions/x86_64-linux/2.1.0/nokogiri-1.6.7.2/gem_make.out

In DocBook, almost any element can be conditional, i. e. displayed/evaluated only when a condition is defined. Our team uses these conditions extensively, as we have several sources that vary only in product names and such, so this is a key feature for us.

A few notes:

• Most of the time, we use something like <phrase conditon="FOO">bar</phrase> or <chapter condition="BAZ">...</chapter>, in general nested as needed. I understand that, for example, this construct:

  <title>
      Foo <phrase condition="BAR">baz</phrase> qux
  </title>

  is probably not easily convertible as both titles and conditions in AsciiDoc require the line to start with = or ifdef, respectively, and that the XML source will have to be modified to be convertible.

• It is not important for us if one-line or block conditions are used in the resulting document. Both:

  ifdef::FOO[bar]

  and

  ifdef::FOO[]
  bar
  endif::FOO[]

  are okay.

• <xi:include ...> statements in DocBook also support conditions, but that can easily lead to invalid XML documents, which are buildable by Publican (that happens by including multiple tags with the same ID, for example). I am not sure if conditional inclusion should be supported for this reason.

Setup a proper RubyGems structure for the project so that it's ready to be published to RubyGems.