(^70) CHAPTER 6 ■ DOCUMENTATION AND CODING CONVENTIONS
As you can see, you have a lot of options for the definition of a para element. This is, of
course, an absurdly complex example, but it demonstrates the most common tags. Here are
the items included in Listing 6-11:
Lists: itemizedlist is a grouping tag that contains items within the list. You can specify an
unlimited number of listitem elements, each of which may have one or more para tags.
Footnotes: The footnote element adds a footnote. When parsed, footnotes substitute their
text for a hyperlinked [n], where n is the current footnote index. At the end of the docu-
ment, all your footnotes will be included with matching [n] text that is anchored to the
original hyperlink.
Examples, code, and CDATA: The example tag lets you include PHP code within your docu-
mentation. The title of the example is contained in the title tag, and the actual code for
the example is called a program listing and is enclosed by the programlisting tag. Notice,
though, that the PHP data must be wrapped in CDATA. CDATA actually comes from XML
and allows you to put brackets and other characters that would otherwise cause a problem
inside an XML document. Without CDATA, most PHP code would cause validation issues
with the XML document, and transformation would not be possible, so always remember
to wrap your code inside CDATA delimiters. Similar to examples, you can also embed code
in-line using the code tag. The language attribute defines what type of code the reference is.
Linking: The ulink elements add an underlined link from your documentation to another
site. This is analogous to an a (anchor) tag in HTML; instead of href, the url attribute is used.
Citations: Sometimes, you will want to include material from another author or source. To
do this, you can use the cittitle tag along with the blockquote tag to make it clear that the
words cited are not your own.
Tables: The next item is the table model for DocBook. It’s pretty much like HTML, but with
slightly different element names. The table model in DocBook is not designed to be used
for presentation, as in HTML. Instead, it is meant to be used when you have a set of data
that is best expressed in a tabular format.
Notes and literals: You can use the note element to declare a note. Often, you will need to
include the name of a function or class within your documentation. You should enclose
any literal elements like these inside the literal tag. This tag can serve as notice to trans-
lators and editors that the information is to be taken literally and cannot be translated or
edited.
Databases: When referencing databases, there is a great way to describe them in DocBook.
First take a database element, and then customize it with a class attribute. The class
attribute defines the information within the element to be one of the basic items in a data-
base, like a field, primary key, data type, table, and so on. If you use this approach, the
transformation will be able to create direct links to these items, or even present them in a
graphical fashion.
McArthur_819-9C06.fm Page 70 Friday, February 22, 2008 8:59 AM