Some of BRL-CAD's existing documentation has been converted to DocBook format, but not all of the new files pass strict XML validation. We want to make our existing pages conform strictly. 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/articles directory (e.g., doc/docbook/articles/en/pipes.xml), 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:

# in your build directory cd doc/docbook/articles make 

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

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

Keep track of how long this all takes you because we intend to add a lot more tasks like this one.

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/articles/*/*.xml