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/[glnrt]* -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/gtools, src/lgt, src/nirt, src/remrt, src/rt,src/rttherm, and src/tab subdirectories of the BRL-CAD source tree (about 24 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:

• Current Docbook man pages: http://brlcad.svn.sourceforge.net/viewvc/brlcad/brlcad/trunk/doc/docbook/system/
• Docbook documentation: http://www.docbook.org/tdg/en/html/docbook.html
• Doclifter conversion tool: http://www.catb.org/~esr/doclifter/
• Emacs editor: http://www.gnu.org/software/emacs/emacs.html
• nxml Emacs mode: http://www.thaiopensource.com/nxml-mode/

Code:

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