The majority of BRL-CAD's documentation is defined as DocBook XML files, from which other formats (HTML, PDF, man page, etc.) can be generated. PDF files present a particular challenge, and have some very specific requirements to achieve ''good'' formatting.

BRL-CAD's DocBook files need to uniformly use a style of image inclusion that is aware of what ''role'' the image is supposed to serve. A ''basic'' image inclusion example looks like this:

<mediaobject>
<imageobject>
<imagedata align="center" fileref="../../lessons/en/images/img.png" format="PNG"/>
</imageobject>

<para>
Caption goes here.
</para>

</mediaobject>

This task involves switching image inclusions that use the above style to something like the following:

<mediaobject>
<imageobject role="html">
<imagedata align="center" fileref="../../books/en/images/img.png" format="PNG"/>
</imageobject>
<imageobject role="fo">
<imagedata align="center" fileref="../../books/en/images/img.png" format="PNG"/>
</imageobject>

<para>
Caption goes here.
</para>

</mediaobject>

The ''role'' flag to imageobject provides the opportunity to specify different image formatting options when the output is HTML (role=''html'') or PDF (role=''fo'').

The captions should be preserved as above on mediaobjects that have them, but mediaobjects without a caption should also be converted and there is no need to add a caption in such cases.

Any patch that makes changes to the DocBook sources should result in a successful ''make doc'' build test. This won't generate PDF documents, but it will validate the XML files and produce HTML. Your updated files must pass ''make doc'' to be accepted, preferably submitted in patch format.

This task is specifically to write some sort of automated script that can scan our DocBook xml hierarchy and perform the above change for all unmodified instances of the image tag - it should leave image tags that have already been updated alone.

Write the script to do the above coversion

Test it on the BRL-CAD doc/docbook source directory

Submit the script files and a patch with the changes the script has introduced into the xml files (via svn diff)