Some of BRL-CAD's existing documentation has been converted to DocBook format, but not all of the new files pass strict XML validation (particularly the new GCI files). We want to make our existing pages conform strictly and convert cleanly. The simplest way to find documents with errors is to add a CMake configuration flag when preparing to build BRL-CAD that enables a strict check when make is run. Adding this flag will cause a build failure if there's a syntax error:

-DBRLCAD_EXTRADOCS_VALIDATE=ON 

Generally, the resulting error message will provide hints that can be used to identify and fix the problem. Also, once it is clear how to address one particular problem, it is likely that that problem will occur multiple times in different files. This will make the process faster once initial errors are solved.

This task involves preparing a BRL-CAD compilation environment with validation enabled, then cleaning up the DocBook XML files under the doc/docbook directory, fixing whatever errors arise and submitting a patch. You can build test your changes by compiling just a subset of the documentation. In your build directory (not source), you can run this:

cd doc/docbook && make 

Once you're done, make and submit your patch: 

svn diff ~/brlcad.svn/doc/docbook > xmlfixes.patch 

References:

• doc/docbook/README
• DocBook 5 Reference: http://docbook.org/tdg5/en/html/docbook.html
• Emacs editor: http://www.gnu.org/software/emacs/emacs.html
• nxml Emacs mode: http://www.thaiopensource.com/nxml-mode/

Code:

• doc/docbook/*/*/*.xml