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 simply to do the above conversion for all images in the file or files, not to introduce PDF specific formatting. If all image inclusions have been converted successfully and a student is interested in actually fixing the formatting, please discuss it with us on IRC or the mailing list. Follow-on tasks are likely.
References:
- doc/docbook/*/en/*.xml (anything with mediaobject tags)
- doc/docbook/books/en/BRL-CAD_Tutorial_Series-VolumeIII.xml
Code:
- doc/docbook
File name/URL | File size | Date submitted | |
---|---|---|---|
gci.tar.gz | 21.3 KB | November 19 2013 21:42 UTC |
I would like to work on this task.
This task has been assigned to David Wood. You have 72 hours to complete this task, good luck!
I think I've finished this task in the Virtual Machine avaliable on the BRL-CAD website, I've went through 4 small files and converted any instances of imageobject to two instances, one with role="html" and the other with role="fo". I'm unsure as how to sumbit this, or if this has been done correctly.
I've submitted the files I've modified, they all originated from doc/docbook/lessons/en
The work on this task is ready to be reviewed.
Looks good!
Congratulations, this task has been completed successfully.
Numerous follow-on tasks as well as a scripting task were added.