What now follows is exemplary DocBook-XML code that shows some of the text elements commonly used in technical documentation. Of course this sequence of examples is hardly complete but it should suffice to produce a "well-formed" DocBook-XML document of adequate diversity.
DocBook-XML provides several document types that prearrange and restrict the textual elements that may be contained therein. From this rich set the mostly used types article and book will be shown.
Articles are very good for the kind of documentation that is sharply related to a specific topic that has a limited scope (you wouldn't want to explain the world in an article). Nevertheless articles can be arbitrarily complex but for large scale documentation the book document type would be more suitable.
Articles are structured in cascading sections.
Example 3-1. Article
<?xml version="1.0" encoding='ISO-8859-1'?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "/usr/share/sgml/db41xml/docbookx.dtd" [ <!ENTITY version "0.01"> <!ENTITY dx "DocBook-XML"> ]> <article> ... <section> ... <section> ... ... </section> ... </section> ... </article> |
The lines in the example above can be used "as is" via cut-and-paste but the following lines deserve some explanation.
DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
This line defines the document to be of type article. The uppermost hierarchy level in the document must be of the same type. Furthermore it defines the DTD to be used.
"/usr/share/sgml/db41xml/docbookx.dtd"
XML requires to mention the path to the file containing the DTD.
<!ENTITY dx "DocBook-XML">
ENTITYs are some kind of macros in XML. The line above defines a macro dx that expands to "DocBook-XML". To do so it is sufficient to write "&dx;" anywhere in the text.
<article></article>
These are the start and end tags of the uppermost element level in the document. This uppermost level must match the type given in the DOCTYPE line above.
Despite the fact that the audience of this document is very unlikely to write a book in DocBook-XML the book doctype may be the type of choice if the document to be written is of more complex nature. The book doctype implies automatic generation and printing of a table-of-contents and several indexes which is very convenient with documents of larger size. (There may be other differences I don't know yet).
Books are structured in chapters containing cascading sections.
Example 3-2. Book
<?xml version="1.0" encoding='ISO-8859-1'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "/usr/share/sgml/db41xml/docbookx.dtd" [ <!ENTITY version "0.01"> <!ENTITY dx "DocBook-XML"> <!ENTITY ds "DocBook-SGML"> ]> <book> ... <chapter> ... <section> ... <section> ... ... </section> ... </section> ... </chapter> ... </book> |