Ashley J.S Mills

ashley@ashleymills.com

2002 The University Of Birmingham This section will detail how to install the tools required to validate and process XML DocBook documents. The tools that will be installed are; a bunch of tools and libraries called 'libxml', Saxon and FOP. The first will be used here to validate XML files and the latter two will be used to process XML files to produce other types of output. Another tool called a resolver will be installed to allow the tools to map links to files external to the computer being worked on to files local to the computer being worked on. This allows one to use the tools without an Internet connection and speeds up there execution. The documentation for the installation is written under the assumption that the reader has some experience of installing software on computers and knows how to change the operating environment of the particular operating system they are using. The documents entitled Configuring A Windows Working Environment and Configuring A Unix Working Environment are of use to people who need to know more. Within this tutorial the primary purpose for installing the libxml C library will be to gain access the tools that come with it. The tools provide the means to validate and transform XML files. In this tutorial, the program xmllint will be used to validate XML DocBook files before processing. The program xsltproc can be used to transform XML files. It is a program which uses XSLT. To install libxml on a Windows machine one needs to download the Windows binaries and libraries. These can be obtained from http://www.zlatkovic.com/pub/libxml/. Download the following: libxml2-2.6.2+.win32.zip libxslt-1.1.0.win32.zip iconv-1.9.1.win32.zip The three links shown immediately above may be broken since it is common practice to remove old versions from a download page when they are obsoleted. Goto http://www.zlatkovic.com/pub/libxml/ instead and download the libxml2..., libxslt..., and iconv... files with the highest version numbers. Some older versions are available in the directory oldreleases on that server, should one desire them. It is not necessary to extract the content of these zips entirely, instead the required functionality will be extracted. Create a suitable directory to contain the stuff that is about to be extracted. For example, on my home machine. If I am running a Windows system I have a directory called c:\tools which contains all the tools I install. Within c:\tools I have a directory called libxml that contains the stuff I want from these zips. Create a suitable directory to extract the desired content from the zips into. Extract the following files from the libxml archive into the directory. libxml2.dll xmllint.exe Extract the following files from the libxslt archive into the directory. libexslt.dll libxslt.dll xsltproc.exe Extract the following files from the iconv archive into the directory. iconv.dll iconv.exe Append \directory\you\just\unzipped\everything\to to the PATH environment variable. You might not use all the tools but they are worth having around in case you decide you need them. These files are probably already installed on your system, as most modern distributions of these operating systems use XML processing for some of the more popular components. But you may wish to get the latest versions, in which case, goto ftp://xmlsoft.org/ and get the latest libxml2 and libxslt. There are gzipped tars and RPMs available, download whichever you prefer. A list of the latest files at the time of writing is shown below: libxml2-2.4.25.tar.gz libxml2-2.4.25-1.i386.rpm libxml2-2.4.25-1.src.rpm libxslt-1.0.21.tar.gz libxslt-1.0.21-1.i386.rpm libxslt-1.0.21-1.src.rpm The ftp directory also contains devel versions of the software, this is for people who want to develop with libxml. FOP(Formatting Objects Processor) is used to transform FO files to files of other formats. In this tutorial it is used to transform FO output produced by xsltproc into PDF which is a well known format considered by many to be aesthetically pleasing. The Unix and Windows installation paths are very similar, the differences will be mentioned where appropriate. Download the latest version of the Fop application, from http://ftp.plig.org/pub/apache/dist/xml/fop/. Download the zip or tar with bin as a substring of its name to some suitable location. On Windows, append /directory/where/you/unzipped/fop/fop.bat to the PATH environment variable. On Unix, append /directory/where/you/unzipped/fop/fop.sh to the PATH environment variable. Jimi is needed if you want to use PNG images with FOP, download it from http://java.sun.com/products/jimi/# and open the archive. On Windows, rename JimiProClasses.zip from the archive to jimi-1.0.jar and place it in the /directory/where/you/unzipped/fop/lib directory. On Unix, rename JimiProClasses.zip from the archive to JimiProClasses.jarand place it in the /directory/where/you/unzipped/fop/lib directory. The DocBook DTD(Document Type Definition) contains rules which specify the structure of a valid DocBook document, for example, the order that elements may appear and valid attributes etc. If one has a document which one claims is written in DocBook, it is not written in DocBook unless it conforms to the DocBook DTD. The DTD is used by tools like xsltproc in transforming DocBook documents. DTD's are especially useful when one wants to validate a document to check that it conforms to the DTD one claims it conforms to. Validation is beneficial because a valid document is less likely to break processing tools (if a valid document does break a processing tool it is likely that the processing tool is broken and not the document). Hence, the DocBook DTD can be used to validate that a purported DocBook document really is a DocBook document. The latest version, at the time of writing, is called DocBook XML 4.2, it is distributed from http://www.docbook.org/xml/4.2/index.html. Download the zipped archive, http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip and unzip it to some suitable location. For example if I was running the Windows operating system I would unzip it to a directory like c:\lib\docbook-xml-4.2, this is the same as the name of the zip file. If I was running a Unix, Linux, or BSD operating system I would unzip it to a directory like /lib/docbook/docbook-xml-4.2. You might have noticed on the webpage or in the zip, other files apart from DTD files, these are auxiliary files and are necessary. When one writes a DocBook document in XML one inserts a DocType declaration at the top of the document to specify that the document is written in DocBook. This declaration specifies the version of DocBook being used with a PUBLIC ID in the declaration, a SYSTEM ID in the header specifies where one can find the DTD for DocBook. In the case of DocBook, usually this SYSTEM ID points to some location on the OASIS(Organization for the Advancement of Structured Information Standards) website because this is where DocBook's official home is. Some tools used for processing DocBook use the DTD at this location, this is no good when one wants to process a DocBook document on a computer that does not have Internet access or where accessing the Internet is undesirable. To overcome the necessity to access the Internet to process DocBook documents one can use a catalog file. A catalog file maps PUBLIC or SYSTEM IDs to alternate locations. Taking the example from above, one would process the DocBook document that contained the SYSTEM ID pointing to the Internet with a tool and specify a catalog file to use. The catalog file would map the SYSTEM ID pointing to the Internet to a copy of the DTD on the local system, thus circumventing the need for any Internet access. The DocBook zip that was just downloaded does actually contain it's own catalog file (catalog.xml. This does not seem to provide the desired functionality without modification. Instead of modifying that catalog file, create a new one called catalog in the docbook-xml-4.2 directory. Put the following content into it: <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <group xml:base="." prefer="public" > <public publicId="-//OASIS//DTD DocBook XML V4.2//EN" uri="file:///c:/lib/docbook-xml-4.2/docbookx.dtd"/> </group> </catalog> This maps the PUBLIC ID for DocBook XML V4.2 to a local copy of it's DTD. The example above was taken from a Windows system, modify the value of the uri attribute to point to the location of the DTD on your system. On a Unix system this could be file:///lib/docbook/docbook-xml-4.2/docbookx.dtd. The processing tools must know where this catalog file is in order to use the functionality it provides. This is achieved via an environment variable called XML_CATALOG_FILES, create this environment variable and make it point to the catalog file you just created. You could add similar entries to the catalog file shown above to map other DTDs you desire to use to local copies of their DTD's. XSL stylesheets dictate how a document written in XML should be transformed using XSLT to a particular output format. In the case of DocBook, Norman Walsh has already written, and regularly maintains some stylesheets for DocBook that provide rules for transformations from an XML DocBook document to the most commonly desirable output formats such as XHTML and PDF. The installation for Unix and Windows machines is the same. Download the latest stylesheets from http://sourceforge.net/project/showfiles.php?group_id=21935 and unzip the zip or gzipped tar to some suitable location. If I was running a Windows system I would use c:\lib\docbook-xsl\, if I was using a Unix system I would use c:\lib\docbook\docbook-xsl. The stylesheets are now ready to use. The output produced by the stylesheets mentioned above is reasonable but the stylesheets mentioned above are a standard distribution and as a consequence seem to be designed to cater for the needs of the many, which is sensible, unfortunately. One may modify the stylesheets directly but more often one creates a customisation layer which imports the standard stylesheets and then one overrides specific aspects of the standard stylesheets or adds extra functionality within the customisation layer according to ones tastes. I have created a customisation layer which looks good enough for standard applications and am offering it to download. This is particularly pertinent if you study at The University Of Birmingham because any documentation created by me there in DocBook uses this customisation layer, all the tutorials I have written conform to these stylesheets. If you your documents to have the same style as the tutorials then use this customisation layer. It is probably worth downloading the customisation layer anyway so you can see how one goes about creating a customisation layer. Here is the zipped customisation layer: custom-stylesheets.zip. Unzip the zip to where you want the customisation layer to be situated, this could be within the stylesheets directory or in separate directory. If you unzip it to the stylesheets directory the customisation layer will unzip into the directories common, fo and xhtml. If you unzip to a separate directory these directories will be created. Wherever you unzip the zip, it is important to change the references of the imports in the files so that they reflect the state of your system, the files fo/customfo.xsl, xhtml/customxhtml.xsl and xhtml/customchunk.xsl all have references that may need to be modified. For example, the file fo/customfo.xsl has the import line: <!-- Import standard fo style-sheet --> <xsl:import href="file:///c:/lib/docbook-xsl/fo/docbook.xsl"/> Change this to point to /where/you/put/the/stylesheets/fo/docbook.xsl Similarly, change the entry in customchunk.xsl to point to /where/you/put/the/stylesheets/xhtml/chunk.xsl and the entry in customxhtml.xsl to point to /where/you/put/the/stylesheets/xhtml/docbook.xsl. The advantage of unzipping the zip in the same location as the standard stylesheets is that the import links may be relative (the import links can always be relative assuming the stylesheets are on the same machine, but for clarity if I am using a different directory for the customisation stylesheets I will make the import references absolute). I have only provided customisations for FO and XHTML. It will become apparent how to use the customisation layer in the section on using the tools later. The provided customisations are listed below: fo/customfo.xsl - Use this to generate custom FO xhtml/customxhtml.xsl - Use this to generate custom XHTML (segmented) xhtml/customxchunk.xsl - Use this to generate custom XHTML (chunked) More information about customising stylesheets can be found at http://www.sagehill.net/xml/docbookxsl/. In order to check the syntactic accordance of a DocBook document with the DocBook DTD one may use xmllint. xmllint --valid --noout in.xml The --valid option specifies that xmllint should validate the document against the DTD and the --noout option specifies that no output should be produced if there are no errors, hence if the document being validated is valid, xmllint will exit silently. If the document is invalid xmllint will output an error similar to this: docbook.xml:1: error: Start tag expected, '< not found ?xml version="1.0" encoding='ISO-8859-15'?> ^ Which specifies that there is a missing start tag on line one. One can use the --loaddtd option to specify an external DTD to validate the file with. Also, the --nonet option can be useful to surpress fetching of DTDs files from the web if you find that your version does this by default and you don't want it too. xsltproc file:///path/to/docbook-xsl/xhtml/docbook.xsl in.xml > out.html This will produce a single XHTML file according to the XSL stylesheet specifications. xsltproc file:///path/to/docbook-xsl/xhtml/chunk.xsl in.xml This will produce a set of XHTML files of the document where each section is on a separate HTML page. The layout will accord to the XSL stylesheet specified. The separate files will be given unique names that correspond to the different sections of the book, e.g index.html, ar01s02.html and ar01s03.html. xsltproc file:///path/to/docbook-xsl/fo/docbook.xsl in.xml > out.fo This will produce output as an XSL FO(Formatting object), this is an intermediate file type that can be used by other programs to generate other types of output, such as PDF. In order to execute this conversion you will need to have generated XSL FO output by using xsltproc or some other tool capable of doing so. fop.bat in.fo out.pdf Substituting fop.sh for fop.bat on Unix derivatives. This will generate a PDF file named according to the name provided as the second argument. FOP will probably generate lots of warnings about un-implemented features whilst generating this output, this is normal and can be ignored. Assume that a file called test.xml has been created in XML DocBook. Assume that the stylesheets are located in a directory called /lib/docbook-xsl/ One would create XHTML output like this: xsltproc file:///lib/docbook-xsl/xhtml/docbook.xsl test.xml > test.html One would create PDF output in two steps, first create the FO output using xsltproc: xsltproc file:///lib/docbook-xsl/fo/docbook.xsl test.xml > test.fo Next, process the FO output with FOP to produce the PDF file: java org.apache.fop.apps.Fop test.fo test.pdf If you want to use the custom stylesheets you simply modify the stylesheet parameter so that it points to the custom stylesheet you want to use. Assuming an install of the customisation layer mentioned above in the same location as the standard stylesheets one could generate XHTML output that conformed to the custom stylesheet for XHTML like this: xsltproc file:///lib/docbook-xsl/xhtml/customxhtml.xsl test.xml > test.html Similarly, FO output could be produced. For the ultimate reference guide see DocBook: The Definitive Guide. A template for a DocBook article is shown below: <?xml version="1.0" encoding='UTF-8'?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <article> <articleinfo> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>2002</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <abstract> <para>Include an abstract of the article's contents here.</para> </abstract> </articleinfo> <sect1><title>Section 1</title> <para> blah blah blah </para> </sect1> <sect1><title>Section 2</title> <para> blah blah blah </para> </sect1> </article> The output produced in the following examples was produced using a customisation of the stylesheets hence output on systems not implementing the same customisations may differ. The reference page for the para element can be found here: http://www.docbook.org/tdg/en/html/para.html. para is one of the most commonly used elements of all the DocBook elements. para's can contain block elements such as itemizedlist and mediaobject and can contain almost all inline elements. There is some debate about whether or not it is best to separate block elements from para elements, it is probably better to do so however because some processing systems have problems processing block elements within para elements. An example of a para element containing some inline elements is shown below: <para> <quote>Behold the superfluous. They are always sick. They vomit their gall and call it a newspaper.</quote> - Friedrich Wilhelm Nietzsche, <citetitle>Twilight of the Idols</citetitle> </para> Looks like this: Behold the superfluous. They are always sick. They vomit their gall and call it a newspaper. - Friedrich Wilhelm Nietzsche, Twilight of the Idols The reference page for the programlisting element can be found here: http://www.docbook.org/tdg/en/html/programlisting.html. The programlisting element is used to display information that should be output verbatim, that is, white space is significant. An example is shown below: <programlisting> public class HelloWorld { public static void main(String args[]) { System.out.println(&quot;Hello World!&quot;); } } </programlisting> Is output as: public class HelloWorld { public static void main(String args[]) { System.out.println("Hello World!"); } } Notice the use of (&quot;) to represent the (") character, this is know as a character entity and is used to represent a character that is not allowed to be used directly in the document, this is because these characters are used by the XML part of the document for special purposes. These special characters are known as CDATA as apposed to PCDATA, the latter standing for Parsed Character DATA. If one wants to use lots of CDATA characters in a document then one can wrap the section in a CDATA section like this: <programlisting> <![CDATA[ One can get away with using lots of &&& """ ''' <<< >>> characters that would normally require being marked up as entities. ]]> </programlisting> Is displayed as: One can get away with using lots of &&& """ ''' <<< >>> characters that would normally have to be marked up as entities. For more information about the available entities see the next section. The following entities are provided for special characters, they must always be used unless they are used in a section that has been marked as a CDATA section. It is preferred to always use them in preference of CDATA sections however: CharacterEntity <&lt; >&gt; &&amp; "&quot; '&apos; The reference page for the screen element can be found here: http://www.docbook.org/tdg/en/html/screen.html. Often one wants to illustrate the use of a program or a commandline, the screen element is intended to mark content up as text that a user would see on a computer screen. An example is shown below: <screen> <userinput><command>java</command> org.apache.fop.apps.Fop <replaceable>in.fo</replaceable> <replaceable>out.pdf</replaceable></userinput> </screen> Is displayed as: java org.apache.fop.apps.Fop in.fo out.pdf The reference page for the ulink element can be found here: http://www.docbook.org/tdg/en/html/ulink.html. ulink is the DocBook equivalent of HTML's "<a href="...">blah blah</a>", an example is shown below: <para> <ulink url="http://www.oasis-open.org/committees/docbook/">http://www.oasis-open.org/committees/docbook/</ulink> </para> Displays as: http://www.oasis-open.org/committees/docbook/ The reference page for itemizedlist is here: http://www.docbook.org/tdg/en/html/itemizedlist.html. Itemized lists are standard bulleted lists and should be used where order of evaluation of the items of the list is not significant, ordered lists should be used where order of evaluation fot he items of the list are significant. An example use of itemized list is shown below: <itemizedlist> <listitem><para>Books</para> <itemizedlist> <listitem><para>Donald E. Knuth - The Art Of Computer Programming</para></listitem> <listitem><para>Nils J. Nilsson - Artificial Intelligence: A New Synthesis</para></listitem> <listitem><para>Pure Mathematics 2 - Geoff Mannall, Michael Kenwood</para></listitem> </itemizedlist> </listitem> <listitem><para>Games</para> <itemizedlist> <listitem><para>Chess</para></listitem> <listitem><para>Backgammon</para></listitem> <listitem><para>Noughs And Crosses</para></listitem> </itemizedlist> </listitem> </itemizedlist> Which looks like this: Books Donald E. Knuth - The Art Of Computer Programming Nils J. Nilsson - Artificial Intelligence: A New Synthesis Pure Mathematics 2 - Geoff Mannall, Michael Kenwood Games Chess Backgammon Noughs And Crosses The reference page for orderedlist is here: http://www.docbook.org/tdg/en/html/orderedlist.html. Ordered lists are used to specify a sequence of steps of which the order of evaluation is significant. The general form of an ordered list is like this: <orderedlist> <listitem><para>Action A<para></listitem> <listitem><para>Action B<para></listitem> </orderedlist> Which would look like this: Action A Action B One may also specify the type of enumeration that the list will display, there are five types of enumeration; arabic, loweralpha, lowerroman, upperalpha , upperroman. The type of enumeration is specified via the numeration attribute like this: <orderedlist numeration="arabic"> <listitem>...</listitem> . . . </orderedlist> The types of enumeration are shown below: Arabic: arabic arabic arabic Loweralpha: loweralpha loweralpha loweralpha Lowerroman: lowerroman lowerroman lowerroman Upperalpha: upperalpha upperalpha upperalpha Upperroman: upperroman upperroman upperroman These can be combined to make nested enumeration clearer: <orderedlist numeration="loweralpha"> <listitem> <para>Preparation</para> <orderedlist numeration="upperalpha"> <listitem><para>Chop tomatoes</para></listitem> <listitem><para>Peel onions</para></listitem> <listitem><para>Mash potatoes</para></listitem> </orderedlist> </listitem> <listitem> <para>Cooking</para> <orderedlist numeration="upperalpha"> <listitem><para>Boil water</para></listitem> <listitem><para>Put tomatoes and onions in</para></listitem> <listitem><para>Blanch for 5 minutes</para></listitem> </orderedlist> </listitem> <listitem> <para>Cleanup</para> <orderedlist numeration="upperalpha"> <listitem><para>Throw away scraps</para></listitem> <listitem><para>Clean side</para></listitem> <listitem><para>Wash hands</para></listitem> </orderedlist> </listitem> </orderedlist> Which looks like this: Preparation Chop tomatoes Peel onions Mash potatoes Cooking Boil water Put tomatoes and onions in Blanch for 5 minutes Cleanup Throw away scraps Clean side Wash hands One may also make the enumeration continue at lower nested levels by setting the continuation attribute to continues: <orderedlist> <listitem> <para>Do this</para> <orderedlist numeration="arabic"> <listitem><para>And this</para></listitem> <listitem><para>And this</para></listitem> <listitem><para>And this</para></listitem> </orderedlist> </listitem> <listitem> <para>And this</para> <orderedlist numeration="arabic" continuation="continues"> <listitem><para>And this</para></listitem> <listitem><para>And this</para></listitem> <listitem><para>And this</para></listitem> </orderedlist> </listitem> </orderedlist> Which looks like this: Do this And this And this And this And this And this And this And this Some stylesheets may define that nested lists are of a different numeration by default. Some common inline elements and their output are shown below: ExampleDisplays as <emphasis>Emphasised Text</emphasis>Emphasised Text <emphasis role="strong">A different type of emphasis</emphasis>A different type of emphasis <filename>blahblah.txt</filename>blahblah.txt <acronym>XML</acronym>XML <quote>blahblahblah<quote>blahblahblah Images are included in DocBook documents as illustrated below: <figure><title>blah</title> <mediaobject> <imageobject><imagedata fileref="blah.jpg" format="JPEG"/></imageobject> <textobject><phrase>Image description</phrase></textobject> </mediaobject> </figure> The overall encapsulating element is figure the reference page for which can be found at http://www.docbook.org/tdg/en/html/figure.html. The figure contains a mediaobject element which can occur on it's own too and may contain audioobject, caption, imageobject, objectinfo, textobject and videoobject elements. The reference page formediaobject is at http://www.docbook.org/tdg/en/html/mediaobject.html. imageobject is the type of mediaobject used to include an image and it's reference page can be found at http://www.docbook.org/tdg/en/html/imageobject.html. The item within the imageobject that handles the image is imagedata, it's reference page is at http://www.docbook.org/tdg/en/html/imagedata.html. The idea behind mediaobject is to provide a way to include media in many formats. It becomes the document processors job to decide which of the formats specified in the mediaobject to use in the particular output medium chosen. For example the mediaobject element may contain a PNG format imageobject for HTML output and a TIFF format imageobject for print output, there may also be a textobject providing a description of the image for an output format that does not have the capability to display images, for example, perhaps the document will be output in an audio format for people with sight problems. One does not have to encapsulate the mediaobject in a figure object but doing so allows one to provide a title and be able to have the figure listed in a list of figures at the beginning of the document. imagedata may be of the following formats: imageobject image formats The attribute format is thus required along with either fileref or entityref to reference the image: <mediaobject> <imageobject><imagedata fileref="frog.png" format="PNG"/></imageobject> <textobject><phrase>A frog</phrase></textobject> </mediaobject> A frog One could use stylesheets such that, in HTML rendered output, the phrase used in the textobject would become the alternative text in an image in the HTML. One can use multiple imageobjects for different output formats, for instance one may have an eps version of the image so that output can be generated with a processing chain that requires the image to be in this form. One could include different image formats for each of the desired output formats. The imagedata element has the useful attributes align and valign. align specifies how the image should be aligned horizontally and can be set to the values; center, left and right. valign specifies how the image should be aligned vertically and can be set to the values; bottom, middle and top. There are two elements used for placing tables inside a DocBook document, table and informaltable, the only difference between the former and the latter is that the former requires a title and the latter does not. <table><title>title</title> <informaltable> . . . or . . . </table> </informaltable> The table contains an attribute called frame which specifies how the table should be framed: <table frame="frametype"><title>frame="frametype"</title> <tgroup cols="1"> <thead> <row><entry>a1</entry><entry>b1</entry><entry>c1</entry></row> </thead> <tbody> <row><entry>a2</entry><entry>b2</entry><entry>c2</entry></row> <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row> </tbody> </tgroup> </table> Where frametype is replaced with one of all, bottom, none, sides, top or topbot:

