# 1.4 DocBook All Phing reference documentation is written using the DocBook5 XML markup (see [DocBook Project](http://docbook.sourceforge.net/)). 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](http://www.thaiopensource.com/nxml-mode/)) - Serna Free, (Free of charge) A Java based XML editor with extended support for DocBook5 (see [Serna Free - Open Source XML Editor](http://www.syntext.com/products/serna-free/)) - XMLMind XML Editor, Personal Edition (Free of charge), A java based XML editor with extended support for DocBook5 (see [XMLMind Personal Edition](http://www.xmlmind.com/xmleditor/persoedition.html)) The sources for the documentation are included under the `docs/docbook5` 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](http://www.w3.org/TR/xinclude/)). For the writing of the book only a subset of all available DocBook elements are used as shown in [Section聽1.4.4](ch01s04.html#sec.docbookelements "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 sources are structured in a tree under `docs/docbook5`. The top level is the language of the manual. As of this writing only an English manual is available and hence the only top level directory available is "`en`". Under this directory the following structure applies (also for any new language translation that is added): ``` |-- scripts |-- source |聽聽 |-- appendixes |聽聽 `-- 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 should normally be documented in the "`appendix/optionaltasks.xml`" file. 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](http://sourceforge.net/projects/xslthl/). 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 AttributeValueDescription`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 ElementValue`<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 AttributeValueDescription`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 sectionThe 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 ElementValue`<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 AttributeValueDescription`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 AttributeValueDescriptionroledirUsed 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 AttributeValueDescription`xlink:href`URL LinkThe 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 AttributeValueDescription`xlink:href`Internal reference to an ID elementInternal 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](http://www.sagehill.net/docbookxsl/CellSpans.html) in Bob Stayton's book ["DocBook XSL: The Complete Guide - 4th Edition"](http://www.sagehill.net/docbookxsl/) Table 1.9:聽Required nested elements AttributeDescriptiontitleThe descriptive title for the table.tgroupGroups a set of columns togethercolspecDefines the sizing of the tabletheadHeader row for tabletbodyBody 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: "**PH**ing **I**s **N**ot **GN**U 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.