Andreas Aderhold, andi@binarycloud.com Alex Black, enigma@turingstudio.com Manuel Holtgrewe, grin@gmx.net Hans Lellelid, hans@xmpl.org Michiel Rook, mrook@php.net Johan Persson, johan162@gmail.com $Id$ Copyright 2002-2012, The Phing Project. This documentation is made available under the GNU Free Document License (see ) Copyright (c) 2002 - 2012, The Phing Group Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; This book is written using the DocBook 5 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 requires to extend or edit this documentation. However, XML tends to be quite verbose and even if a plain text editor technically is all you need 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 you write is a valid DocBook 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/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). For the writing of the book only a subset of all available DocBook elements are used as shown in 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). 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. 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 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. As of this writing it only contains one utility script "hlsaxon" which sets up a suitable environment to call the Saxon translator (a Java based XSL procesor) with highlighting enabled. In this script the path to the DocBook installed stylesheets must be correct and depending on your system they might need updating. 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 validate Validates all sources against the DocBook5 grammaar 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. The astute reader will notice the lack of target for Webhelp and as why the most useful target for a manual is omitted. The reason is that to get a good working Webhelp version a snapshot of the official XSL has been used. The latest official release of the DocBook XSL (as of this writing 1.76.1) is rather old and the Webhelp stylesheets have a few issues. Until 1.77.0 is out this target is not officially supported (but there is nothing that stops you from trying to generate that yourself by downloading the latest snapshot from DocBook sourceforge. A version of the Phing docs in Webhelp format is however available from the DocBook website. 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. 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. 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. 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. 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; 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. 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. 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. 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" 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.