The output above is PDF, with HTML all the tables look the same as the one with attribute all apart from the one with attribute none which has no frame at all. The attributes colsep and rowsep are used to control whether lines should be drawn between columns and rows respectively: <table colsep="0" rowsep="0"> ... </table> <table colsep="0" rowsep="1"> ... </table> <table colsep="1" rowsep="0"> ... </table> <table colsep="1" rowsep="1"> ... </table> Unfortunately at the time of writing the tools used to convert FO to PDF either did not yet implement this feature or were in a broken state with regards to this feature so no pictorial examples can be provided. Other table attributes are discussed at http://www.docbook.org/tdg/en/html/table.html. The generic layout for a table is as follows: <table><title>title</title> <tgroup cols="3"> <thead> <row><entry>blah</entry></row> </thead> <tbody> <row><entry>blah</entry></row> </tbody> <tfoot> <row><entry>blah</entry></row> </tfoot> </tgroup> </table> tgroup contains the rest of the table which must contain a tbody element which specifies which data is in the body of the table. The tbody element may be empty with the table being included in thead or tfoot but this is not the intention. The reason for the thead and tfoot elements is so that different layouts can be applied by the stylesheets for the header and the footer of the table respectively. So usually the first row would be wrapped in a thead element. tgroup has the mandatory attribute cols which specifies the number of columns the table has. tgroup may also specify alignment of content via the align attribute, where alignment is either left, center or right: <table frame="all"><title>align="alignment"</title> <tgroup cols="3" align="alignment"> <tbody> <row><entry>a2</entry><entry>b2</entry><entry>c2</entry></row> </tbody> </tgroup> </table>

