DocBookRx (gem: docbookrx) is the prescription (℞) you need to get rid of your DocBook pain. This tool converts DocBook XML (hell) to AsciiDoc.
Currently, DocBookRx is only available in source form. You’ll need to retrieve the source and run the application out the source directory.
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
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.7
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.7 > .ruby-version
We like RVM because it keeps the dependencies required by various projects isolated from each other and from your system.
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.
|
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.
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