BRL-CAD is in the process of converting its documentation in order to enable automatic generation of output in different formats (html, pdf, man) from a single source. We need to convert our existing UNIX man pages to the Docbook XML format. There is a doclifter conversion tool available to help automatically convert files, then just a little bit of cleanup is needed. This will find all of them:

find src/conv -name \*.1 

The simplest way to confirm the files are successfully converted is to incorporate them into BRL-CAD's build logic (edit CMakeLists.txt) and view the output using brlman and an html viewer. It is recommended to use the Emacs editor with the nxml mode in order to more easily identify and fix errors, but this is not a requirement.

This task involves using the doclifter tool to perform a rough conversion to Docbook of all man pages in the src/conv subdirectory of the BRL-CAD source tree (about 43 files), then performing whatever manual corrections are needed to the autogenerated XML files to make them valid Docbook (some conversions have already been done and can serve as guides). Add new files to the doc/docbook/system/man1/en directory (via svn add), edit the CMakeLists.txt file in that same directory, verify no errors by compiling, and make a patch.

References:

• doc/docbook/system/
• Doclifter conversion tool: http://www.catb.org/~esr/doclifter/
• Docbook documentation: http://www.docbook.org/tdg/en/html/docbook.html
• Emacs editor: http://www.gnu.org/software/emacs/emacs.html
• nxml Emacs mode: http://www.thaiopensource.com/nxml-mode/

Code:

• src/conv/*.1
• doc/docbook/system/man1/en/CMakeLists.txt
• doc/docbook/system/man1/en/