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=ONGenerally, 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 makeOnce you're done, make and submit your patch:
svn diff ~/brlcad.svn/doc/docbook xmlfixes.patchReferences:
- 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
| File name/URL | File size | Date submitted | |
|---|---|---|---|
| man5final.patch | 13.0 KB | December 02 2012 19:37 UTC | |
| man5full.patch | 25.9 KB | December 03 2012 01:31 UTC | |
| man1full.patch | 24.9 KB | December 03 2012 01:31 UTC | |
| system_warnings.patch | 147.2 KB | December 03 2012 14:42 UTC | |
| system_contrib_fix.patch | 76.4 KB | December 03 2012 16:57 UTC |
I would like to work on this task.
This task has been assigned to Cezar. You have 48 hours to complete this task, good luck!
The work on this task is ready to be reviewed.
Commit r53957
If these are all committed, I'm still getting a slew of warnings throughout the compile. Messages like this:
[ 9%] Generating ../../../../../share/man/man1/anim_track.1
Note: meta manual : no titled ancestor of refentry anim_track
Note: meta manual : no refentry/refmeta/refmiscinfo@class=manual anim_track
Note: meta manual : see http://docbook.sf.net/el/refmiscinfo anim_track
Warn: meta manual : using "BRL-CAD" for "manual" anim_track
Note: Writing anim_track.1
[ 9%] Built target anim_track_man1_man
[ 9%] Generating ../../../../../share/doc/html/man1/en/anim_turn.html
[ 9%] Built target anim_turn_man1_html
[ 9%] Generating ../../../../../share/man/man1/anim_turn.1
Note: meta manual : no titled ancestor of refentry anim_turn
Note: meta manual : no refentry/refmeta/refmiscinfo@class=manual anim_turn
Note: meta manual : see http://docbook.sf.net/el/refmiscinfo anim_turn
Warn: meta manual : using "BRL-CAD" for "manual" anim_turn
Note: Writing anim_turn.1
One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.
Ah, wasn't aware we cared about the warnings, so I didn't fix those. Okay then, I'm on it.
The work on this task is ready to be reviewed.
`system_warnings.patch` should get rid of all the warnings inside doc/docbook/system/*
Commit r53961
Congratulations, this task has been completed successfully.
I removed the contrib tag where the author is an organization.
Commit r53964
Patch file: system_contrib_fix.patch