Fix documentation XML errors in doc/docbook/system/mannBRL-CAD
Status: ClosedTime to complete: 24 hrs Mentors: SeanTags: xml, text editor, docbook

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/system/mann 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:

# in your build directory cd doc/docbook/system/mann make 

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

svn diff ~/brlcad.svn/doc/docbook/system/mann  xmlfixes.patch 

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

References:

Code:

  • doc/docbook/articles/*/*.xml
Uploaded Work
File name/URLFile sizeDate submitted
mann.patch471.9 KBNovember 28 2012 21:05 UTC
Comments
Sean on November 28 2012 19:07 UTCwork completed

This task is already completed and allocated to a student.

Cezaron November 28 2012 19:21 UTCTask Claimed

I would like to work on this task.

Sean on November 28 2012 19:21 UTCTask Assigned

This task has been assigned to Cezar. You have 24 hours to complete this task, good luck!

Cezaron November 28 2012 21:06 UTCCommit r53879

Commit r53879

Cezaron November 28 2012 21:38 UTCReady for review

The work on this task is ready to be reviewed.

Sean on November 28 2012 21:38 UTCTask Closed

Congratulations, this task has been completed successfully.