DocBook v5 elements used in the manual and their meaning

To keep things simple the manual uses only a small subset of all available elements in the DocBook schema. This makes it fairly easy to quickly get up to speed with adding and editing the manual. It also helps to keep the look&feel consistent and makes the writing of the CSS and XSL stylesheets a little bit easer.

The following list shows the supported elements and how they should be used in the manual

<chapter>, <appendix>

This is the top element for each chapter and appendix in the manual. Each <chapter> or <appendix> must also have a title.

Table 1. Required attributes

Attribute Value Description
xmlns http://docbook.org/ns/docbook Name space for DocBook. Always needed.
xmlns:xi http://www.w3.org/2001/XInclude Name space for XInclude. Needed since we use XInclude to split the manual into different files.
xmlns:xlink http://www.w3.org/1999/xlink Name space for xlink. Needed sine we make use of link and xref elements to link to other sites and cross references within the manual.
version 5.0 Versions of DocBook. Always needed
xml:id app.XXX , ch.XXX The id for the chapter or the appendix. Used in other part of the manual to refer to this chapter/appendix with an <xref> element.

Table 2. Required nested elements

Element Value
<title> The title of the chapter/appendix

Example:

<appendix xmlns="http://docbook.org/ns/docbook" 
    xmlns:xi="http://www.w3.org/2001/XInclude"
	xmlns:xlink="http://www.w3.org/1999/xlink" 
    version="5.0" 
    xml:id="app.coretasks">
	<title>Core tasks</title>
...
</appendix>
<sectN>

The section tags divides each chapter and appendix into logical parts. Each task description must be contained in a <sect1> element and each example section for the task must be contained within a <sect2> element. Depending on the description needed for each task additional <sect2> may be added as needed to make the text logically structured. If needed, a further nesting level may be used by using <sect3> elements within each <sect2> element. No deeper nestings than <sect3> should ever be used.

Each top level section must have the xml:id attribute which is used to reference the section from other parts of the document. Each section must have a nested title element.

Table 3. Required attributes

Attribute Value Description
role taskdef This is only used and required for <sect1> elements for task description. This role is not currently used in the any of the XSL sheets. This is for future use.
xml:id Name of section The id for task definition should be the same as the task name for task description. For other sections the id should be a logical name that descrobes the content.

Table 4. Required nested elements

Element Value
<title> The title of the section

Example:

<sect1 role="taskdef" xml:id="AdhocTaskdefTask">
    <title>AdhocTaskdefTask</title>
...
</sect1>
<para>

Division between paragraphs in flowing text.

<screen>

Used to mark command lines and multi-line computer output. For inline screen output use the <literal> element

<programlisting>

Used for all PHP and XML program listings in the manual. Please note that this tag should not be used for command lines as entered in a terminal. Use the <screen> element for this.

Note: Remember to write all opening '<' as &lt;

Table 5. Required attributes

Attribute Value Description
language php, xml The language attribute should indicate what programming language the programlisting contains. This is used to control what syntax highlighting should be used.

Example:

<programlisting language="xml">
  &lt;append 
   destFile="${process.outputfile}">
  &lt;filterchain>
    &lt;xsltfilter style="${process.stylesheet}">
	     &lt;param name="mode" expression="${process.xslt.mode}"/>
    &lt;/xsltfilter>
  &lt;/filterchain>
  &lt;filelist dir="book/" listfile="book/PhingGuide.book"/>
&lt;/append></programlisting>
<acronym>

Used to indicate acronym in running text

<literal>

Used to indicate literal names in running text such as program variables, name of attributes, XML-elements etc.

<filename>

Used to indicate a file- or directory name in running text.

Table 6. Required attributes

Attribute Value Description
role dir Used when the filename is a directory

Example:

<filename role="dir">/etc/php5</filename>
<link>

Used to include a URL link to other sites or documents outside the manual.

Table 7. Required attributes

Attribute Value Description
xlink:href URL Link The link to an external reference

Example:

<link xlink:href="http://qbnz.com/highlighter/"
>GeSHi Homepage</link>
<xref>

A link to another part of the document. When the link is generated in the rendered document the name of the section, chapter or appendix that the link refers to is included literal.

Table 8. Required attributes

Attribute Value Description
xlink:href Internal reference to an ID element Internal links must be prefixed with a '#' character.

Example:

<xref xlink:href="#ch.projcomponents"/>
<table>

The CALS model for table should be used. The generated rendered version will be styled by the CSS stylesheet automatically. For this to work as expected for the required attribute for a task the columns needs to have the following names (they are used in the CSS sheets). The column width specified is not important since that will be overridden by the CSS stylesheets.

...
<colspec colname="name" colnum="1" colwidth="1.5*"/>
<colspec colname="type" colnum="2" colwidth="0.8*"/>
<colspec colname="description" colnum="3" colwidth="3.5*"/>
<colspec colname="default" colnum="4" colwidth="0.8*"/>
<colspec colname="required" colnum="5" colwidth="1.2*"/>
...

A CALS model table should have the following required nested elemenets. For more information on more advanced CALS formatting such as joining rows or columns please see Chapter 30. Tables in Bob Stayton's book "DocBook XSL: The Complete Guide - 4th Edition"

Table 9. Required nested elements

Attribute Description
title The descriptive title for the table.
tgroup Groups a set of columns together
colspec Defines the sizing of the table
thead Header row for table
tbody Body of table

Example:

<table>
    <title>Required attributes</title>
    <tgroup cols="3">
        <colspec colname="attribute"   colnum="1" 
                 colwidth="1.0*"/>
        <colspec colname="value"       colnum="2" 
                 colwidth="1.0*"/>
        <colspec colname="description" colnum="3" 
                 colwidth="1.0*"/>
        <thead>
            <row>
                <entry>Attribute</entry>
                <entry>Value</entry>
                <entry>Description</entry>
            </row>
        </thead>
        <tbody>
            <row>
                <entry>...</entry>
                <entry>...</entry>
                <entry>...</entry>
            </row>
            <row>
                <entry>...</entry>
                <entry>...</entry>
                <entry>...</entry>
            </row>
        </tbody>
    </tgroup>
</table>
<emphasis role="bold">

Should only be used when certain effects in flowing text are wanted that warrents the text to be rendered in a bold style to be shown as emphasised.

Example:

<emphasis role="bold">PH</emphasis>ing <emphasis 
role="bold">I</emphasis>s <emphasis
role="bold">N</emphasis>ot <emphasis 
role="bold">GN</emphasis>U make;

The above example will then be rendered as: "PHing Is Not GNU make;"

<application>

This tag is used to indicate the name of a application. The line between a command (marked with <literal>) and an application is not cut in stone but an application is usually a complex computer program with its own user interface. Examples of what we would mark as applications are "Emacs", "OpenOffice", "MatLab" etc.

This element is rarely used.