DocBookRx: The ℞ for all your DocBook pain

DocBookRx (gem: docbookrx) is the prescription (℞) you need to get rid of your DocBook pain. This tool converts DocBook XML (hell) to AsciiDoc.

DocBookRx is the start of a DocBook to AsciiDoc converter written in Ruby. This converter is far from perfect at the moment and some of the conversion is done hastily. The plan is to evolve it into a robust library for performing this conversion in a reliable way.

• Installing the Development Version
• Running the Converter
• About this Project

Installing the Development Version

Currently, DocBookRx is only available in source form. You’ll need to retrieve the source and run the application out the source directory.

Retrieve the Source Code

Simply copy the GitHub repository URL and pass it to the git clone command:

$ git clone https://github.com/asciidoctor/docbookrx

Next, switch to the project directory:

$ cd docbookrx

Prepare RVM (optional)

We recommend using RVM when developing applications with Ruby. Follow the installation instructions on the RVM site to setup RVM and install Ruby.

Once you have RVM setup, switch to the version of Ruby you installed:

$ rvm use 2.3.0

If you want RVM to set the version of Ruby automatically whenever you switch to the project, write the version of Ruby to a file at the root of the project named .ruby-version:

$ echo 2.3.0 > .ruby-version

We like RVM because it keeps the dependencies required by various projects isolated from each other and from your system.

Install the Dependencies

The dependencies needed to use DocBookRx are defined in the Gemfile at the root of the project. You’ll use Bundler to install these dependencies.

To check if you have Bundler available, use the bundle command to query the version installed:

$ bundle --version

If it’s not installed, use the gem command to install it.

$ gem install bundler

Next, configure the bundle command (provided by the bundler gem) to use the system-wide Nokogiri library if available, which dramatically cuts down on installation time:

$ bundle config --local build.nokogiri --use-system-libraries

Finally, use the bundle command (which is provided by the bundler gem) to install the dependencies into the project:

$ bundle --path=.bundle/gems

Note	You must invoke bundle from the project’s root directory so it can locate the Gemfile.

Important

Since we’ve installed dependencies inside the project, it’s necessary to prefix all commands (e.g., rake and docbookrx) with bundle exec.

Running the Converter

To run the converter, execute the launch script and pass a DocBook file to convert as the first argument.

$ bundle exec docbookrx sample.xml

The script will automatically create the output file sample.adoc, replacing the DocBook file extension, .xml with the AsciiDoc file extension, .adoc.

The converter is not perfect yet, but we’ll get there with your help. You’ll can find a list of tasks that need attention listed in the WORKLOG.adoc file.

Conditional attribute

The DocBook conditional attribute "condition" is replaced to "ifdef" macro.

Take note the marco is on a line by itself.

For example, in the case of there is the DocBook inline element with condition.

a<phrase condition="foo">b</phrase>c

It is converted to below AsciiDoc format.

a
ifdef::foo[]
b
endif::foo[]
c

When it is converted to html format, the output is displayed with both a space before "b" and a space after "b".

a b c

About this Project

Authors

docbookrx was written by Dan Allen.

Credits

Gem structure originally created using Gemsmith.

Copyright

Copyright © 2013-2016 Dan Allen and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.

See the LICENSE file for details.