1.4 DocBook

1.4 DocBook
Prev	Chapter 1 About this book	Next

All Phing reference documentation is written using the DocBook5 XML markup (see DocBook Project). The main advantage with DocBook is that it is a single source but multiple outputs. These document sources can be rendered into many possible output formats such as (X)HTML, PDF, EPub, Webhelp, RTF, Text and many more. Another advantage, inherit with the text based XML format, is that the document sources are all completely text based written using UTF-8 encoding. Only a plain text editor is required to extend or edit this documentation.

However, XML tends to be quite verbose and even if a plain text editor technically is all that is needed the actual entering of text will be made much easier with custom XML editor. These editors can be used to hide the XML tags and do auto-completion and on-the-fly validation to make sure that what is written is a valid DocBook5 document.

To work with the documentation we recommend to use one of the free XML/DocBook aware editors available. For example

Emacs with the nXML mode (see nXML mode)
Serna Free, (Free of charge) A Java based XML editor with extended support for DocBook5 (see Serna Free - Open Source XML Editor)
XMLMind XML Editor, Personal Edition (Free of charge), A java based XML editor with extended support for DocBook5 (see XMLMind Personal Edition)

The sources for the documentation are included under the docs/ directory. The DocBook sources are split into several files in order to make it more maintainable using the XML standard XInclude (see XML Inclusions (XInclude) Version 1.0).

For the writing of the book only a subset of all available DocBook elements are used as shown in Section 1.4.4, “DocBook v5 elements used in the manual and their meaning”

As of this writing the build process has been validated using version 1.78.1 of the DocBook5 stylesheets.

Important

Make sure all documentation is written using UTF-8 text encoding.

1.4.1 Building the documentation

In order to build the documentation it is necessary to have the DocBook5 XSL stylesheets installed together with "xsltproc" which is used to transform the source into various output formats. In addition, to build the versions (either HTML or PDF) that supports highlighting of included source (within the <programlisting> element) the Saxon 6.5.5 XSL processor must be used. This is necessary since the syntax highlighting in DocBook is based on a Java extension (xslthl-2.x.x) which requires a Java based processor (such as Saxon).

Tip

The easiest way to setup a complete build environment for DocBook5 for people new to DocBook is to install a clean version of Debian 7.x and then run the "deb-setup.sh" shell script. This will create a fully tested and working build environment for DocBook5 as it is used with Phing. This could easily be done using a virtual setup (for example using VirtualBox).

All DocBook is structured in a tree:

.
├── source
│   ├── appendixes
│   │   └── optionaltasks
│   └── chapters
└── stylesheets
    ├── css
    │   └── img
    └── xsl
        └── images

All document sources are stored under the subdirectory "source" and the master document is aptly named "master.xml". This document pulls in all chapters and appendixes in the right order. For example, new tasks added must be documented in a new file inside "source/appendixes/optionaltasks/", then a reference should be added in "source/appendix/optionaltasks.xml". Look at the existing tasks and follow the same structure.

Important

In order to get highlighting to work both the "xslthl-2.x.x.jar" package must be installed as well as Saxon 6.5.x. The jar file must be installed somewhere in the CLASSPATH , for example "/usr/share/java" if you run this on Linux. The xslthl package is available on SourceForge, please see XSLT syntax highlighting. By using the automated setup for Debian 7.x all these dependencies will be taken care of!

The customized stylesheets used are stored under "stylesheets" which uses one sub-folder for the customized XSL stylesheets (responsible for the transformation from DocBook to the chosen output format) and one sub-folder for the CSS stylesheets used to give the generated HTML documents there "look & feel".

Finally the "scripts" directory stores utility scripts. This currently contains two scripts, deb-setup.sh and "hlsaxon". The first scripts helps to create a full build environment for DocBook5 starting with a clean Debian 7 installation. This is meant to help people new to DocBook5 to get a working build environment as easy as possible. This script takes care of all detailed setup and will make a fulloy working DocBook5 build environment out-of-the-box.

The second script (hlsaxon) is wrapper file used from the buildfiles to call the Saxon translator (a Java based XSL procesor) with highlighting enabled and suitable paths to supporting libraries In this script the path to the DocBook installed stylesheets must be adjusted depending on your system (unless the automated setup have been used - with the deb-setup.sh file which takes care of that setup automatically). Mutatis mutandis.

In order to drive the transformation a Phing build script is available in the docbook root, build.xml. The build script supports the following public targets

 all*         Builds all available targets (default)
 chunk        Builds the chunked HTML
 clean        Removes all output files
 epub         Builds the EPUB version
 hlhtml       Builds the HTML version with syntax highlight
 hlpdf        Builds the PDF version with syntax highlight
 html         Builds the HTML version
 htmlfancy    Builds the HTML version with an alternative styling for screen output
 pdf          Builds the PDF version
 webhelp      Builds the webhelp version (Note: This requires Java and Ant
              to be installed!)
 validate     Validates all sources against the DocBook5 grammar

All generated output is stored under the directory "output" (which is created if it doesn't exist) with a subdirectory corresponding to the name of the chosen output format.

1.4.2 Template for new tasks

For creating documentation for new tasks the easistes thing is to use the included template template_for_tasks.xml which is a skeleton tasks with all commonly used elements. This will ensure a correct setting of all attributes. The skeleton can then be added to a suitable appendix as needed.

Note

All new task description should go into one of the Appendices.

1.4.3 Customization of the look & feel of the rendered outputs

Note

The following section is only meant for the maintainers that work on the core layout of the official Phing manual and is not necessary for developers adding documentation for new tasks of improving documentation for existing tasks.

Furthermore, by necessity this assumes a rudimentary knowledge of Docbook5 bubild process and what XSL and CSS stylesheets are. It is not possible in this short space to give a full description of that setup.

XSL Customization layer

All DocBook5 renderings are started from one of the customized XSL stylesheet under "stylesheets/xsl" . All commonly adjusted properties should go into the appropriate stylesheet for that rendering. No properties should be passed on via the command line. To keep the customization layer as future proof as possible only in very rare circumstances should any cores XSL templates be copied and modified. As usual the recommended way is to use the provided hooks.

CSS styelsheets

The CSS stylesheets are used to create the look & feel for the HTML based renderings. These are entirely standard CSS files which by design are kept very simple. It should be noted that a few styling option depends in turn of the modified XSL transformations in the XSL customization layer. This had to be done in order to gain some more detialed control not provided by DocBook5 out-of-the-box.

Webhelp

The webhelp output rendering is a bit of a special case. This rendering depends not only on DocBook5 but also on Java as well as Ant build processor. These dependencies are inherited from the official DocBook5 webhelp process and will remain. Unfortunately adjusting the look & fell for this rendering is not as simple as for the other outputs since a fair amount of the layout (as well as look & feel) are hard-coded in the Webhelp build system. While it is perfectly possible to adjust the hard coded values and design choises it is not future proof. Since the Webhelp rendering is the newest and fastest improving output from DocBook the intention for the Phing documentation is to track these improvements and not spend time ourself to duplicate this effor with a parallell development.

1.4.4 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.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 1.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 1.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 1.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 <

Table 1.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">
  <append
   destFile="${process.outputfile}">
  <filterchain>
    <xsltfilter style="${process.stylesheet}">
         <param name="mode"
         expression="${process.xslt.mode}"/>
    </xsltfilter>
  </filterchain>
  <filelist dir="book/"
  listfile="book/PhingGuide.book"/>
</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 1.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 1.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 1.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 1.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.

Prev	Up	Next
1.3 License	Home	Chapter 2 Introduction