For more information about the tgroup element see http://www.docbook.org/tdg/en/html/tgroup.html. A row consists of a number of entry elements which are entered in the sequence they should appear in each table row, for more information about the row element see http://www.docbook.org/tdg/en/html/row.html. The entry element has some interesting attributes which allow an entry to span more than one column or row, they are (namest & nameend) and morerows respectively. The morerow attribute specifies how many more rows the entry it is applied to should span: <table frame="all"><title><emphasis>morerows</emphasis> example</title> <tgroup cols="3"> <tbody> <row><entry morerows="2">a1</entry><entry>b1</entry><entry>c1</entry></row> <row><entry>b2</entry><entry>c2</entry></row> <row><entry>b3</entry><entry>c3</entry></row> </tbody> </tgroup> </table>

Unfortunately there is no morecolumns attribute, instead one has to use namest to specify the starting column of the entry and nameend to specify the ending column of the entry. The value applied to this attribute is the name of the columns, columns are named using the colspec element, colspec elements are inserted inside tgroup but before thead, tbody and tfoot: <table frame="all"><title>column spanning</title> <tgroup cols="3"> <colspec colname="col1"/> <colspec colname="col2"/> <colspec colname="col3"/> <tbody> <row><entry namest="col1" nameend="col3">a1</entry></row> <row><entry>a2</entry><entry>b1</entry><entry>c1</entry></row> <row><entry>a3</entry><entry>b2</entry><entry>c2</entry></row> </tbody> </tgroup> </table>

More information about the entry element can be found at http://www.docbook.org/tdg/en/html/entry.html. Tables may be nested to a level of one, see http://www.docbook.org/tdg/en/html/entrytbl.html. For the entire source and output pertaining to the examples discussed in this section see Table Examples. DocBook: The Definitive Guide http://www.docbook.org/tdg/en/html/docbook.html Using the DocBook XSL Stylesheets http://www.sagehill.net/xml/docbookxsl/. Setting Up A Free XML/SGML DocBook Editing Suite For Windows And Unix