DocBookRx: The ℞ for all your DocBook pain¶ ↑
Dan Allen <github.com/mojavelinux[@mojavelinux]> // Settings: :idprefix: :idseparator: - :icons: font ifdef::env-github,env-browser[] :toc: preamble :toclevels: 1 endif::[] ifdef::env-github[] :status: :outfilesuffix: .adoc :!toc-title: endif::[] // Aliases: :project-name: DocBookRx :project-handle: docbookrx // URIs: :uri-asciidoc: asciidoc.org :uri-docbook: docbook.org :uri-repo: github.com/asciidoctor/docbookrx :uri-rvm: rvm.io :uri-rvm-install: rvm.io/rvm/install :uri-build-status: travis-ci.org/asciidoctor/docbookrx :img-build-status: img.shields.io/travis/asciidoctor/docbookrx/master.svg
ifdef::status[] image:{img-build-status}[Build Status Badge,link={uri-build-status}] endif::[]
{project-name} (gem: *{project-handle}*) is the prescription (℞) you need to get rid of your DocBook pain. This tool converts DocBook XML (hell) to AsciiDoc.
{project-name} is the start of a uri-docbook to uri-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¶ ↑
Currently, {project-name} 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 {uri-repo}[GitHub repository URL] and pass it to the ‘git clone` command:
- subs=attributes+
-
$ git clone {uri-repo}
Next, switch to the project directory:
- subs=attributes+
-
$ cd {project-handle}
Prepare RVM (optional)¶ ↑
We recommend using uri-rvm when developing applications with Ruby. Follow the {uri-rvm-install}[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:
- subs=attributes+
-
$ 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 [path].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 {project-name} are defined in the [path]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 [path]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 [path]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 github.com/mojavelinux[Dan Allen].
Credits¶ ↑
Gem structure originally created using github.com/bkuhlmann/gemsmith[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[LICENSE] file for details.