Both document types mentioned above may contain a rich set of textual elements that can be combined according to the rules of the DocBook-DTD to form the final document. Unfortunately it is impossible to explain in short the hierarchical dependencies of these elements in a manner of "Element x may be embedded only into element y". The rules implied by the use of a very elaborated DTD like DocBook-XML are by far too complex to be illustrated at a glance. The only solution is to use an adequate tool like emacs/psgml that supports the author with this task. Another way to get around that is to cut-and-paste from an existing document but even this might lead to a violation of the DTD-rules if the destination has a structure different from the source.
Most of the textwork being done usually implies sections and paragraphs. Paragraphs are exactly what everyone associates with this notation: Portions of continuous text with a little space before and after the text. It is important to know that any line breaks within the text flow of a paragraph are completely ignored for the final layout. The text is formatted is if no line breaks were present. More than one paragraph may be embedded into the upper level element.
Sections are an instrument to establish a hierarchical order in the text to be written. Sections may be recursively embedded which leads to the structure of the document. They are automatically enumerated in the final text and (optionally) a table-of-contents is created.
Example 3-3. Sections And Paragraphs
The following example shows a cut-out from the beginning of this document.
<?xml version="1.0" encoding='ISO-8859-1'?> ... <chapter> <title>Introduction</title> <para> This document has been written by the author while he was ... contributions are welcome to <email>thomas.roelz@suse.de</email>. </para> <section> <title>What This Document Is</title> <para> The following text gives a <emphasis>very</emphasis> ... writing his first DocBook document. </para> <para> The audience of this document are the hackers of the ... a much more complicated strategy. </para> </section> <section> <title>What This Document Is Not</title> <para> Meant to be used as a kickstart into the matter... </para> </section> </chapter> ... |
An itemized list is a list with some sort of symbol preceding each element of the list (elsewhere called bulleted list). It is suitable for listing several items in loose order.
Example 3-4. Itemized list
<?xml version="1.0" encoding='ISO-8859-1'?> ... <itemizedlist> <listitem> <para> A list item. </para> </listitem> <listitem> <para> Another list item. </para> </listitem> <listitem> <para> Once more a list item. </para> </listitem> </itemizedlist> ... |
This example looks like this:
A list item.
Another list item.
Once more a list item.
An ordered list is a list with a number preceding each element of the list (elsewhere called numbered list). It is suitable for listing several items in definitive order.
Example 3-5. Ordered list
<?xml version="1.0" encoding='ISO-8859-1'?> ... <orderedlist> <listitem> <para> The first item. </para> </listitem> <listitem> <para> The second item. </para> </listitem> <listitem> <para> The third item. </para> </listitem> </orderedlist> ... |
This example looks like this:
The first item.
The second item.
The third item.
The following simple table is suitable for showing "straight" table content. The entries in the <thead> element are the column headings.
In the <tgroup> tag there are some attributes used to define the layout of the table:
cols="4"
Defines the number of columns whereas the number of rows is given by the number of row definitions.
align="center"
Defines the element content to be printed centered.
The <colspec colwidth="..."/> tags specify the column width. The meaning of the numbers depends on the output format so that some try-and-error is necessary again. If these tags are omitted all columns get the same witdth.
If the table contains a title the table is automatically enumerated.
Note: Obviously tables are somewhat difficult to format for the conversion programs. If a table lies on the top of a page or if a dynamic page break calculated during format conversion lies whithin a table it may be messed up.
That is especially true if it has a title embedded like the one below. In such a case one may try the title-less variant <informaltable> instead (if that is an option).
Example 3-6. Simple Table
<?xml version="1.0" encoding='ISO-8859-1'?> ... <table frame="all"> <title>Simple Table</title> <tgroup cols="4" align="center"> <colspec colwidth="100"/> <colspec colwidth="90"/> <colspec colwidth="80"/> <colspec colwidth="70"/> <thead> <row> <entry>Col 100</entry> <entry>Col 90</entry> <entry>Col 80</entry> <entry>Col 70</entry> </row> </thead> <tbody> <row> <entry>Element 1,1</entry> <entry>Element 1,2</entry> <entry>Element 1,3</entry> <entry>Element 1,4</entry> </row> <row> <entry>Element 2,1</entry> <entry>Element 2,2</entry> <entry>Element 2,3</entry> <entry>Element 2,4</entry> </row> <row> <entry>Element 3,1</entry> <entry>Element 3,2</entry> <entry>Element 3,3</entry> <entry>Element 3,4</entry> </row> </tbody> </tgroup> </table> ... |
This example looks like this:
A screen is suitable for printing listings, ASCII-file content or the screen output of programs etc. The formatting to be found in the XML source is kept as is and the font is different from normal paragraphs. In some destination formats (e.g. HTML) the text region also has another background color.
The overall size of the text region is determined by the width attribute that "shrinks" the whole region (including the font) to a specific value.
Example 3-7. Screen
<?xml version="1.0" encoding='ISO-8859-1'?> ... <screen width="80"> [tom@simpson] 896 / $> ls -l insgesamt 195 drwxrwxrwx 5 root root 4096 Okt 16 2001 Export drwxr-xr-x 3 root root 4096 Jun 14 14:58 abuild drwxr-xr-x 2 root root 4096 Apr 3 15:48 bin drwxr-xr-x 2 root root 4096 Apr 3 17:48 boot lrwxrwxrwx 1 root root 12 Apr 3 16:05 cdrom -> /media/cdrom drwxr-xr-x 29 root root 49152 Mai 21 15:46 dev </screen> ... |
This example looks like this:
[tom@simpson] 896 / $> ls -l insgesamt 195 drwxrwxrwx 5 root root 4096 Okt 16 2001 Export drwxr-xr-x 3 root root 4096 Jun 14 14:58 abuild drwxr-xr-x 2 root root 4096 Apr 3 15:48 bin drwxr-xr-x 2 root root 4096 Apr 3 17:48 boot lrwxrwxrwx 1 root root 12 Apr 3 16:05 cdrom -> /media/cdrom drwxr-xr-x 29 root root 49152 Mai 21 15:46 dev |
Importing graphics is possible with very many formats in DocBook-XML in a convenient way. However if the DocBook-XML file shall be processed by jade_dsl (e.g. using docbook-toys) all this is rather disappointing. Most graphics formats are leading to error messages during the conversion process. It's unknown at the moment if this is due to shortcomings in jade or in docbook-toys. PNG has proven to work with PDF and HTML but anything else is subject to try-and-error. Further investigation has to be made regarding those problems.
Additionally the DocBook-XML scaling facility using a given width or depth does not work. Only scaling with absolute factors is possible as shown below. So it is again a matter of try-and-error to achieve a specific result.
Note: The enclosing figure-tag is optional and can be left out. However the figure-tag allows for assigning a title to the picture that is also incorporated into an automatically generated figures index.
Example 3-8. Importing Graphics
<?xml version="1.0" encoding='ISO-8859-1'?> ... <figure> <title>Imported Graphics</title> <mediaobject> <imageobject> <!-- Formats OK: PNG --> <imagedata fileref="./learnxml.png" scale="80"/> </imageobject> <caption> <para> An imported graphics file scaled to 80% of its original size. </para> </caption> </mediaobject> </figure> ... |
This example looks like this:
Notes are printed inline at exactly the location where they are in the source.
Example 3-9. Note
<?xml version="1.0" encoding='ISO-8859-1'?> ... <note> <para> The text of a note is printed inline. </para> </note> ... |
This example looks like this:
Note: The text of a note is printed inline.
Depending on the document type (book, article) and the destination format footnotes are printed on the bottom of the page, at the end of the chapter or at the end of the document.
Example 3-10. Footnote
<?xml version="1.0" encoding='ISO-8859-1'?> ... <footnote> <para> This text is printed near the end of whatever. </para> </footnote> ... |
This example looks like this: [1]
A warning is a warning text that is formatted in a special way depending on the destination format.
Example 3-11. Warning
<?xml version="1.0" encoding='ISO-8859-1'?> ... <warning> <para> The text of a warning. </para> </warning> ... |
This example looks like this:
Warning |
The text of a warning. |
A caution is a warning text that is formatted in a special way depending on the destination format. In contrast to the warning a title must be given that is printed instead of "Warning".
Example 3-12. Caution
<?xml version="1.0" encoding='ISO-8859-1'?> ... <caution> <title>The title of a caution</title> <para> The text of the caution. </para> </caution> ... |
This example looks like this:
The title of a caution |
The text of the caution. |
A reference to another text location can be integrated into the text. Depending on the destination format it is printed in an suitable format and furthermore may be functional when displayed with a viewing tool capable of hyperlinking (e.g. acrobat reader for PDF).
Example 3-13. Reference (source)
<?xml version="1.0" encoding='ISO-8859-1'?> ... <para> The following reference points to a chapter: (see <xref linkend="id_references"/>) Try it! </para> ... |
This example looks like this:
The following reference points to a chapter: (see Chapter 5) Try it!
The linkend attribute has to defined somewhere in the text as shown below.
Example 3-14. Reference (destination)
<?xml version="1.0" encoding='ISO-8859-1'?> ... <chapter id="id_references"> <title>References</title> ... |
Note: Assigning an ID to chapters and sections as shown above has another benefit if the source shall be converted to HTML. Normally during conversion the source is split up into several HTML-files that are named dynamically. This naming may change after the source has been modified and converted anew which in turn may result in dead-end reader-bookmarks.
If IDs are assigned to chapters and sections the resulting files are named after these IDs resulting in stable reader-bookmarks.
A web-URL can be integrated into the text. Depending on the destination format it is printed in an suitable format. If the destination format is capable of being displayed in a web-browser the URL is also functional.
Example 3-15. Web-URL
<?xml version="1.0" encoding='ISO-8859-1'?> ... <ulink url="http://www.oreilly.com/homepages/jasper/DocBook/over.htm"> http://www.oreilly.com/homepages/jasper/DocBook/over.htm </ulink> ... |
This example looks like this: http://www.oreilly.com/homepages/jasper/DocBook/over.htm
[1] | This text is printed near the end of whatever. |