GSoC/GCI Archive
Google Code-in 2012 BRL-CAD

Convert remaining manual pages to Docbook XML

completed by: Cezar

mentors: Sean

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 the pages specific to this task:

find . -name *.[1-9] -not -regex '.*cmake.*' -not -regex '.*external.*' -not -regex '.*other.*' | grep -v src/[glnrt]  | grep -v util 

This is minimally 26 files, but possibly more.  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 pertaining to BRL-CAD that are in our source tree but not already covered by other GCI tasks, then performing whatever manual corrections are needed to the autogenerated XML files to make them valid Docbook.  Many conversions have already been done and can serve as guides. Add new files to the doc/docbook/system/man#/en directory (via svn add), edit the CMakeLists.txt file (add references), remove the old files (via svn rm), and edit the and CMakeLists.txt files to remove references under src.

Verify no warnings or errors by compiling, and make a patch (svn diff > my_changes.patch).  You will probably have to make minor edits to make them compile cleanly.