DocBook Demo
by Ron Burkey
This isn't really a PSAC. It's just a little thing I threw together to demo inserting raw <Command>DocBook</Command> commands into <Command>Do178Builder</Command> databases.
To see how I actually did any of this stuff, look at the XML database that I used to create the doc.
I would, however, offer the following advice about including raw <Command>DocBook</Command> commands within your DO-178B database: <Command>DocBook</Command> has so many different things it can do, that it's possible to spend most of your time just researching what <Command>DocBook</Command> can do, and determining the proper way to do it. But the object of using <Command>Do178Builder</Command> is to make things simple for you. So where it's at all reasonable to do so, you should concentrate on just providing content, and use the simple features <Command>Do178Builder</Command> provides to you, rather than exerting all your effort on presentation. Remember, DO-178B documentation is read by technical people.
Here I add a footnote.<DocBook><footnote><para>This is the first paragraph of my footnote. It has several sentences in it in order to make it long, so that we can see it wrap around on the page. In fact, here's a gratuitous third sentence!</para><para>This is the second sentence of my footnote. For reasons not clear to me, it seems to come out in a smaller size. Maybe somebody can explain this to me....</para></footnote></DocBook> I call it a <Emphasis>foot</Emphasis>note, though whether it's a footnote, an endnote to the document, or an endnote to a document section is really controlled by the stylesheet that's in effect when the <Command>Do178Builder</Command>'s output SGML is post-processed by <Command>DocBook</Command> utilities to create the PDF or RTF or whatever for presentation.
It's also possible to create a footnote<DocBook><footnote id=myfn><para>Another footnote.</para></footnote></DocBook> which can be referred to later by the same mark.<DocBook><footnoteref linkend=myfn></DocBook> This is useful (for example) in tables, where the same footnote may apply to a lot of different cells.
Another interesting thing to do is to include a table. Here's a 3-row, 3-column table with equal column sizes and a grid around the cells:
<DocBook>
<informaltable>
<tgroup cols=3 align=center>
<tbody>
<row><entry>A</entry><entry>B</entry><entry>C</entry></row>
<row><entry>D</entry><entry>E</entry><entry>F</entry></row>
<row><entry>G</entry><entry>H</entry><entry>I</entry></row>
</tbody>
</tgroup>
</informaltable>
</DocBook>
Here's a different example, in which I specify that the second column is twice as wide as the first column, and the third column is quadruple size. Also, the entries are no longer centered:
<DocBook>
<informaltable>
<tgroup cols=3>
<colspec colwidth="1*">
<colspec colwidth="2*">
<colspec colwidth="4*">
<tbody>
<row><entry>Item 1</entry><entry>My favorite</entry><entry>Here I'm putting a long, long description, just so that we can see the wrap-around</entry></row>
<row><entry>Item 2</entry><entry>Emily's favorite but not Whitney's favorite</entry><entry>A short bit of text.</entry></row>
<row><entry>Item 3</entry><entry>Amy's favorite</entry><entry>But who cares?</entry></row>
</tbody>
</tgroup>
</informaltable>
</DocBook>
It's possible to create lists, such as numbered lists or bulleted lists. Here are some examples of each:
<DocBook>
<itemizedlist>
<listitem><para>Well, here's my first bulleted list item.</para></listitem>
<listitem><para>And here's my second one. I'm making it really long to make sure I see wraparound.</para></listitem>
<listitem><para>And a short third one.</para></listitem>
<listitem><para>You get the idea.</para></listitem>
</itemizedlist>
<orderedlist>
<listitem><para>Well, here's my first numbered-list item.</para></listitem>
<listitem><para>And here's my second one. I'm making it really long to make sure I see wraparound.</para></listitem>
<listitem><para>And a short third one.</para></listitem>
</orderedlist>
</DocBook>
You can also do math stuff, either inline or formatted as blocks, but this seems to require a graphical image of the math, so I won't attempt to demo it.
<DocBook>
<figure>
<title>Demo of a graphic: The Mad Hatter</title>
<graphic fileref="Hatter.jpg" align=center scale=33></graphic>
</figure>
</DocBook>
As an example of inline graphics, here you should see a <DocBook><inlinegraphic fileref="star_butterfly.jpg"></inlinegraphic></DocBook> (butterfly).
A potential problem with referencing external files (such as graphics) is that these files generally need to be copied into the output directory where <Command>Do178Builder</Command> generates its output SGML (<Command>DocBook</Command>) files. Otherwise, when you run <Command>DocBook</Command> utilities to post-process the output SGML and create PDF or RTF (or whatever), these files will be missing. But because <Command>Do178Builder</Command> does not understand the <Command>DocBook</Command> commands themselves, it is not necessarily able to understand when external files are referenced, and may therefore not copy such files. As a compromise solution, <Command>Do178Builder</Command> <Emphasis>does</Emphasis> look for <Function>fileref</Function> attributes, and does copy any files which are referenced by them. This should work in most cases. If not, there's always a workaround of manually files into the output directory.
Oddball symbols can also be included, such as the Hebrew <DocBook>ℵ</DocBook> (aleph) or the <DocBook>∞</DocBook> (infinity) symbol. Your ability to print these may depend on the fonts installed on your computer.
Here's a lower-case Greek alphabet, for example, with variants shown for some of the characters: <DocBook>α, β, γ, δ, ε, ζ, η, &thetas;, ι, κ (ϰ), λ, μ, ν, ξ, π, ρ (ϱ), σ (ς), τ, υ, &phis; (ϕ), χ, ψ, ω.</DocBook>
A bunch of special symbols are listed at the end of Walsh and Muellner's book.
You might need a block-quote to (for example) describe the licensing of some software you're using:
<DocBook>
<blockquote>
<attribution>XYZ Corporation</attribution>
<para>The ABC software program is ©2004 by the XYZ Corporation, Ltd., all rights reserved.</para>
<para>As a licensee of the ABC software, you may include it in binary form when distributing binary copies of your own software. For each copy distributed, a royalty of $5 shall be paid within...</para>
</blockquote>
</DocBook>
Although such niceties are generally ignored in technical documentation such as DO-178B documentation, it is traditional when quoting material (of another author) to place short quotations (say, a phrase or a sentence) within quotation marks and to place longer quotations (a paragraph or more) in a block-quote like that above.