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.
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)
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
You must invoke
Since we’ve installed dependencies inside the project, it’s necessary to prefix all commands (e.g., rake and docbookrx) with
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,
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.
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.
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