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
I somehow managed to find XML files with mediaobject tags but what am i supposed to do? copy them into notepad and save as XML and edit them then sumbit them here?
I would like to work on this task.
This task has been assigned to Sharan Narayan. You have 72 hours to complete this task, good luck!
The work on this task is ready to be reviewed.
Sharan, I believe this is your first "source file" submission? Source file changes are most efficiently communicated and exchanged in "patch" format.
There are hundreds of tutorials around the web and we have information on our website [1][2], but the basic idea is that you obtain an SVN checkout of our source files. You edit the files, and then you have SVN generate a patch file (automatically).
Creating patch files on Windows is slightly different, but the same basic concept applies. You get a checkout (e.g., via TortoiseSVN), edit the files (directly), and extract a patch file of your changes (using TortoiseSVN). Alternatively, you can use the virtual disk image we provide and the instructions should work exactly as-is.
[1] http://brlcad.org/wiki/Patches
[2] http://brlcad.org/wiki/Deuces#When_You.27re_Done
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.
The work on this task is ready to be reviewed.
Sharan, this is much closer, but those are invalid patch files. It looks like maybe you copy-pasted the diff output? Patch files are the ENTIRE output including likes that begin with special markers like Index: and @@ and ---. Also, if you do it right, it's just one file.
This shows how to create a patch using TortoiseSVN:
http://make.wordpress.org/core/handbook/working-with-patches/create-a-patch-using-tortoisesvn/
If you tell me how your work environment is set up (which SVN client you're using, which OS), I can help you more specifically if it's not TortoiseSVN.
Congratulations, this task has been completed successfully.
And I selected the wrong button.. :) However, I'd still like your patch so we can apply your changes. Feel free to e-mail the patch file to devs@brlcad.org