Using DocBook at CERN
work in progress
Copyright © 1997-2000, 2001-2002 David Rugge, Mark Galassi, Eric Bischoff, Michel Goossens
This document can be freely redistributed according to the terms of the GNU General Public License.
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; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
| Revision History | ||
|---|---|---|
| Revision 0.0 | 2001-07-21 | michel.goossens@cern.ch |
| Initial version, started from DocBook-Intro.xml written by Mark Galassi (Cygnus) and crash-course of David Rugge, Mark Galassi, Eric Bischoff | ||
| Revision 0.3 | 2002-03-05 | michel.goossens@cern.ch |
| Start clean up source | ||
| Revision 0.4 | 2002-03-21 | michel.goossens@cern.ch |
| First public release with many additions for CERN | ||
| Revision 0.5 | 2002-07-24 | michel.goossens@cern.ch |
| Change to use version 4.2 of DocBook DTD throughout | ||
Abstract
This document is a tutorial on how to write documentation in DocBook, and generate HTML and PDF from the XML sources. The description of the DTD elements is general in nature, whereas some tools and the location of system files relate to the CERN XML set-up.
This material is based in part on "A crash-course in DocBook", which was itself created from a fusion of three documents:
the "Introduction to DocBook" by Mark Galassi
the "KDE crash-course to DocBook" by David Rugge
parts of Eric Bischoff's tutorial about DocBook
I have freely adapted the above material to CERN, and have complemented it in many places. On the other hand, for reasons of maintainability, I have completely eliminated all references to SGML and DSSSL, since at CERN I only want to maintain the XSLT stylesheets to render DocBook source material.
Table of Contents
- 1. XML and DocBook
- 1.1. DocBook
- 1.2. A few words about XSLT
- 1.3. Presentation of the DocBook XML Tools installed at CERN
- 1.4. My First DocBook File
- 1.5. Translation to HTML
- 1.6. What about those Style Sheets?
- 1.7. Translation to PDF
- 1.8. Anatomy of a DocBook Tag
- 1.9. The Structure of a DocBook File
- 1.10. The Document Type Declaration
- 2. Meta Information
- 3. Lists
- 3.1. The simplelist
- 3.2. The itemizedlist
- 3.3. The orderedlist
- 3.4. The variablelist
- 3.5. The segmentedlist
- 3.6. qandaset
- 3.7. Procedures
- 4. Tables
- 5. Graphics
- 6. Links
- 7. Describing the Application's Interface
- 7.1. Examples
- 7.2. GUI Interface Elements
- 7.3. Command Line Elements
- 7.4. Elements for classes and methods
- 7.5. Describing an API
- 8. Bibliograpy elements
- 8.1. Handling
- 9. Miscellaneous
- 9.1. Labelling Tags
- 9.2. Formatting Tags
- 9.3. Warnings, Tips, and Notes
- 10. If you want to know more
- A. Emacs PSGML mode tips
- B. A complete example of a DocBook article
- Glossary
- C. Overview of all DocBook elements
- Index
List of Figures
- 1.1. PDF rendering of a small DocBook test file
- 8.1. Citations and bibliography (PDF output)
- 8.2. Citations and bibliography (Displayed by the Mozilla browser)
- A.1. Emacs and its psgml mode with the DocBook DTD
- B.1. DocBook example with MathML translated into PDF
- B.2. DocBook example with MathML translated into HTML and viewed with Mozilla (one file)
- B.3. DocBook example with MathML translated into HTML and viewed with Mozilla (chunked file)
List of Tables
List of Examples
- 1.1. My first simple DocBook file
- 1.2. Running docbook2html (single output file)
- 1.3. HTML version generated from a DocBook file as displayed by lynx
- 1.4. Running docbook2html with the chunk option
- 1.5. A small DocBook file showing the use of attributes
- 1.6. Generating PDF with docbook2pdf
- 1.7. Chapters and sections
- 1.8. Entities used to share text
- 1.9. HTML version generated from a DocBook file as displayed by Lynx
- 1.10. Including external files using entities
- 2.1. DocBook metainformation
- 3.1. A simplelist
- 3.2. An itemizedlist
- 3.3. An orderedlist
- 3.4. A variablelist
- 3.5. A segmentedlist
- 3.6. A qandaset
- 3.7. A procedure list
- 4.1. A regular simple table
- 4.2. A simple informal table (no title)
- 4.3. A more complex table
- 5.1. An inline media object
- 5.2. A screenshot
- 6.1. Five kinds of links
- 7.1. An example
- 7.2. A BASIC Example
- 7.3. Displaying markup in a CDATA section
- 7.4. CDATA sections and markup
- 7.5. guimenu and shortcut
- 7.6. A command and its output
- 7.7. A commandsynopsis
- 7.8. Class synopsys
- 7.9. Describing a function in a C library API
- 8.1. Example of A bibliography and citations
Table of Contents
- 1.1. DocBook
- 1.2. A few words about XSLT
- 1.3. Presentation of the DocBook XML Tools installed at CERN
- 1.4. My First DocBook File
- 1.5. Translation to HTML
- 1.6. What about those Style Sheets?
- 1.7. Translation to PDF
- 1.8. Anatomy of a DocBook Tag
- 1.9. The Structure of a DocBook File
- 1.10. The Document Type Declaration
The aim of this chapter is to give the reader an introduction to XML and one of its best-known vocabularies, DocBook.
The DocBook markup system is described in the printed book DocBook - The Definitive Guide [ TDG1999]. There is an up-to-date local HTML copy at CERN [ TDG2002]. For maximal efficiency, this tutorial must thus be used along with the above reference documentation. Indeed, by far not all of the (almost) 400 DocBook elements are covered. Hence, the complete list, as well as to all available attributes and entity sets, are explained in that reference document. This present tutorial mainly limits itself to the principles of the DocBook markup language. With the help of examples we introduce you to the use of the rich DocBook element tag set.
There are two DocBook-related discussion lists, one about Docbook itself [DBLIST] and one about its applications [DBAPPSLIST].
DocBook is already more than ten years old. It began in 1991 as a joint project of HaL Computer Systems and O'Reilly. Its popularity grew, and in 1994, the Davenport Group became an officially chartered entity responsible for DocBook's maintenance. DocBook V1.2.2 was published at that time. In mid-1998, it became a Technical Committee (TC) of the Organization for the Advancement of Structured Information Standards (OASIS).
DocBook V3.1 was released in February 1999, and was, like its previous versions SGML only. In February 2001, when DocBook V4.1 and DocBook XML V4.1.2 became an OASIS Standard support SGML and XML is now available on an equal basis. More details are on the OASIS DocBook history Web page. The current V4.2 DTD versions for both XML and SGML were released in July 2002. Version 5 is foreseen to become available at the beginning of 2003.
The OASIS TC observes a very cautious policy regarding changes to the DTD. Backward-incompatible changes can only be introduced in major releases (4.0, 5.0, 6.0, and so on), and only if the change was described in comments in the DTD in the previous major release. In particular, the next version of DocBook, 5.0, will be XML compliant, and this will introduce a lot of changes.
DocBook has a very rich element set, is freely available, well documented, and comes with a good set of production tools, DocBook has become wide spread and has been adopted by many producers of software (open source as well as commertial), by students, and faculty for courses and theses, and by document managers everywhere. The following is an non-exhaustive list of who uses DocBook at present.
Many books at O'Reilly, the publishing house, are marked up in DocBook (in particular [DocBook, the definitive Guide].
A lot of computer documentation, such as that for the following projects: xfree86, GNOME, KDE, FreeBSD, PHP, the Linux Documentation Project.
Similarly, a lot of the documentation for commercial software and hardware vendors. For instance Sun, Red Hat, SuSE, HP, Cogent Real-Time Systems, Conectiva, Rational, Mandrakesoft, Caldera, Apple (Darwin docs), etc. use DocBook.
Producing generated documentation from code comments (GNOME, Linux kernel, XSLT Standard Library).
For training material, where from a single document, one can produce presentation slides, sample files, and printed handouts.
Whitepapers, like system or formal specifications (e.g., the RELAX NG specification) and proposals.
For maintaining websites, in particular those hosting FAQs.
Producing presentation slides, courseware, theses and dissertations.
Using a single docbook source with various stylesheets to document applications in various ways: Online manuals (PDF, HTML), Context-sensitive help (HTML, HTML Help), Man pages and formatted text (using also non-XSLT HTML to text conversion), Filtering conditionalized versions (using profiling).
The complete development chain of a product, including a description of the product itself, the automated test tool documentation, the defect tracking database, related software (O/S, networking, Apache, SQL, etc.).
Single sourcing to ensure consistency, by generating three targets from the same DocBook document: product API specifications (targeted at internal developers),API refenrence manual (targeted at our customers), API validation code (different programming languages).
The DocBook markup language, maintained by the OASIS consortium, is specifically suited for for technical documentation. It provides a rich set of tags to describe the content of especially software documentation.
A number of key points that help understand what DocBook is follow.
- Docbook is a markup language.
It is very similar to HTML in this respect. The tags give some structure to your document, and appear intermixed with the informational text.
This pecular point makes it quite different from DTP (Desktop Publishing Tools) that spend most of their time "making the text look nice". In the case of DocBook and its associated XML tools, the rendering is done indirectly by using a transformation stage to generate the format for a given output medium.
- DocBook was mainly developed for technical documentation.
DocBook is perfectly suited for car engine parts documentation. However, it is strongly biased towards computer programs documentation.
- DocBook is maintained by an independent consortium.
The OASIS consortium is in charge of maintaining and making this standard evolve through the DocBook Technical Committee. This is a guarantee of independence with respect to proprietary software and standards.
Major players of the industry like Boeing or IBM are members of OASIS. A more complete members list is at the OASIS site.
- Technically, DocBook is a (SGML or) XML DTD.
This means that one can take profit of the many (SGML and) XML aware tools that are (often freely) avialable. While DocBook as an XML implementation is quite recent, it has a long history as a SGML application.
- DocBook is not a presentation language.
DocBook carefully cares about not specifying how the final documentation looks like. This allows the writer to concentrate on the organization and meaning of the document being written. All the presentation issues are devolved to style sheets.
This ensures all your documents have a consistent appearence, whoever is the technical writer.
- DocBook is customizable.
It is quite easy to customize the DTD to meet user need thanks to its modular organization. However, one must be aware that customization must respect SGML/XML conventions and that it can lead to incompatibilities.
If DocBook is used in conjunction with Norman Walsh's modular XSLT stylesheets, it is also possible to customize the way a DocBook file can be printed or put online.
- DocBook is comprehensive.
The large number of tags defined in DocBook guarantees that it can accomodate a wide range of situations and of processing expectations.
This in turn makes it a bit difficult to learn, but one can manage writing documentation knowing only a limited set of tags and referring to the reference documentation when needed.
- DocBook uses long and understable tags.
Example of such tags are <itemizedlist> or <literallayout>. This makes DocBook source text easier to read than an HTML source, for example. As a drwback, it can become quite tedious to type those long tags, but in that case specialized modes in editors, such as Emacs' psgml mode, can alleviate this burden. They also exist some complete DocBook authoring tools, but these are mostly not free.
In Section 1.3 we introduce the docbook2pdf and docbook2html applications. They allow you, with the help of Norman Walsh' XSLT stylesheets, to transform DocBook XML sources into PDF and HTML, respectively. The XSLT language, that is used to transform the DocBook XML sources into HTML, XSLT-FO, etc. is described in the W3C recommendation XSL Transformations [REC-XSLT]. There is a nice XSLT tutorial [NICXSLTUT], as well as Mike Kay's book XSLT Programmer's Reference [KAY2001]. The style sheets themselves are also described [DBXSLTDOC].
This section describes how to work with DocBook on Unix-like systems, such as Linux and Solaris (although the tools can also be made to work easily on Nice 2000).
The DocBook XML tools consist of several packages that work together to edit DocBook XML files, to convert them into many other formats, and to perform other miscellaneous operations. The output formats include:
HTML (and its XML variant XHTML)
HELP
JavaHelp
FO (for generating PDF)
HTMLHelp
At CERN the following two DocBook XML tools are installed.
docbook2html - transforms a DocBook source into one or more HBOOK files.
docbookpdf - transforms a DocBook source into a PDF file.
For Linux they are available in the /afs/cern.ch/sw/XML/XMLBIN/bin/i386-linux directory, which should be added into your PATH environment variable.
First, you need a DocBook file to convert. Using your favorite text editor you can type (or cut and paste) the following lines:
Example 1.1. My first simple DocBook file
1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"> <article> <articleinfo> 5 <title>XML rules the world!</title> </articleinfo> <section> <title>XML and DocBook do it together</title> 10 <para>DocBook and XML are the golden twins of the 21st certury !</para> </section> 15 </article>
Then save it, say, with the name dbfile.xml.
This file has to be well-formed. To check an XML document, you can use the following tool:
$ rxp -s dbfile.xml
If you have catalog support the above source, in fact, can relate your XML source file to a Document Type Definition (DTD) for DocBook. A DTD defines the possible elements, their arguments, and their content models (which elements can contain which, how do elements relate to each other). If you have access to the relevant DTD, you can validate your file. At CERN, on Unix (with AFS) the DocBook DTD can also be referenced by adding the second line specifying its complete address, as follows:
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/afs/cern.ch/sw/XML/XMLBIN/share/www.oasis-open.org/docbook/xmldtd-4.2/docbookx.dtd" > <article> . . . </article>
To validate dbfile.xml, use the command:
$ rxp -s -V dbfile.xml
If errors are shown, read through the error log and correct errors from the beginning of the list first. Often, an early error has knock-on effects further down the processing of the document.
Alternatively, when using emacs there exists an XML processing mode, psgml, see Appendix A “Emacs PSGML mode tips”.
Your file is now ready to be converted to other formats. To convert this file from DocBook format to HTML format, the command docbook2html can be used. This will run Norman Walsh's XSLT to HTML stylesheets and Michael Kay's saxon XSLT processor to generate the HTML files from the DocBook sources.
Example 1.2. Running docbook2html (single output file)
$ docbook2html dbfile.xml dbfile.xml abc.xsl dbfile.html Using java 1.4 from AFS. java version "1.4.0" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92) Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)
If you validated your XML file with an XML parser, then there should be no errors, and the procedure will generate the file dbfile.html, which can be viewed with an HTML browser, e.g., the line browser lynx shows the following.
Example 1.3. HTML version generated from a DocBook file as displayed by lynx
XML rules the world!
XML rules the world!
_________________________________________________________________
Table of Contents
XML and DocBook do it together
XML and DocBook do it together
DocBook and XML are the golden twins of the 21st century !
Commands: Use arrow keys to move, '?' for help, 'q' to quit, '<-' to go back.
Arrow keys: Up and Down to move. Right to follow a link; Left to go back.
H)elp O)ptions P)rint G)o M)ain screen Q)uit /=search [delete]=history list
In general, with a larger document, and the chunk option, you will get several files, as shown when we run (an early version) of the present manual with the docbook2html procedure.
Example 1.4. Running docbook2html with the chunk option
$ docbook2html -chunk dbatcern.xml
dbatcern.xml abc.xsl index.html
Using java 1.4 from AFS.
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)
Writing ch01s02.html for sect1(why-docbook)
Writing ch01s03.html for sect1(your-world-view)
Writing ch01s04.html for sect1(markup-based-on-content)
Writing ch01.html for chapter(introduction)
Writing ch02s02.html for sect1(installing-the-tools)
Writing ch02s03.html for sect1(hello-world)
Writing ch02s04.html for sect1(style-sheets)
... Many more lines ...
Writing ch11s03.html for sect1(warnings)
Writing ch11.html for chapter(miscellaneous)
Writing ch12.html for chapter(next)
Writing apa.html for appendix(emacs)
Writing go01.html for glossary(glossary)
Writing index.html for book(dbatcern)
We can see that files are generated at the level of the section (sect1 element), and in each case the value of the id attribute, if present, is displayed between parentheses.
XML processors, and in particular XSLT or CSS stylesheets can tune the way they handle or display elements in clever and convenient ways. For instance, we can add a lang attribute on the <book> and an id attribute on the <chapter> tags in the previous example and get the following:
Example 1.5. A small DocBook file showing the use of attributes
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/afs/cern.ch/sw/XML/XMLBIN/share/www.oasis-open.org/docbook/xmldtd-4.2/docbookx.dtd" > 5 <book lang="en-gb"> <!-- This is a <huge>comment & --> <bookinfo> <title>XML rules the world!</title> 10 </bookinfo> <chapter id="Chap1"> <title>XML rules the world!</title> 15 <para>Here we go with DocBook and XML.</para> </chapter> </book>
This example shows how to place comments (line 5) in an XML source file. A comment is all material between a leading <!-- and a trailing -->. The textual material between these two markers cannot contain two consecutive hyphens, i.e., -- is disallowed inside comments. A comment can span several lines. Comments are not interpreted by XML parsers, i.e. as seen in the example, you can put markup and other forbidden characters inside comments without problems.
To convert a DocBook file from DocBook format to another format, you need an XML processing tools and an XSL style sheet. The command docbook2html uses internally Mike Kay's saxon XSLT interpreter and Norman Wlash' XSLT style sheets.
Instead of generating an HTML hyper-document it is somethimes necessary to produce a nicely printable copy. Therefore, starting from the same DocBook XML source document and using an alternative XSLT style sheet one can generate XSL-FO formatting objects, that can the be translated into various media formats, in particular PDF with oneof several XSL-FO to PDF translators.
At CERN a script, docbook2pdf, hides the details of this translation process from the user. By default the script takes one argument, the name of the XML source to be transformed into PDF, for example,
Example 1.6. Generating PDF with docbook2pdf
$ docbookpdf dbfile.xml
docbook2pdf dbfile.xml
dbfile.xml abc.xsl dbfile.fo
Using java 1.4 from AFS.
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)
Making portrait pages on A4 paper (210mmx297mm)
running pdftex/passivetex (twice): pdfxmltex dbfile.fo
This is pdfTeX, Version 3.14159-pre-1.0-unofficial-20010704 (Web2C 7.3.3.1)
(./dbfile.fo{/afs/cern.ch/sw/TeXlive/tl7/texmf-var/pdftex/config/pdftex.cfg}
LaTeX2e <2001/06/01>
...
Output written on dbfile.pdf (1 page, 7710 bytes).
Transcript written on dbfile.log.
This is pdfTeX, Version 3.14159-pre-1.0-unofficial-20010704 (Web2C 7.3.3.1)
(./dbfile.fo{/afs/cern.ch/sw/TeXlive/tl7/texmf-var/pdftex/config/pdftex.cfg}
...
Output written on dbfile.pdf (1 page, 7710 bytes).
Transcript written on dbfile.log.
In the above we see that first a XSLT translator (saxon) is run that generates XSL-FO elements, that are then rendered into PDF by pdftex, a variant of the TeX program that generates PDF. Thus we obtain a file dbfile.pdf, which can be seen in Figure 1.1.
The file dbfile.pdf can be viewed with ghostview or acroread, and can be sent by these applications to a PostSCript printer.
What we obtained with the previous example is the default presentation as defined by the style sheets of Norman Walsh. In fact, Norman parameterized his style sheets in a convenient way, so that over one hundred parameters are available to finetune the format of the output page. At CERN you can specify a second filename to the docbook2pdf command, and when specified, it will be used as an XSLT customization style sheet, for instance, at CERN you could type:
$ docbookpdf dbfile.xml dbforpassivetex.xsl
If you are interested in such customization, you can start from the style sheet dbforpassivetex.xsl that is available from the docbook DocBook Web page at CERN. A full discussion of all parameters can be found in the [reference guide] entry in the [DocBook XSLT stylesheets] section of the above Web page.
XML, just like it spredecessor SGML, is a generic markup language. It is a meta-language syntax to define a convenient vocabulary for the application domain being dealt with. In science, in particular, software, DocBook offers a large choice of elements that are useful for marking up and producing good and precise documents in computer science, etc.
However, DocBook being an instance of an XML language, it obeys the XML syntax, which introduces elements, attributes, and entities as main components. For example, the XML start tag <chapter id="introduction"> has the element name chapter and the attribute id. The element influences the rendering of the text inside the element, while an element's attributes can further modify the behaviour or meta-information associated with the element. An element is closed with an XML end tag, for instance </chapter">. In the case of the chapter element the element contents, i.e., all text included within the starting and closing tags should be treated as a chapter, while the id attribute labels the chapter so it can be linked to or used as a file name when DocBook is translated to another format.
An element can also be empty, i.e., have no contents. For such an element we use a specific syntax, e.g. for a xref element, <xref linkend="foo" />.
Most DocBook tags contain a common set of attributes. The most often-used such common attributes are lang, which specifies the language of the data inside the element, id labels an element so that it can be referenced by other elements, and role, which allows one to subclass an element, to make it information-wise more specific.
As an XML language instance all DocBook elements must have a start and an end tag, or be empty (please forget your SGML or HTML habits, where end-tags are not always required). You should also make sure to use the proper case for element names, entities, and attribues. Detailed information about all element names and their attributes is in the DocBook reference guide.
DocBook document always has a top level element. In most cases it will be book, or article, but it can also be set, part, chapter and a few more.
The structural content of these two most-occurring cases for top (more correctly called root) elements of book, or article (or perhaps chapter when you are contributing to a book) are detailed next.
A book is structured in the following way:
book
meta information
chapter
sect1
sect1
chapter
sect1
appendix
sect1
appendix
sect1
…
glossary
An article has a somewhat simpler structure than a book:
article
meta information
sect1
sect1
sect2
sect1
…
Example 1.7. Chapters and sections
1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "/afs/cern.ch/sw/XML/XMLBIN/share/www.oasis-open.org/docbook/xmldtd-4.2/docbookx.dtd" > <book id="hello-world" lang="en"> 5 <bookinfo> <title>Hello, world</title> </bookinfo> 10 <chapter id="introduction"> <title>Introduction</title> <para>This is the introduction. It has two sections</para> 15 <sect1 id="about-this-book"> <title>About this book</title> <para>This is my first DocBook file.</para> 20 </sect1> <sect1 id="work-in-progress"> <title>Warning</title> 25 <para>This is still under construction.</para> </sect1> </chapter> 30 </book>
Example 1.7 shows a skeleton of the structural tags. Lines 1 and 2 contain the document type declaration (via a public identifier on line 1, which needs a calalog to operate and via an explicit system path on line 2, which, of course, will only work at CERN when connected to AFS). This information is described more fully in Section Section 1.10.
Next comes the root element (line 3), which contains the complete document. The name of the root element must be identical to the element name following the DOCTYPE specifier on line 1. Note the use of the lang attribute inside the <book> start tag. It is good practive to always use a language attribute to clearly indicate the (main) language in which the document is written.
After the <book> tag comes the meta information for the document, which is enclosed in the <bookinfo> element (lines 5-7). This information is described in more detail in Chapter Chapter 2.
Then come the chapters of the book (lines 9 to 28), which can contain one or more section tags (<sect1> through <sect5>). It is important to associate a label to each of the structural elements of your document using the id attribute for <chapter>, <sect>, etc. This makes cross-references between structural elements possible and it allows the output processors to use the value of the id attribute to name the generated output files. In order to make the development and maintenance of your documents easier, it is advisable to assign meaningful values (e.g., not merely numbers) to these id attributes.
Structural elements, such as chapters and sections, must contain at least a <title> (lines 10, 15, 22), and a (possibly empty) <para> element (lines 12, 17, 24).
The content model for the various elements, i.e., where and how many times each one can occur at a given point in a document is defined by the DocBook DTD (or Schema).
Content in DocBook is contained within a <para> tag, which is very similar to the <p> tag in HTML and LinuxDoc except that it must always have a closing </para> tag. Each time there can be a line break in some text (like in a list item), it means that the text will have to be enclosed in <para> tags.
In non-trivial document the document type declaration (the very first lines of a DocBook file) can be slightly more complicated than the one or two lines presented in the document skeleton previously.
The following example shows how entities allow one to define abbreviations for text strings. They can also be used to declare a convenient name for a character that is unavailable on a standard keyboard.
Example 1.8. Entities used to share text
1 <?xml version="1.0" encoding="iso-8859-1" ?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" <!ENTITY CERN "Conseil Européen pour la Recherche Nucléaire"> <!ENTITY WWW "<application>World Wide Web</application>"> 5 <!ENTITY W3C "&WWW; Consortium"> ]> <article id="The.Web" lang="en"> <articleinfo> 10 <title>The origin of the &WWW;</title> </articleinfo> <section id="introduction"> <title>General Introduction</title> 15 <para> Tim Berners-Lee and collaborators invented the &WWW; at <acronym>CERN</acronym> (&CERN;) at the beginning of the nineteen nineties. 20 </para> <para> Today all further developments are coordinated by the &W3C; (MIT, INRIA, Keio). 25 </para> </section> </article>
Several important points should be noted in Example 1.8. Firstly, line 1 shows that we have to declare an explicit encoding when we want to use non-ASCII characters (more precisely, characters that are not encoded in Unicode's UTF8 or UTF16). In particular, on line 3, where we define the CERN entity, we make use of the é (accented e) which is part of the ISO-8859-1 encoding, as specified on line 1. On the other hand we could use a Unicode character reference and replace line 3 by the following statement.
<!ENTITY CERN "Conseil Européen pour la Recherche Nucléaire">
In this case we do not have to declare an explicit encoding. Further, line 4 defines the WWW application, showing that one can use markup inside entity definitions, while the entity definition of W3C indicates that one can use entity references to previously declared entities (&WWW; in this case).
In the body of the text the defined entities are referenced on lines 10, 18, 19, and 23.
When you run the above file dbw3cexa.xml through the docbook2html procedure you obtain the file dbw3cexa.html, which is shown, as displayed by the Lynx line browser in Example 1.9.
Example 1.9. HTML version generated from a DocBook file as displayed by Lynx
The origin of the World Wide Web
The origin of the World Wide Web
________________________________________________________________
Table of Contents
General Introduction
General Introduction
Tim Berners-Lee and collaborators invented the World Wide Web at CERN
(Conseil Européen de la Recherche Nucléaire) at the beginning of the
nineteen nineties.
Today all further developments are coordinated by the World Wide Web
Consortium (MIT, INRIA, Keio).
Commands: Use arrow keys to move, '?' for help, 'q' to quit, '<-' to go back.
Arrow keys: Up and Down to move. Right to follow a link; Left to go back.
H)elp O)ptions P)rint G)o M)ain screen Q)uit /=search [delete]=history list
The consistent use of entities has a number of advantages:
you do not have to type several times a possibly quite long identical text string;
it allows you to centralize changes to commonly-used phrases and terms in a single place, thus guaranteeing consistency;
if the entity name is well chosen, it makes the source documents easier to read and maintain.
For larger documetnts, it is convenient to keep chapters or other large text chunks in individual files that can be maintained separately. In such a case the various files that have to be included in the master document are declared in the document type declaration as general external entities.
For instance, the present tutorial document is split at the chapter and appendix level into separate files, that are included with a single main driver file, as follows (only part of the file is shown):
Example 1.10. Including external files using entities
1 <!DOCTYPE book SYSTEM "/afs/cern.ch/sw/XML/XMLBIN/share/www.oasis-open.org/docbook/xmldtd-4.2/docbookx.dtd" [ <!ENTITY bookinfo SYSTEM "bookinfo.xml"> 5 <!ENTITY introduction SYSTEM "introduction.xml"> .... <!ENTITY emacs SYSTEM "emacs.xml"> <!ENTITY examples SYSTEM "examples.xml"> <!ENTITY glossary SYSTEM "glossary.xml"> 10 ]> <book id="dbatcern" lang="en"> &bookinfo; &introduction; ... 15 &emacs; &examples; &glossary; </book>
There exists a one-to-one correspondence between the entity definition using the <!ENTITY ...> declaration and the entity references, using the &xxx; syntax, where xxx is an entity that corresponds to a file that has to exist on the system as defined by the entity declaring xxx. A reference to an non-existing file will result in an error. For instance line 3 declares the bookinfo entity as an external reference to the file bookinfo.xml, that will be included on by the entity reference &bookinfo; on line 13.
Entity names have to be unique thoughout the document, but of course entities can be references several times (e.g., &WWW; on lines 10 and 17 of Example 1.9). For internal entities multiple references could be useful in the case of a copyright or other company message that has to be repeated on every page or at the beginning of each chapter.
The tags covered in this section provide meta information about the document, such as author, title, data of publication, etc.
authorinitials - Initials or other identifier for the author of a revision or comment
keywordset - Set of terms describing the content of a document
othername - Name component that is not a firstname, surname, or lineage
releaseInfo - Information about a particular version of a document
revision - Entry in revhistory, describing some revision made to the text
title - Text of a heading or the title of a block-oriented element
Example 2.1. DocBook metainformation
<bookinfo> <title>The TZirrdle Handbook</title> <authorgroup> <author> <firstname>George</firstname> <othername>N.</othername> <surname>Ugnacious</surname> </author> </authorgroup> <date>03/04/1999</date> <releaseinfo>1.01.00</releaseinfo> <abstract> <para> <application>twiddle</application> is an application specially designed to do nothing you would ever want. </para> </abstract> <keywordset> <keyword>twiddle</keyword> <keyword>sample application</keyword> </keywordset> </bookinfo>
The <bookinfo> tag contains all of the meta information for your document, as opposed as its contents that are in the various chapters. This allows you, for instance, to:
conveniently retrieve a specific document among many others on your system;
print some information on the front page, under the control of the style sheets;
serve it to search engines if you put it online in HTML format.
Table of Contents
- 3.1. The simplelist
- 3.2. The itemizedlist
- 3.3. The orderedlist
- 3.4. The variablelist
- 3.5. The segmentedlist
- 3.6. qandaset
- 3.7. Procedures
Elements related to DocBook lists are shown below. DocBook lists are very similar to their counterparts in HTML except that DocBook contains several more types of lists for specialized purposes.
itemizedlist - List in which each entry is marked with a bullet, dash, or other dingbat
listitem - Wrapper for the elements of items in an itemizedlist or orderedlist
orderedlist - List in which each entry is marked with a sequentially incremented label
segtitle - Title that pertains to one seg in each seglistitem
term - Hanging term attached to a listitem within a varlistentry in a variablelist
variablelist - List in which each entry is composed of sets of one or more terms with associated listitems
varlistentry - Wrapper for term and its associated listitem in a variablelist
The easiest of all the lists to use is the simplelist. It is designed for lists of short phrases (like a grocery list) and only requires two tags for building the list as you can see in the example below. The <member> tag can only contain inline content, so a simplelist cannot contain other lists.
Example 3.1. A simplelist
<simplelist type="inline"> <member>Apples</member> <member>Oranges</member> <member>Bananas</member> <member>Grapefruit</member> <member>Black Beans</member> </simplelist>
When converted, a simplelist will look something like this: Apples, Oranges, Bananas, Grapefruit, Black Beans
An itemizedlist is similar to the simplelist except that each entry contains a paragraph instead of just a short phrase, allowing you to put more varied content in your list. ItemizedLists can contain other lists.
Example 3.2. An itemizedlist
<itemizedlist> <listitem><para>Apples - my favorite fruit.</para></listitem> <listitem><para>Oranges - yummy, but sticky.</para></listitem> <listitem><para>Bananas - they ripen too quickly!</para></listitem> <listitem><para>Grapefruit - great when eaten in halves.</para></listitem> <listitem><para>Black Beans - go well with rice.</para></listitem> </itemizedlist>
The example will look something like this when converted:
Apples - my favorite fruit.
Oranges - yummy, but sticky.
Bananas - they ripen too quickly!
Grapefruit - great when eaten in halves.
Black Beans - go well with rice.
The orderedlist is like the itemizedlist except that each listitem is numbered or lettered. The numeration attribute specifies what kind of numbering will be used and can be one of the following values: arabic, upperalpha, loweralpha, upperroman, lowerroman. There are several other attributes that control the appearance of an orderedlist, see the DocBook Reference for details. orderedlists can contain other lists.
Example 3.3. An orderedlist
<orderedlist numeration="arabic"> <listitem><para>Wake up.</para></listitem> <listitem><para>Eat Breakfast.</para></listitem> <listitem><para>Take a shower.</para></listitem> <listitem><para>Contemplate my navel.</para></listitem> <listitem><para>Go to Sleep.</para></listitem> </orderedlist>
The example will look something like this when converted:
Wake up.
Eat Breakfast.
Take a shower.
Contemplate my navel.
Go to Sleep.
The variablelist is similar to an HTML definition list. It is used when you have a list of terms and definitions. The variablelist consists of several tags: <varlistentry>, which is used to group related terms together, <term>, which contains the term, and <listitem>, which contains the decription of the term.
Example 3.4. A variablelist
<variablelist> <varlistentry> <term>Black Beans</term> <listitem><para>My favorite black bean recipe is black bean soup, but they also go well with rice.</para></listitem> </varlistentry> <varlistentry> <term>Apples</term> <term>Bananas</term> <listitem><para>You can eat them straight, but they also go well in salads and in desserts.</para></listitem> </varlistentry> </variablelist>
When converted, the example variablelist will look something like this:
- Black Beans
My favorite black bean recipe is black bean soup, but they also go well with rice.
- Apples, Bananas
You can eat them straight, but they also go well in salads and in desserts.
segmentedlists are used to list information in distinct fields like the contents of an address book. The name of each field is put inside of a <segtitle> tag. Then, use the <seglistitem> tag to start and end each set of data. The actual data is put in the <seg> tag.
Example 3.5. A segmentedlist
<segmentedlist> <segtitle>Name</segtitle> <segtitle>Occupation</segtitle> <segtitle>Favorite Food</segtitle> <seglistitem> <seg>Tux</seg> <seg>Linux mascot</seg> <seg>Herring</seg> </seglistitem> <seglistitem> <seg>Konqui</seg> <seg>The KDE Dragon</seg> <seg>Gnomes</seg> </seglistitem> </segmentedlist>
This silly example looks something like this when converted:
Name: Tux
Occupation: Linux mascot
Favorite Food: Herring
Name: Konqui
Occupation: The KDE Dragon
Favorite Food: Gnomes
The qandaset is a specialized list designed specifically to deal with sets of questions and answers, like you would see in a FAQ. Each set of questions and answers are contained within a <qandaentry> tag. The <question> and <answer> tags contain the questions and answers respectively.
Example 3.6. A qandaset
<qandaset> <qandaentry> <question> <para>What are little boys made of?</para> </question> <answer> <para>Snips and snails and puppy dog tails.</para> </answer> </qandaentry> <qandaentry> <question> <para>What are little girls made of?</para> </question> <answer> <para>Sugar and spice and everything nice.</para> </answer> </qandaentry> </qandaset>
The qandaset looks something like this when converted:
Procedure lists are a specialized orderedlist used for listing step-by-step procedures like you would find in a recipe or Linux HowTo.
Example 3.7. A procedure list
<procedure> <title>Waking Up</title> <para>This is what you must do to awaken.</para> <step performance="required"> <para> Bring yourself to a hypnopompic state, either from an ongoing dream or by use of your internal clock. You may feel unable to move, but you will no longer be dreaming. </para> <para>Now you are ready for real-world readjustment.</para> <substeps> <step performance="optional"> <para>Roll over.</para> </step> <step performance="required"> <para>Squint out of one eye.</para> </step> </substeps> </step> <step performance="required"> <para>Yawn and rise from your bed. </para> </step> </procedure>
The above example would look something like this when converted:
Procedure 3.1. Waking Up
This is what you must do to awaken.
Bring yourself to a hypnopompic state, either from an ongoing dream or by use of your internal clock. You may feel unable to move, but you will no longer be dreaming.
Now you are ready for real-world readjustment.
Roll over.
Squint out of one eye.
Yawn and rise from your bed.
Table of Contents
Tables are used to organize data into a columnar representation. Optional titles, headers, and footers can be added to for describing the data, as required. DocBook tables come in two varieties: the table, which requires a title, and the informaltable, which does not have a title. All the other characteristics of these two table types are the same. DocBook elements associated to table markup are detailed below.
A table consists of formatting information and data entries. There are quite a few attributes that can be adjusted to tweak the display of your data. The examples show only a few of the basic formatting attributes. For more detailed description is in the DocBook Reference documentation.
Let us look at an example to see how a table is constructed.
Example 4.1. A regular simple table
1 <table> <title>Number of Visitors</title> <tgroup cols="3"> <thead> 5 <row> <entry>Month</entry><entry>Week</entry><entry>Visitors</entry> </row> </thead> <tfoot> 10 <row> <entry>Total</entry><entry></entry><entry>1833</entry> </row> </tfoot> <tbody> 15 <row> <entry>March</entry><entry>1</entry><entry>634</entry> </row> <row> <entry>March</entry><entry>2</entry><entry>657</entry> 20 </row> <row> <entry>March</entry><entry>3</entry><entry>542</entry> </row> </tbody> 25 </tgroup> </table>
As shown in Example 4.1, tables begin with the <table> (or <informaltable>) tag. Next, a title has to be defined using the title tag when using a regular table (line 2). Finally, we have the tgroup element which contains all of the header, footer, and row information (lines 3 to 25). There can be more than one tgroup if formatting options have to change for the different sections of the table. The tgroup tag (line 3) has a number of optional formatting parameters, but the cols attribute, which specifies the number of columns, is required. The thead (lines 4 to 8), tfoot (lines 9 to 13), and tbody (lines 14 to 24) elements contain the data in your table. Data in the thead appears at the top of the table, tbody appears in the middle, and tfoot appears at the end of the table.
Data in a table is contained in rows and entries, using row (lines 5-7, 10-12, 15-17, etc.) and entry (lines 6, 11, 16, etc.) elements, respectively. A table can be embedded inside another with the entrytbl element.
The above example would look something like this when converted:
Table 4.1. Number of Visitors
| Month | Week | Visitors |
|---|---|---|
| Total | 1833 | |
| March | 1 | 634 |
| March | 2 | 657 |
| March | 3 | 542 |
The structure of an informal table is similar to that of a normal table, but is has no title. Therefore, we present in Example 4.2 how such a table can be marked up. In most cases this example is rich enough to let you construct most of your real-life table.
Example 4.2. A simple informal table (no title)
1 <informaltable frame="all"> <tgroup cols="4"> <thead> <row> 5 <entry><emphasis>Title column 1</emphasis></entry> <entry><emphasis>Title column 2</emphasis></entry> <entry><emphasis>Title column 3</emphasis></entry> <entry><emphasis>Title column 4</emphasis></entry> </row> 10 </thead> <tbody> <row> <entry>Row 1 column 1</entry><entry>Row 1 column 2</entry> <entry>Row 1 column 3</entry><entry>Row 1 column 4</entry> 15 </row> <row> <entry>Row 2 column 1</entry><entry>Row 2 column 2</entry> <entry>Row 2 column 3</entry><entry>Row 2 column 4</entry> </row> 20 <row> <entry>Row 3 column 1</entry><entry>Row 3 column 2</entry> <entry>Row 3 column 3</entry><entry>Row 3 column 4</entry> </row> </tbody> 25 </tgroup> </informaltable>
| Title column 1 | Title column 2 | Title column 3 | Title column 4 |
|---|---|---|---|
| Row 1 column 1 | Row 1 column 2 | Row 1 column 3 | Row 1 column 4 |
| Row 2 column 1 | Row 2 column 2 | Row 2 column 3 | Row 2 column 4 |
| Row 3 column 1 | Row 3 column 2 | Row 3 column 3 | Row 3 column 4 |
The following table has a title and references some mathematical symbols, such as the ∑ and × entities. In fact quite a few entities are available, but, as seen in the definition of Euler's constant, the quality is note very high. For more complex mathematical construct MathML markup is to be preferred. For the definition of column alignment, the align attribute specifies that the entries in the columns should be eligned on the decimal point of floating point numbers.
Example 4.3. A more complex table
1 <table frame="all"> <title>Physical and mathematical constants</title> <tgroup cols="3" align="char" charoff="50" char="."> <thead> 5 <row> <entry>Quantity</entry> <entry>Definition</entry> <entry>Value</entry> </row> 10 </thead> <tbody> <row> <entry>Planck constant</entry> <entry>h</entry> 15 <entry>6.62606876(82)×10<superscript>-34</superscript> J s</entry> </row> <row> <entry>Boltzmann constant</entry> <entry>k</entry> 20 <entry>1.3806503(24)×10<superscript>-23</superscript> J K<superscript>-1</superscript></entry> </row> <row> <entry/> 25 <entry/> <entry>8.617342(15)×10<superscript>-5</superscript> eV K<superscript>-1</superscript></entry> </row> <row> 30 <entry>Euler constant</entry> <entry>e=∑<subscript>k</subscript> x<subscript>k</subscript>/k!</entry> <entry>2.718281828459(1)</entry> </row> 35 </tbody> </tgroup> </table>
This is how that table would be rendered in the output mode you are viewing now:
Table 4.2. Physical and mathematical constants
| Quantity | Definition | Value |
|---|---|---|
| Planck constant | h | 6.62606876(82)×10-34 J s |
| Boltzmann constant | k | 1.3806503(24)×10-23 J K-1 |
| 8.617342(15)×10-5 eV K-1 | ||
| Euler constant | e=∑k xk/k! | 2.718281828459(1) |
Documentation software applications often demands screenshots, pictures of icons and buttons, and other graphical elements. DocBook has element to support screenshots, graphics, and inline graphics. Below is a list of tags related to graphical objects.
imagedata - One of the formats encoding the image, such as EPS when printing and PNG when displaying online
inlinemediaobject - A picture, a sound, a text, that can be encoded in several different formats at the same time, to be rendered in-line
mediaobject - A picture, a sound, a text, that can be encoded in several different formats at the same time, not rendered in-line
screeninfo - Information about how a screenshot was produced
screenshot - Representation of what the user sees or might see on a computer screen
The following examples contain a picture as an inline graphic (Example 5.1) and as a screenshot (Example 5.2).
Example 5.1. An inline media object
1 <para> Here are a bunch of rectangles <inlinemediaobject> <imageobject> <imagedata fileref="rectangles.eps" format="EPS"/> </imageobject> 5 <imageobject> <imagedata fileref="rectangles.png" format="PNG"/> </imageobject> <textobject> <phrase>A bunch of rectangles</phrase> </textobject> </inlinemediaobject> </para>
The content of the inlinemediaobject element (lines 4 to 6) is displayed alongside text. The fileref attribute of the <imagedata> tag (lines 4 and 5) contains the name of the graphic file, the format attribute contains the type of the graphic file (the appropriate format should be chosen by the rendering application), and the optional align attribute changes the alignment of the graphic. The example will look something like this when converted:
Here are a bunch of rectangles
Example 5.2. A screenshot
1 <screenshot> <screeninfo>Feynman diagrams</screeninfo> <mediaobject> <imageobject> 5 <imagedata fileref="feyn1batik.png" scale="50" align="center" format="PNG"/> </imageobject> <textobject> <phrase>We show three Feynman diagrams with their 10 corresponding mathematical expressions</phrase> </textobject> <caption> <para>Feynman diagrams and their mathematical representation</para> </caption> 15 </mediaobject> </screenshot>
The screenshot element designates a screenshot with the screeninfo element (line 2) providing a textual description of the screen shot. The heart of the screenshot is the mediaobject element (lines 3 to 15) which points to a graphic file as explained in the first example. The imageobject element (lines 4 to 7) can contain one or more imagedata element (e.g. different formats for the same image, as in Example 5.1). In the present case (line 5 and 6) we only specify an PNG image, but we scale it to 50% (scale attribute) and center align it (align attribute). We also provide a textual description in the textobject element (lines 8 to 11) for applications that cannot handle the available graphics type(s). A global description with the help of the caption element (lines 12 to 14) ends the element content.
 |
Feynman diagrams and their mathematical representation
Linking in DocBook is very similar to linking in HTML. The <link> and <xref> tags are used to link to any element with an id in a document, and can also be used to link to other local files as well. The <ulink> tag is used when you need to link to a URL. The <email> tag is a specialized form of the ulink tag used for email addresses. <anchor> is used to mark a spot in the text that you want to reference later with a Link. An overview of these most common link elements of DocBook follows.
Example 6.1. Five kinds of links
1 <sect1 id="sec.link"> <title id="sec.title.link">Docbook link types</title> <para id="par.link"> This is a paragraph that will be linked to with a link tag. 5 If you want to know what's cool in HEP, point your browser at the <ulink url="http://www.cern.ch">CERN Web Page</ulink>. <anchor id="einstein.anchor"/>Einstein has been there.</para> <para> The above paragraph is reference <link linkend="par.link">here</link>. 10 <xref linkend="sec.link"/> (<xref linkend="sec.link" endterm="sec.title.link"/>) is a reference to a section. My email address is <email>michel.goossens@cern.ch</email> </para> </sect1>
We see that to address their link targets the link and xref elements use the linkend attribute (lines 9 and 10), while the ulink element uses the url attribute (line 6). The link and xref elements can also have a endterm attribute, which specifies that the content of the element with the value of its id attribute equal to the value of endterm must be used as the text of the cross-reference (line 11).
The above example would be displayed something like what is shown below.
1 1. Docbook link types This is a paragraph that will be linked to with a link tag. If you want to know what is cool in HEP, point your browser 5 at the CERN Web Page [http://www.cern.ch]. Einstein has been there. The above paragraph is reference here. Section 1. (Docbook link types) is a reference to a section. My email address is 10 <michel.goossens@cern.ch>.
We see how on lines 8 and 9 the work "Section 1." was generated by the application. Between brackets we find the contents of the title element, since the value of its id attribute (sec.title.link) corresponds to that specified on the endterm attribute of the xref element. Thus, we can finetune what we want to display as cross-reference information by making optimal us of the id attributes of the structural document elements.
Table of Contents
- 7.1. Examples
- 7.2. GUI Interface Elements
- 7.3. Command Line Elements
- 7.4. Elements for classes and methods
- 7.5. Describing an API
Often we want to include examples of source code, commands, or GUI actions in our documentation. DocBook has many tags to support these needs. Some of the relevant element are listed below.
example - Example of a computer program or related information
literallayout - Wrapper for lines set off from the main text that are not tagged as screens, examples, or programlisting, in which line breaks and leading white space are to be regarded as significant
screen - Text that a user sees or might see on a computer screen
Example 7.1. An example
<example> <title>A BASIC Example</title> <programlisting linenumbering='numbered'> 10 PRINT "HELLO WORLD" 20 GOTO 10 </programlisting> </example>
In this first example, we have a listing of a simple BASIC program. The code contained in the programlisting element is displayed with the spacing and line breaks intact which is very useful for code examples and similar situations where you must preserve the literal formatting. The literallayout and screen elements work similarly, but they are used to indicate different types of content, in particular screen elements contain output that would appear on the screen, while literallayout elements are used for any other text that must be rendered with line breaks and tabs.
The example would look something like this when converted:
Example 7.2. A BASIC Example
1 2 10 PRINT "HELLO WORLD" 3 20 GOTO 10 4
One problem with the screen , literallayout , and programlisting elements is that all text is rendered literally, but DocBook tags are still interpreted as tags and not text. If you do not want tags and entity references interpreted, you can use a <![ CDATA [ ]]> section, which labels the text contained within the inner brackets as character data that should not be interpreted by the XML parser. Any text within the brackets will remain as-is after the conversion, so the example above will successfully reproduce its tags.
Example 7.3. Displaying markup in a CDATA section
<example> <title>CDATA sections and markup</title> <screen> <![CDATA[ <para>This is a DocBook example.</para> ]]> </screen> </example>
This is what the markup example would look like when converted:
Example 7.4. CDATA sections and markup
<para>This is a DocBook example.</para>
accel - keycap used with a meta key to activate a graphical user interface
guiicon - Graphic and, or, text appearing as a icon in a graphical user interface
guimenuitem - Name of a terminal menu item in a graphical user interface
guisubmenu - Name of a submenu in a graphical user interface
interfacedefinition - Full or short name of a formal specification of a graphical user interface
keycap - Text printed on a physical key on a computer keyboard, not necessarily the same thing as a KeyCode
keycode - Computer's numeric designation of a key on a computer keyboard
keysym - Key symbol name, which is not necessarily the same thing as a Keycap
One could almost say that there are too many tags in DocBook for describing GUI elements. Most of the tags listed above can be used in a variety of contexts, but a few, such as <keycap>, must be used within other tags. The example and explanation below will not cover all of the tags listed above. This list is for your convenience since the DocBook Reference does not group tags by their function.
All of the GUI tags can be used within the context of a regular paragraph. So if I wanted to talk about the Trash icon or the Empty Trash button, I would just use the <guiicon> and <guibutton> tags like this: <guiicon>Trash</guiicon> icon, <guibutton>Empty Trash</guibutton> button. Note that all GUI tags may also contain inline graphics.
Below is a more complicated example of GUI tag usage.
Example 7.5. guimenu and shortcut
<variablelist> <varlistentry> <term><menuchoice> <shortcut> <keycombo><keycap>Ctrl</keycap><keycap>n</keycap></keycombo> </shortcut> <guimenu>File</guimenu> <guimenuitem>New</guimenuitem> </menuchoice></term> <listitem><para><action>Creates a new document</action></para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <shortcut> <keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo> </shortcut> <guimenu>File</guimenu> <guimenuitem>Save</guimenuitem> </menuchoice></term> <listitem><para><action>Saves the document</action></para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <shortcut> <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo> </shortcut> <guimenu>File</guimenu> <guimenuitem>Quit</guimenuitem> </menuchoice></term> <listitem><para><action>Quits</action> application>Kapp</application></para></listitem> </varlistentry> </variablelist>
The most complicated part of this example is the <Shortcut> tag which labels keyboard shortcuts for menuitems. Shortcut contains either a KeyCombo or a single KeyCap that contains the key or group of keys the use would press to invoke that menuitem from the keyboard. It is important to use the KeyCombo and KeyCap tags within the Shortcut tag because it is incorrect to use character data (the Ctrl-q text for example) within a shortcut.
Other tags worth mentioning from the example are menuchoice, action, and application. menuchoice labels a menu choice and should contain the shortcut (if any) the name of the menu in GUIMenu, and the name of the menuitem in guimenuitem. Action simply labels a phrase that describes what the menuitem (or other interface element) does. application is a tag used to label the names of applications.
The example would look something like this when converted:
- File->New (Ctrl-n)
Creates a new document
- File->Save (Ctrl-s)
Saves the document
- File->Quit (Ctrl-q)
Quits Kapp
The following tags are used to label elements of a command:
command - Executable program, or the entry a user makes to execute a command
funcsynopsisinfo - General information on how to use the function
literal - Literal string, used in-line, that is part of data in a computer
paramdef - Data type information and the name of the parameter this information applies to
prompt - Character indicating the start of an input field in a computer display.
replaceable - Content that may be replaced in a synopsis or command line
There are two situations in which you want to describe a command: showing an example of a command typed on the command line and a detailed description of all of the arguments and options to a command like you would see in a man page.
DocBook supports both of these contexts with the <command> and <cmdsynopsis> tags.
Example 7.6. A command and its output
<screen> <prompt>bash$</prompt> <command>twiddle <replaceable>myfile</replaceable> </command> twiddling myfile.....done! </screen>
Would appear as:
bash$ twiddle -c 1 myfile twiddling myfile.....done!
The command tag can also be used within a paragraph to mark the name of a command. For example:
The <command>twiddle</command> command is used to twiddle files files. Twiddled files will be marked with the .twid extension, so if I <command>twiddle</command> <replaceable>myfile</replaceable> then it will become <replaceable>myfile.twid</replaceable>. Errors are written to the file <filename>twiddle.err</filename>.
The twiddle command is used to twiddle files files. Twiddled files will be marked with the .twid extension, so if I twiddle myfile then it will become myfile.twid. Errors are written to the file twiddle.err.
The <prompt> tag is simply used to label the prompt in a command line. Replaceable labels text that should be replaced by the user. In the example, myfile is just an arbitrary name for a file since we don't know and don't care what the name of the file is, we just want to show how the command is used. If a filename in a command is known, use the <filename> tag instead.
Marking up a cmdsynopsis is a bit more difficult. Here is an example from the DocBook Reference:
Example 7.7. A commandsynopsis
<cmdsynopsis>
<!-- This is a synopsis for the command foo.
The options -a and -x are optional and exclusive
The option -c takes a cheese and is optional and repeatable
The options -t and -k are referred to in another fragment
The options -i, -j, and -k are required and exclusive
The option -f takes a filename and is required
The -t and -k options specify the kind of milk and mold in an
optional and repeatable group
-->
<command>foo</command>
<group>
<arg>-a</arg>
<arg>-x</arg>
</group>
<group>
<arg rep="repeat">-c <replaceable>cheese</replaceable></arg>
<synopfragmentref linkend="cheesetype">cheesetype</synopfragmentref>
</group>
<group choice="req">
<arg>-i</arg>
<arg>-j</arg>
<arg>-k</arg>
</group>
<arg choice="req">-f <replaceable>filename</replaceable></arg>
<synopfragment id="cheesetype">
<group rep="repeat">
<arg>-t <replaceable>milk</replaceable></arg>
<arg>-k <replaceable>mold</replaceable></arg>
</group>
</synopfragment>
</cmdsynopsis>Which looks like this:
A cmdsynopsis contains one command, groups of related args, independent args, and synopfragments. The <arg> labels arguments to the command. arg has two attributes: choice and rep. choice is used to indicate whether the tag is optional (the default), required (req), or to be displayed without any decoration (plain). The <group> tag is used to group together related args. synopfragment is the most complicated of the cmdsynopsis tags. It is used to provide a more detailed description of options for an argument. A synopfragment consists of two parts: the synopfragment, which contains the additional Args, and the synopfragmentref which points to the detailed description.
For describing classes and methods DocBook offers the following elements.
classname - The name of a class, in the object-oriented programming sense
classsynopsisinfo - Information supplementing the contents of a ClassSynopsis
ooclass - A class in an object-oriented programming language
ooexception - An exception in an object-oriented programming language
oointerface - An interface in an object-oriented programming language
An example of a Java Class synopsys and its typeset result follows.
Example 7.8. Class synopsys
<classsynopsis language="java"> <ooclass> <modifier>public</modifier> <classname>TextFileWriter</classname> </ooclass> <ooclass> <classname>HandlerBase</classname></ooclass> <fieldsynopsis> <modifier>private</modifier> <type>Writer</type> <varname>writer</varname> </fieldsynopsis> <fieldsynopsis> <modifier>public</modifier> <type>String</type> <varname>writerName</varname> <initializer>"MyWriter"</initializer> </fieldsynopsis> <methodsynopsis> <modifier>static</modifier> <modifier>public</modifier> <void/> <methodname>write</methodname> <methodparam> <type>ResultTreeFragment</type> <parameter>frag</parameter> </methodparam> <methodparam> <type>String</type> <parameter>file</parameter> </methodparam> <exceptionname>SAXException</exceptionname> </methodsynopsis> </classsynopsis>
public TextFileWriter extends HandlerBase {private Writer writer ;public String writerName = "MyWriter";static public void write(ResultTreeFragment frag,
String file)
throws SAXException;
}
Another example of a class definition, this time for IDL, follows.
<classsynopsis class="interface" language="idl"> <oointerface> <interfacename>Element</interfacename></oointerface> <oointerface> <interfacename>Node</interfacename></oointerface> <fieldsynopsis> <modifier>readonly</modifier> <modifier>attribute</modifier> <type>DOMString</type> <varname>tagName</varname> </fieldsynopsis> <methodsynopsis> <type>DOMString</type> <methodname>getAttribute</methodname> <methodparam> <modifier>in</modifier> <type>DOMString</type> <parameter>name</parameter> </methodparam> </methodsynopsis> <methodsynopsis> <void/> <methodname>setAttribute</methodname> <methodparam> <modifier>in</modifier> <type>DOMString</type> <parameter>name</parameter> </methodparam> <methodparam> <modifier>in</modifier> <type>DOMString</type> <parameter>value</parameter> </methodparam> <exceptionname>DOMException</exceptionname> </methodsynopsis> </classsynopsis>
interface implementsElement, Node {readonly attribute DOMString tagName ;DOMString getAttribute(in DOMString name);void setAttribute(in DOMString name, in DOMString value)
raises(DOMException);
}
DocBook has a rather detailed way of marking up descriptions of function behaviour. The tag that introduces it is <funcsynopsis>. Here is an example:
Example 7.9. Describing a function in a C library API
<funcsynopsis> <funcsynopsisinfo>#include <stdlib.h></funcsynopsisinfo> <funcprototype> <funcdef>double <function>atof</function></funcdef> <paramdef>const char *<parameter>nptr</parameter></paramdef> </funcprototype> </funcsynopsis>
Here is how it looks:
#include <stdlib.h>
double atof(nptr);
const char *nptr;
Table of Contents
- 8.1. Handling
Bibliographic information is specified inside the bibliography element. DocBook implements two styles of bibliography entries, and they have quite different processing expectations. On the one hand, you have raw informatioin, that you specify generically inside a biblioentry element, which contain a database-like collection of named fields. On the other hand, bibliomixe entries cooked, i.e., fields occur in the order in which they are to be displayed and additional punctuation may be sprinkled between the fields.
In the following we will mainly emphasize the generic entries. In the text a citation element can be used to refer to a bibliographic entry.
abbrev - An abbreviation, especially one followed by a period
affiliation - The institutional affiliation of an individual
authorgroup - Wrapper for author information with multiple authors or collabarators
authorinitials - The initials or other short identifier for an author
bibliomset - A cooked container for related bibliographic information
biblioset - A raw container for related bibliographic information
citation - An inline bibliographic reference to another published work
confgroup - A wrapper for document meta-information about a conference
contrib - A summary of the contributions made to a document by a credited source
corpauthor - A corporate author, as opposed to an individual
issn - The International Standard Serial Number of a periodical
orgname - The name of an organization other than a corporation
othercredit - A person or entity, other than an author or editor, credited in a document
othername - A component of a persons name that is not a first name, surname, or lineage
pagenums - The numbers of the pages in a book, for use in a bibliographic entry
pubsnumber - A number assigned to a publication other than an ISBN or ISSN
releaseinfo - Information about a particular release of a document
title - The text of the title of a section of a document or of a formal block-level element
volumenum - The volume number of a document in a set (as of books in a set or articles in a journal)
Example Example 8.1 is an XML DocBook source document that contains a short text with a few citations to books or Internet documents, that are defined in the bibliography.
Example 8.1. Example of A bibliography and citations
1 <!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN' "/afs/cern.ch/sw/XML/cdrom/www.nwalsh.com/docbook/xml/docbookx.dtd"> <article> <sect1> 5 <title>DocBook and bibliographic references</title> <para> The DocBook markup system is described in the printed book <emphasis>DocBook - The Definitive Guide</emphasis> <citation><xref 10 linkend="bib.TDG99" endterm="bib.TDG99.abbrev"/></citation>. There is an up-to-date local HTML copy at CERN <citation> <xref linkend="bib.TDGupd" endterm="bib.TDGupd.abbrev"/></citation> </para> 15 <para> The XSLT language, that is used to transform the DocBook XML sources into HTML, XSLT-FO, etc. is described in the W3C recommendation <emphasis>XSL Transformations <citation><xref linkend="bib.xsltrec" endterm="bib.xsltrec.abbrev"/></citation></emphasis>. There is a nice 20 XSLT tutorial <citation><xref linkend="bib.XSLTtut.Nic" endterm="bib.XSLTtut.Nic.abbrev"/></citation>, as well as Mike Kay's book <emphasis>XSLT Programmer's Reference</emphasis> <citation><xref linkend="bib.xsltkay2" endterm="bib.xsltkay2.abbrev"/></citation>. The style sheets themselves are also described <citation><xref 25 linkend="bib.docbook.xslt" endterm="bib.docbook.xslt.abbrev"/></citation>. </para> <para> The are two discussion lists, about Docbook <citation><xref 30 linkend="bib.docbook.list" endterm="bib.docbook.list.abbrev"/></citation> and its applications <citation><xref linkend="bib.docbook.apps.list" endterm="bib.docbook.apps.list.abbrev"/></citation>. </para> </sect1> 35 <bibliography id="sec.bibliography"> <title>Bibliography</title> <biblioentry id="bib.xsltrec"> 40 <abbrev id="bib.xsltrec.abbrev">REC-XSLT</abbrev> <editor><firstname>James</firstname><surname>Clark</surname></editor> <title><ulink url="http://www.w3.org/TR/xslt">XSL Transformations (XSLT) Version 1.0</ulink></title> <publishername>W3C Recommendation</publishername> 45 <pubdate>16 November 1999</pubdate> </biblioentry> <biblioentry id="bib.XSLTtut.Nic"> <abbrev id="bib.XSLTtut.Nic.abbrev">NICXSLTUT</abbrev> <author><firstname>Miloslav</firstname><surname>Nic</surname></author> 50 <title><ulink url="http://www.zvon.org/xxl/XSLTutorial/Books/Book1/index.html">XSLT Tutorial</ulink></title> </biblioentry> <biblioentry id="bib.xsltkay2"> <abbrev id="bib.xsltkay2.abbrev">KAY2001</abbrev> <author><firstname>Michael</firstname><surname>Kay</surname></author> 55 <title>XSLT 2nd Edition</title> <subtitle>Programmer's Reference</subtitle> <pubdate>2001</pubdate> <edition>2</edition> <isbn>ISBN: 1861005067</isbn> 60 <pagenums>940</pagenums> </biblioentry> <biblioentry id="bib.TDG99"> <abbrev id="bib.TDG99.abbrev">TDG1999</abbrev> <authorgroup> 65 <author><firstname>Norman</firstname><surname>Walsh</surname></author> <author><firstname>Leonard</firstname><surname>Muellner</surname></author> </authorgroup> <title>DocBook</title> <subtitle>The Definitive Guide</subtitle> 70 <pubdate>1999</pubdate> <edition>1</edition> <isbn>ISBN: 156592-580-7</isbn> <pagenums>648</pagenums> <releaseinfo> 75 <ulink url="http://www.oreilly.com/catalog/docbook/index.html">Oreilly's catalog entry</ulink>. An online version <ulink url="http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html">is available</ulink> </releaseinfo> </biblioentry> <biblioentry id="bib.TDGupd"> 80 <abbrev id="bib.TDGupd.abbrev">TDG2002</abbrev> <authorgroup> <author><firstname>Norman</firstname><surname>Walsh</surname></author> <author><firstname>Leonard</firstname><surname>Muellner</surname></author> </authorgroup> 85 <title>DocBook 4.2</title> <subtitle><ulink url="http://xml.cern.ch/www.docbook.org/tdg/en/html/docbook.html">Updated online Reference installed at CERN</ulink></subtitle> </biblioentry> <biblioentry id="bib.docbook.xslt"> 90 <abbrev id="bib.docbook.xslt.abbrev">DBXSLTDOC</abbrev> <authorgroup> <author><firstname>Norman</firstname><surname>Walsh</surname></author> <author><firstname>Bob</firstname><surname>Stayton</surname></author> </authorgroup> 95 <title>DocBook XSL stylesheets</title> <releaseinfo> <ulink url="http://sourceforge.net/projects/docbook/">The sources n <literal>sourceforge</literal></ulink>. At CERN these stylesheets are installed locally, as well as the associated <ulink 100 url="http://xml.cern.ch/sourceforge.net/projects/docbook/docbook-xsl-1.49/doc/index.html"> documentation</ulink> </releaseinfo> </biblioentry> <biblioentry> <biblioentry id="bib.docbook.list"> 105 <abbrev id="bib.docbook.list.abbrev">DBLIST</abbrev> <title>DocBook discussion list <email>docbook@lists.oasis-open.org</email></title> <releaseinfo><ulink url="http://lists.oasis-open.org/archives/docbook/">List archive</ulink></releaseinfo> </biblioentry> <biblioentry id="bib.docbook.apps.list"> 110 <abbrev id="bib.docbook.apps.list.abbrev">DBAPPSLIST</abbrev> <title>DocBook applications discussion list <email>docbook-apps@lists.oasis-open.org</email></title> <releaseinfo><ulink url="http://lists.oasis-open.org/archives/docbook-apps/">List archive</ulink></releaseinfo> </biblioentry> 115 </bibliography> </article>
The result of transforming the xml file of Example 8.1 into PDF (with docbook2pdf, see Figure 8.1) and HTML (with docbook2html, see Figure 8.2).
Table of Contents
- 9.1. Labelling Tags
- 9.2. Formatting Tags
- 9.3. Warnings, Tips, and Notes
The application tag labels the name of an application. The <markup> tag is used to label marked up text, such as HTML or TeX tags.
The following tags are fairly self-explanatory. This is an emaphasized sentence with superscripted and subscripted text.
The following tags are used to set off paragraphs from the rest of the text. They all wrap around paragraphs.
<warning><para>Danger, Will Robinson!</para></warning>
The example would look something like this:
Warning
Danger, Will Robinson!
Table of Contents
As already explained in the introduction, various several useful parts of DocBook are not discussed or only briefly mentioned in this Tutorial. A reference of all element names and a one-line explanation is in Appendix C. However, for more detailed information you should consult the resources list that follows.
[REC-XSLT] James Clark. XSL Transformations (XSLT) Version 1.0. W3C Recommendation. 16 November 1999.
[NICXSLTUT] XSLT Tutorial.
[TDG1999] DocBook. The Definitive Guide. 1999. ISBN: 156592-580-7. Oreilly's catalog entry. Online version .
[TDG2002] DocBook 4.2. Updated online Reference installed at CERN.
[DBXSLTDOC] DocBook XSL stylesheets (version 1.49, February 2002). The sources are on sourceforge. At CERN these stylesheets are installed locally, as well as the associated documentation .
[OASISTAB] Organization for the Advancement of Structured Information Standards (OASIS) Technical Memorandum TR 9901:1999. XML Exchange Table Model Document Type Definition. 1999. OASIS. HTML source.
[DBLIST] DocBook discussion list <docbook@lists.oasis-open.org>. List archive.
[DBAPPSLIST] DocBook applications discussion list <docbook-apps@lists.oasis-open.org>. List archive.
Several XML editors exist. A very flexible and free one is emacs with its psgml mode, which, amongst other things, offers emacs-style completion on tags. Also, it lets you check your file (if it can read the DTD), shows which elements are possible at a given pountin the source file, etc.
The emacs editor is one of the most often used editors on Unix (and today is also popular on Microsoft Windows). It is highly customizable via Lisp code and can easily cope with the syntax of various languages. Lennart Staflin developed the basic SGML/XML support in the form of an emacs ``macro mode'' psgml. For editing DTDs Tony Graham contributed his emacs macros tdtd.
All these modes present you with menus and commands for inserting tags, thus helping you to enter only contextually valid tags and allowing you to edit attribute values in a separate window with information about types and defaults. They also identify structural errors.
Figure A.1 shows an example of a small DocBook file where together with James Clark's nsgmls SGML/XML parser and emacs's psgml mode one can verify at each point in the document which element, attritute, etc. is allowed. Moreover, colours are used to distinguish the different XML language components, making editing significantly easier.
If you type "C-c C-e" (or go into the Markup window, and choose the Insert Element entry) emacs will prompt you for an element, and offer as completions all elements valid at that point.
Once it inserts the element, it inserts it with any required following elements along with a comment saying which ones you could put later on.
As an example, if you type the following into the a DocBook emacs:
C-c C-e variab<SPACE BAR><RETURN>
a variablelist and its expansion is inserted into the text buffer, as follows:
<variablelist>
<varlistentry>
<term></term>
<listitem>
<!-- one of (epigraph authorblurb abstract highlights
comment bridgehead anchor sidebar procedure msgset table
figure example equation informaltable informalexample
informalequation graphicco graphic blockquote address
simpara para formalpara funcsynopsis cmdsynopsis synopsis
screenshot screenco screen programlistingco programlisting
literallayout warning tip note important caution
variablelist simplelist segmentedlist orderedlist
itemizedlist glosslist calloutlist) -->
</listitem>
</varlistentry>
</variablelist>
As another example, when we type:
C-c C-e i<SPACE BAR>
we get the following completions:
Click mouse-2 on a completion to select it.
In this buffer, type RET to select the completion near point.
Possible completions are:
important indexterm
informalequation informalexample
informaltable itemizedlist
The current element is closed by typing "C-c /".
1 <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE article SYSTEM "/afs/cern.ch/sw/XML/XMLBIN/share/www.oasis-open.org/docbook/xmldtd-4.2/docbookx.dtd" [ 5 <!ENTITY LaTeX "LaTeX"> <!ENTITY TeX "TeX"> <!ENTITY PTeX "PassiveTeX"> <!ENTITY xmltex "<application>xmltex</application>"> ]> 10 <article> <articleinfo> <title>A Docbook document featuring a few formulae</title> <author><firstname>Michel</firstname> <surname>Goossens</surname> </author> 15 <pubdate>Sunday, 17 March 2002</pubdate> <abstract> <para> This XML document is marked up according the the DocBook schema It shows a few elements of the DocBook vocabulary, as well as a couple of 20 examples of mathematical expressions where we used MathML markup. </para> </abstract> </articleinfo> 25 <sect1> <title>The Docbook model</title> <para> DocBook <citation><xref role="bib" linkend="bib.TDG99" endterm="bib.TDG99.abbrev"/></citation> proposes an XML model 30 <citation><xref role="bib" linkend="bib.xml" endterm="bib.xml.abbrev"/></citation> for marking up technical documents. It is particularly well-suited for software reference guides and computer equipment manuals. </para> 35 <para> Docbook contains hundreds of elements to markup up clearly and explicitly the different components of an electronic document (book, article, reference guide, etc.), not only displaying its hierarchical 40 structure but also indicating the semantical meaning of the various elements. The structure of the DTD is optimized to allow for customization, thus making it relatively straightforward to add or eliminate certain elements or attributes, to change the content model for certain structural groups, or to restrict the value that given 45 attributes can take. </para> <para> Norman Walsh developed a set of XSL stylesheets to transform XML 50 documents marked up using the DocBook DTD into HTML or XSL formatting objects. The latter can be interpreted by &PTeX; and &xmltex; to obtain PDF or PostScript output. </para> </sect1> 55 <sect1> <title>MathML and mathematics</title> <para> MathML <citation><xref role="bib" linkend="bib.mathml" 60 endterm="bib.mathml.abbrev"/></citation> is a W3C recommendation whose aim is to encode mathematical material for teaching and scientific communication at all levels. </para> 65 <para> MathML consists of two parts: presentation (notation) et contents (meaning). MathML permits the conversion of mathematical information into various representations and output formats, including graphical displays, speech synthesizers, computer algebra programs, other 70 mathematics typesetting languages, such as &TeX;, plain text, printers (PostScript), braille, etc. </para> <para> 75 MathML has support for efficiently browsing long and complex mathematical expressoins and offers an extension mechanism. MathML code is human readable, easy to generate and process by software applications, and well suited for editing (even though MathML syntax might appear unnecessarily verbose and complex to the human reader). 80 </para> <para> The W3C MathMl Working Group released the Second version of the the MathML Specification at the beginning of 2001. Two public initiatives 85 that allow the display of MathML code direcly and that are under active development are W3C's <application>Amaya</application> and <application>Mozilla</application>. Commercial programs, such as IBM's <application>techexplorer</application> (a plugin for <application>Netscape</application> or Microsoft's 90 <application>Internet Explorer</application>) or Design Science <application>Webeq</application> (using the Java applet technology) can display MathML formulae in present day browsers. Several computer algebra programs, e.g., <application>Mathematica</application>, or editors using e.g., <application>mathtype</application>, offer a 95 user-friendly interface to enter, produce or read mathematics material marked up in MathML. </para> </sect1> 100 <sect1> <title>Presentation markup</title> <para> The <emphasis>presentation</emphasis> part of MathML discribes the 105 spacial layout of the different elements of a mathematical expression. MathML presenation markup has about thirty elements, that form the basis of a mathematical syntax using classical visual layout model. Some fifty attributes provide precise control on the exact positioning of the various components of the math expression. 110 </para> <para> The list of presentation elements follows. <variablelist> 115 <varlistentry> <term>Token elements</term> <listitem><para> <sgmltag class="element">mi</sgmltag>,<sgmltag class="element">mn</sgmltag>, <sgmltag class="element">mo</sgmltag>,<sgmltag class="element">mtext</sgmltag>, 120 <sgmltag class="element">mspace/</sgmltag>,<sgmltag class="element">ms</sgmltag>, <sgmltag class="element">mchar</sgmltag>,<sgmltag class="element">mglyph</sgmltag> </para></listitem> </varlistentry> <varlistentry> 125 <term>General layout schemata</term> <listitem><para> <sgmltag class="element">mrow</sgmltag>,<sgmltag class="element">mfrac</sgmltag>, <sgmltag class="element">msqrt</sgmltag>,<sgmltag class="element">mroot</sgmltag>, <sgmltag class="element">mstyle</sgmltag>,<sgmltag class="element">merror</sgmltag>, 130 <sgmltag class="element">mpadded</sgmltag>,<sgmltag class="element">mphantom</sgmltag>, <sgmltag class="element">mfenced</sgmltag>,<sgmltag class="element">menclose</sgmltag> </para></listitem> </varlistentry> <varlistentry> 135 <term>Script and limit schemata</term> <listitem><para> <sgmltag class="element">msub</sgmltag>,<sgmltag class="element">msup</sgmltag>, <sgmltag class="element">msubsup</sgmltag>,<sgmltag class="element">munder</sgmltag>, <sgmltag class="element">mover</sgmltag>,<sgmltag class="element">munderover</sgmltag>, 140 <sgmltag class="element">mmultiscripts</sgmltag> </para></listitem> </varlistentry> <varlistentry> <term>Tables and matrices</term> 145 <listitem><para> <sgmltag class="element">mtable</sgmltag>,<sgmltag class="element">mtr</sgmltag>, <sgmltag class="element">mtd</sgmltag>,<sgmltag class="element">maligngroup/</sgmltag>, <sgmltag class="element">malignmark/</sgmltag> </para></listitem> 150 </varlistentry> <varlistentry> <term>Enlivening expressions</term> <listitem><para> <sgmltag class="element">maction</sgmltag> 155 </para></listitem> </varlistentry> </variablelist> </para> 160 <sect2> <title>A MathML example</title> <para> A MathML formula can be typeset inline, as here <inlineequation> 165 <mml:math> <mml:mi>E</mml:mi><mml:mo>=</mml:mo><mml:mi>m</mml:mi><mml:msup><mml:mi>c</mml:mi> <mml:mn>2</mml:mn></mml:msup> </mml:math> </inlineequation>, Einstein's famous equation. 170 </para> <para> An mathematical equation can also be typeset in display mode using DocBook's <sgmltag class="element">informalequation</sgmltag> element, 175 as is shown in the following example containing a matrix: </para> <informalequation> <mml:math> 180 <mml:mrow> <mml:mi>A</mml:mi> <mml:mo>=</mml:mo> <mml:mfenced open="[" close="]"> <mml:mtable><!-- table or matrix --> 185 <mml:mtr> <!-- row in a table --> <mml:mtd><mml:mi>x</mml:mi></mml:mtd><!-- table --> <mml:mtd><mml:mi>y</mml:mi></mml:mtd><!-- entry --> </mml:mtr> <mml:mtr> 190 <mml:mtd><mml:mi>z</mml:mi></mml:mtd> <mml:mtd><mml:mi>w</mml:mi></mml:mtd> </mml:mtr> </mml:mtable> </mml:mfenced> 195 </mml:mrow> <mml:mtext>.</mml:mtext> </mml:math> </informalequation> 200 <para> Note the two attributes <sgmltag class="attribute">open</sgmltag> and <sgmltag class="attribute">close</sgmltag> on the <sgmltag class="element">mfenced</sgmltag> element to specify the style of the braces to be used. The MathML Specification <citation><xref role="bib" 205 linkend="bib.mathml" endterm="bib.mathml.abbrev"/></citation> contains a detailed list of all possible attributes associated to each presentation element. </para> </sect2> 210 </sect1> <sect1> <title>Content markup</title> 215 <para> The meaning of mathematical symbols (e.g., sums, products, integrals) exists independently of their rendering. Moreover the presentation markup of an expression is not necessarily sufficient to evaluate its value and use it in calculations. Therefore, MathML defines 220 <emphasis>content</emphasis> markup to explicitly encode the underlying mathematical structure of an expressoin. </para> <para> 225 It is impossible to cover all of mathematics, so MathML proposes only a relatively small number of commonplace mathematical constructs, chosen carefully to be sufficient in a large number of applications. In addition, it provides a <emphasis>extension mechanism</emphasis> for associating semantics with new notational 230 constructs, thus allowing these to be encoded even when they are not in MathML content element base collection. </para> <para> 235 MathML's basic set of content elements was chosen to allow for simple coding of most of the formulas used in secondary education, through the first year of university. The subject areas targeted are arithmetic, algebra, logic and relations, calculus and vector calculus, set theory, sequences and series, elementary classical 240 functions, and statistics linear algebra. Using this basic sets more complex constructs can be built. </para> <para> 245 The list of the content elements of MathML follows. <variablelist> <varlistentry> <term>token elements</term> <listitem><para> 250 <sgmltag class="element">cn</sgmltag>,<sgmltag class="element">ci</sgmltag>, <sgmltag class="element">csymbol</sgmltag> (MathML 2.0). </para></listitem> </varlistentry> <varlistentry> 255 <term>basic content elements</term> <listitem><para> <sgmltag class="element">apply</sgmltag>,<sgmltag class="element">reln (deprecated)</sgmltag>, <sgmltag class="element">fn (deprecated for externally defined functions)</sgmltag>, 260 <sgmltag class="element">interval</sgmltag>,<sgmltag class="element">inverse</sgmltag>, <sgmltag class="element">sep</sgmltag>,<sgmltag class="element">condition</sgmltag>, <sgmltag class="element">declare</sgmltag>,<sgmltag class="element">lambda</sgmltag>, <sgmltag class="element">compose</sgmltag>,<sgmltag class="element">ident</sgmltag>. </para></listitem> 265 </varlistentry> <varlistentry> <term>arithmetic, algebra and logic</term> <listitem><para> <sgmltag class="element">quotient</sgmltag>,<sgmltag class="element">exp</sgmltag>, 270 <sgmltag class="element">factorial</sgmltag>,<sgmltag class="element">divide</sgmltag>, <sgmltag class="element">max and min</sgmltag>,<sgmltag class="element">minus</sgmltag>, <sgmltag class="element">plus</sgmltag>,<sgmltag class="element">power</sgmltag>, <sgmltag class="element">rem</sgmltag>,<sgmltag class="element">times</sgmltag>, <sgmltag class="element">root</sgmltag>,<sgmltag class="element">gcd</sgmltag>, 275 <sgmltag class="element">and</sgmltag>,<sgmltag class="element">or</sgmltag>, <sgmltag class="element">xor</sgmltag>,<sgmltag class="element">not</sgmltag>, <sgmltag class="element">implies</sgmltag>,<sgmltag class="element">forall</sgmltag>, <sgmltag class="element">exists</sgmltag>,<sgmltag class="element">abs</sgmltag>, <sgmltag class="element">conjugate</sgmltag>,<sgmltag class="element">arg</sgmltag> (MathML 2.0), 280 <sgmltag class="element">real</sgmltag> (MathML 2.0),<sgmltag class="element">imaginary</sgmltag> (MathML 2.0), <sgmltag class="element">lcm</sgmltag> (MathML 2.0). </para></listitem> </varlistentry> <varlistentry> 285 <term>relations</term> <listitem><para> <sgmltag class="element">eq</sgmltag>,<sgmltag class="element">neq</sgmltag>, <sgmltag class="element">gt</sgmltag>,<sgmltag class="element">lt</sgmltag>, <sgmltag class="element">geq</sgmltag>,<sgmltag class="element">leq</sgmltag>, 290 <sgmltag class="element">equivalent</sgmltag> (MathML 2.0),<sgmltag class="element">approx</sgmltag> (MathML 2.0). </para></listitem> </varlistentry> <varlistentry> <term>calculus and vector calculus</term> 295 <listitem><para> <sgmltag class="element">int</sgmltag>,<sgmltag class="element">diff</sgmltag>, <sgmltag class="element">partialdiff</sgmltag>,<sgmltag class="element">lowlimit</sgmltag>, <sgmltag class="element">uplimit</sgmltag>,<sgmltag class="element">bvar</sgmltag>, <sgmltag class="element">degree</sgmltag>,<sgmltag class="element">divergence</sgmltag> (MathML 2.0), 300 <sgmltag class="element">grad</sgmltag> (MathML 2.0),<sgmltag class="element">curl</sgmltag> (MathML 2.0), <sgmltag class="element">laplacian</sgmltag> (MathML 2.0). </para></listitem> </varlistentry> <varlistentry> 305 <term>theory of sets</term> <listitem><para> <sgmltag class="element">set</sgmltag>,<sgmltag class="element">list</sgmltag>, <sgmltag class="element">union</sgmltag>,<sgmltag class="element">intersect</sgmltag>, <sgmltag class="element">in</sgmltag>,<sgmltag class="element">notin</sgmltag>, 310 <sgmltag class="element">subset</sgmltag>,<sgmltag class="element">prsubset</sgmltag>, <sgmltag class="element">notsubset</sgmltag>,<sgmltag class="element">notprsubset</sgmltag>, <sgmltag class="element">setdiff</sgmltag>,<sgmltag class="element">card</sgmltag> (MathML 2.0). </para></listitem> </varlistentry> 315 <varlistentry> <term>sequences and series</term> <listitem><para> <sgmltag class="element">sum</sgmltag>,<sgmltag class="element">product</sgmltag>, <sgmltag class="element">limit</sgmltag>,<sgmltag class="element">tendsto</sgmltag>. 320 </para></listitem> </varlistentry> <varlistentry> <term>elementary classical function</term> <listitem><para> 325 <sgmltag class="element">exp</sgmltag>,<sgmltag class="element">ln</sgmltag>, <sgmltag class="element">log</sgmltag>,<sgmltag class="element">sin</sgmltag>, <sgmltag class="element">cos</sgmltag>,<sgmltag class="element">tan</sgmltag>, <sgmltag class="element">sec</sgmltag>,<sgmltag class="element">csc</sgmltag>, <sgmltag class="element">cot</sgmltag>,<sgmltag class="element">sinh</sgmltag>, 330 <sgmltag class="element">cosh</sgmltag>,<sgmltag class="element">tanh</sgmltag>, <sgmltag class="element">sech</sgmltag>,<sgmltag class="element">csch</sgmltag>, <sgmltag class="element">coth</sgmltag>,<sgmltag class="element">arcsin</sgmltag>, <sgmltag class="element">arccos</sgmltag>,<sgmltag class="element">arctan</sgmltag>, <sgmltag class="element">arccosh</sgmltag>,<sgmltag class="element">arccot</sgmltag>, 335 <sgmltag class="element">arccoth</sgmltag>,<sgmltag class="element">arccsc</sgmltag>, <sgmltag class="element">arccsch</sgmltag>,<sgmltag class="element">arcsec</sgmltag>, <sgmltag class="element">arcsech</sgmltag>,<sgmltag class="element">arcsinh</sgmltag>, <sgmltag class="element">arctanh</sgmltag>. </para></listitem> 340 </varlistentry> <varlistentry> <term>statistics</term> <listitem><para> <sgmltag class="element">mean</sgmltag>,<sgmltag class="element">sdev</sgmltag>, 345 <sgmltag class="element">variance</sgmltag>,<sgmltag class="element">median</sgmltag>, <sgmltag class="element">mode</sgmltag>,<sgmltag class="element">moment</sgmltag>. </para></listitem> </varlistentry> <varlistentry> 350 <term>linear algebra</term> <listitem><para> <sgmltag class="element">vector</sgmltag>,<sgmltag class="element">matrix</sgmltag>, <sgmltag class="element">matrixrow</sgmltag>,<sgmltag class="element">determinant</sgmltag>, <sgmltag class="element">transpose</sgmltag>,<sgmltag class="element">selector</sgmltag>, 355 <sgmltag class="element">vectorproduct</sgmltag> (MathML 2.0),<sgmltag class="element">scalarproduct</sgmltag> (MathML 2.0), <sgmltag class="element">outerproduct</sgmltag> (MathML 2.0). </para></listitem> </varlistentry> <varlistentry> 360 <term>semantic mapping element</term> <listitem><para> <sgmltag class="element">annotation</sgmltag>,<sgmltag class="element">semantics</sgmltag>, <sgmltag class="element">annotation-xml</sgmltag>. </para></listitem> 365 </varlistentry> <varlistentry> <term>constant and symbol element (all MathML 2.0)</term> <listitem><para> <sgmltag class="element">integers</sgmltag>,<sgmltag class="element">reals</sgmltag>, 370 <sgmltag class="element">rationals</sgmltag>,<sgmltag class="element">naturalnumbers</sgmltag>, <sgmltag class="element">complexes</sgmltag>,<sgmltag class="element">primes</sgmltag>, <sgmltag class="element">exponentiale</sgmltag>,<sgmltag class="element">imaginaryi</sgmltag>, <sgmltag class="element">notanumber</sgmltag>,<sgmltag class="element">true</sgmltag>, <sgmltag class="element">false</sgmltag>,<sgmltag class="element">emptyset</sgmltag>, 375 <sgmltag class="element">pi</sgmltag>,<sgmltag class="element">eulergamma</sgmltag>, <sgmltag class="element">infinity</sgmltag>. </para></listitem> </varlistentry> </variablelist> 380 </para> <sect2> <title>An example with content markup</title> 385 <para> The matrix example given in the preceding section in its presentation markup form if recoded here using content markup. <programlisting><reln> <eq/> 390 <ci>A</ci> <matrix> <matrixrow> <ci>x</ci><ci>y</ci> </matrixrow> 395 <matrixrow> <ci>z</ci><ci>w</ci> </matrixrow> </matrix> </reln> 400 </programlisting> </para> </sect2> </sect1> 405 <bibliography> <title>Bibliographic references</title> <biblioentry id="bib.xml"> <abbrev id="bib.xml.abbrev">XML98</abbrev> <authorgroup> 410 <author><othername>World Wide Web Consortium</othername></author> <editor><firstname>Tim</firstname><surname>Bray</surname></editor> <editor><firstname>Jean</firstname><surname>Paoli</surname></editor> <editor><firstname>Michael</firstname><surname>Sperberg-McQueen</surname></editor> </authorgroup> 415 <title> <ulink url="http://www.w3.org/TR/REC-xml/">Extensible Markup Language (XML) 1.0</ulink></title> <bibliomisc> See also the <ulink url="http://www.xml.com/axml/axml.html">annotated 420 version of the XML specification</ulink>.</bibliomisc> </biblioentry> <biblioentry id="bib.TDG99"> <abbrev id="bib.TDG99.abbrev">TDG1999</abbrev> <authorgroup> 425 <author><firstname>Norman</firstname><surname>Walsh</surname></author> <author><firstname>Leonard</firstname><surname>Muellner</surname></author> </authorgroup> <title>Docbook. The Definitive Guide.</title> <publisher> 430 <publishername>O'Reilly & Associates, Inc.</publishername> </publisher> <copyright><year>1999</year></copyright> <isbn>1-56592-580-7</isbn> <releaseinfo><ulink 435 url= "http://www.oreilly.com/catalog/docbook/index.html">Oreilly's catalog entry</ulink>. </releaseinfo> <bibliomisc> You can also consult the <ulink url= 440 "http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html"> online version of the DocBook reference guide</ulink> and download the <ulink url="http://sourceforge.net/projects/docbook/">Docbook DTD and XSL stylesheets</ulink>.</bibliomisc> </biblioentry> 445 <biblioentry id="bib.mathml"> <abbrev id="bib.mathml.abbrev">MATHML2</abbrev> <authorgroup> <author><othername>World Wide Web Consortium</othername></author> <editor><firstname>David</firstname><surname>Carlisle</surname></editor> 450 <editor><firstname>Patrick</firstname><surname>Ion</surname></editor> <editor><firstname>Robert</firstname><surname>Miner</surname></editor> <editor><firstname>Nico</firstname><surname>Poppelier</surname></editor> </authorgroup> 455 <title><ulink url="http://www.w3.org/TR/MathML2/">Mathematical Markup Language (MathML) Version 2.0</ulink> </title> </biblioentry> </bibliography> 460 </article>
The result of transforming the DocBook source of this appendix into PDF (with docbook2pdf, see Example 1.6 in Section 1.7) is shown in Figure B.1.
We can also transform the DocBook source into HTML with docbook2html, as explained in Section 1.5. On the one hand, we can convert it into a single output file (as in Example 1.2), and the result is shown in Figure B.2 as displayed with the Mozilla browser. This figure corresponds to the beginning of the output file. On the other hand, Figure B.3 shows one of the chunks generated when running docbook2html with the chunk option (see Example 1.4 for an explanation). For large files it is more efficient to use chunking to allow handling of reasonably-sezed output files that have to be served over the Web.
- ASCII
(American Standard Code for Information Interchange) This standard character encoding scheme is used extensively in data transmission.
- ANSI
(American National Standards Institute) This group is the U.S. member organization that belongs to the ISO, the International Organization for Standardization.
- attribute
Attributes augment the element on which they appear; they also provide additional information about the element.
Attributes appear as name-value pairs in the element's start-tag. For example, to assign the value hostname to the role attribute of systemitem, you would use the mark up: <systemitem role="hostname">.
- callout
A pointer, verbal or graphical or both, to a component of an illustration or a text object.
- cooked
“Cooked” data, as distinct from “raw,” is a collection of elements and character data that's ready for presentation. The processor is not expected to rearrange, select, or suppress any of the elements, but simply present them as specified.
See Also Raw.
- document type declaration (DTD)
A set of declarations that defines the names of the elements and their attributes, and that specifies rules for their combination or sequence. You can store a DTD at the beginning of a document or externally in a separate file.
- element
Elements define the hierarchical structure of a document. that may They contain either text or other subelements such as a paragraph, a chapter, and so on. In XML all elements have start and end tags and contain some part of the document content. Empty elements have no content.
- element declaration
A statement in the DTD defining an element and declaring the order in which it may appear in the document and what other elements it may include.
- entity
A name assigned (by means of a declaration) to some chunk of data so it can be referred to by that name; the data can be of various kinds: a string of characters, a special character (e.g., unavailable on a standard keyboard), a external chapter or graphics file, or a set of declarations in a DTD, for instance. The way an entity is referred to depends on the type of data and where it is being referenced. XML has parameter, external, internal, and data entities.
- entity declaration
A statement in the DTD or document that assigns an XML/L name to an entity so you can reference it.
- external entity
An external entity is a general entity that refers to another document. External entities are often used to incorporate parsable text documents, like legal notices or chapters, into larger units, like chapters or books.
- external subset
Element, attribute, and other declarations that compose (part of) a document type definition that are stored in an external entity, and referenced from a document's document type declaration using a public or system identifier.
- float
Text objects like sidebars, figures, tables, and graphics are said to float when their actual place in the document is not fixed. For presentation on a printed page, for instance, a graphic may float to the top of the next page if it is too tall to fit on the page in which it actually falls, in the sequence of words and the sequence of other like objects in a document.
- general entity
An entity referenced by a name that starts with an ampersand (&) and ends with a semicolon. Most of the time general entities are used in SGML/XML documents, not in the DTD. There are two types, external and internal entities, and they refer either to special characters or to text objects like commonly repeated phrases or names or chapters.
- HTML
(HyperText Markup Language) This is the format of files published on the World Wide Web. HTML is an application of SGML/XML; to author in HTML using SGML/XML-based authoring software, you simply need the HTML DTD.
- internal entity
A general entity that references a piece of text (including its markup and even other internal entities), usually as a keyboard shortcut.
- internal subset
Element, attribute, and other declarations that compose (part of) a document type definition that are stored in a document, within the document type declaration.
- Internet
The Internet is a worldwide communications network originally developed by the U.S. Department of Defense as a distributed system with no single point of failure. The Internet has seen an explosion in commercial use since the development of easy-to-use software for accessing the Internet.
- ISO
(International Organization for Standardization) The ISO is an industry-supported organization that establishes worldwide standards for everything from data interchange formats to film speed specifications.
- markup
Markup is anything added to the content of the document that describes the text.
- meta-information
Meta-information is information about a document, such as the specification of its author or its date of composition, as opposed to the content of a document itself.
- parameter entity
An entity usually referenced in the DTD by a name that starts with a percent sign (%) and ends with a semicolon. In DocBook, parameter entities are mainly used to facilitate customization of the DTD, but they can also be used to control marked sections of a document.
- parser
A parser is a specialized software program that recognizes XML markup in a document. A parser that reads a DTD and checks and reports on markup errors is a validating XML parser. A parser can be built into an XML editor to prevent incorrect tagging and to check whether a document contains all the required elements.
- processing instruction
An essentially arbitrary string preceded by a question mark and delimited by angle brackets that is intended to convey information to an application that processes an XML instance. For example, the processing instruction <?linebreak> might cause the formatter to introduce a line break at the position where the processing instruction occurs.
In XML documents, processing instructions should have the form:
<?pitarget param1="value1" param2="value2"?>
The pitarget should be a name that the processing application will recognize. Additional information in the PI should be added using “attribute syntax.”
- public identifier
An abstract identifier for an SGML or XML document, DTD, or external entity.
- raw
“Raw” data is just a collection of elements, with no additional punctation or information about presentation. To continue the cooking metaphor, raw data is just a set of ingredients. It's up to the processor to select appropriate elements, arrange them for display, and add required presentational information.
See Also Cooked.
- SGML
Standard Generalized Markup Language, an international standard (ISO 8879) that specifies the rules for the creation of platform-independent markup languages for electronic texts.
- stylesheet
A file that specifies the presentation or appearance of a document; there are several standards for such stylesheets, including CSS, FOSIs, DSSSL, and, most recently, XSL. Vendors often have proprietary stylesheet formats as well.
- system identifier
In SGML/XML, a local, system-dependent identifier for a document, DTD, or external entity. Usually a filename on the local system.
- tag
In the world of SGML/XML, a tag is a marker embedded in a document that indicates the purpose or function of the element. Each element has a beginning tag and an end tag, or is empty Iis syntax is a name enclosed in angle brackets (<>). For instance, <para> is a tag in DocBook used to mark the beginning of a paragraph, </para> marks the end of a paragraph, while <xref ... /> is an empty tag.
- Unicode
The Unicode Consortium is a non-profit organization founded to develop, extend and promote use of the Unicode Standard, which specifies the representation of multi-lingual text in modern software products and standards.
Unicode supports characters that are one to four bytes wide rather than the 8-bit codes currently supported by most systems. In each of its seventeen 16-bit planes (numbered 0 to 16) Unicode encodes 65,536 characters rather than only 256 for one-byte encodings, such as ASCII, ISO-8859-1, etc. Thus, in total, Unicode allows one to encode well over 1 million characters.
In its Basic Multilingual Plane (Plane 0, BMP) it encodes most of the world's commonly-used languages, with rarer, ancient, or specialized characters encoded in the higher planes. The first 128 code points coincide with ASCII, so that for text using that character set only one byte is needed, whereas for mots other languages two byte suffice.
Of particular interest are the XML standard encodings UTF-8 (Unicode Transformation Format, 8-bit encoding form), which serializes a Unicode scalar value (code point) as a sequence of one to four bytes, and UTF-16 (Unicode Transformation Format, 16-bit encoding form), which serializes a Unicode scalar value (code point) as a sequence of two bytes, in either big-endian or little-endian format.
- URI
Uniform Resource Identifier, the W3C's codification of the name and address syntax of present and future objects on the Internet. In its most basic form, a URI consists of a scheme name (such as file, http, ftp, news, mailto, gopher) followed by a colon, followed by a path whose nature is determined by the scheme that precedes it (see RFC 1630).
URI is the umbrella term for URNs, URLs, and all other Uniform Resource Identifiers.
- URL
Uniform Resource Locator, a name and address for an existing object accessible over the Internet. http://www.docbook.org is an example of a URL (see RFC 1738).
- URN
Uniform Resource Name, the result of an evolving attempt to define a name and address syntax for persistent objects accessible over the Internet; urn:foo:a123,456 is a legal URN consisting of three colon-separated fields: urn followed by a namespace identifier, followed by a namespace specifier (see RFC 1737 and RFC 2141 for details).
- W3C
The World Wide Web Consortium (http://www.w3.org/).
- World Wide Web
Often referred to as WWW or the Web, this usually refers to information available on the Internet that can be easily accessed with software usually called a “browser.” Organizations publish their information on the Web in a format known as HTML (or more recently in XML with an accompanying CSS or XSL stylesheet). This information is usually referred to as their “home page” or “web site”.
- wrapper
Some elements, such as chapter, have important semantic significance. Other elements serve no obvious purpose except to contain a number of other elements. For example, bookinfo has no important semantics; it merely serves as a container for the meta-information about a book. Elements that are just containers are sometimes called “wrappers.”
- XML
The Extensible Markup Language, a subset of SGML designed specifically for use over the Web.
- XSL
XML Style Language, an evolving language for stylesheets to be attached to XML documents. The stylesheet is itself an XML document.
The present appendix list alphabetically all elements that are defined in version 4 of the DocBook DTD. For each element a one line description is given. For more details the [DocBook Reference Guide] should be consulted.
abbrev - An abbreviation, especially one followed by a period
acronym - An often pronounceable word made from the initial (or selected) letters of a name or phrase
affiliation - The institutional affiliation of an individual
area - A region defined for a Callout in a graphic or code example
areaset - A set of related areas in a graphic or code example
areaspec - A collection of regions in a graphic or code example
audioobject - A wrapper for audio data and its associated meta-information
authorgroup - Wrapper for author information when a document has multiple authors or collabarators
authorinitials - The initials or other short identifier for an author
beginpage - The location of a page break in a print version of the document
bibliomset - A cooked container for related bibliographic information
biblioset - A raw container for related bibliographic information
citation - An inline bibliographic reference to another published work
classname - The name of a class, in the object-oriented programming sense
classsynopsisinfo - Information supplementing the contents of a ClassSynopsis
colophon - Text at the back of a book describing facts about its production
command - The name of an executable program or other software command
computeroutput - Data, generally text, displayed or presented by a computer
confdates - The dates of a conference for which a document was written
confgroup - A wrapper for document meta-information about a conference
confnum - An identifier, frequently numerical, associated with a conference for which a document was written
confsponsor - The sponsor of a conference for which a document was written
conftitle - The title of a conference for which a document was written
constraintdef (EBNF) - The definition of a constraint in an EBNF production
contrib - A summary of the contributions made to a document by a credited source
corpauthor - A corporate author, as opposed to an individual
entrytbl - A subtable appearing in place of an Entry in a table
epigraph - A short inscription at the beginning of a document or component
figure - A formal figure, generally an illustration, with a title
footnoteref - A cross reference to a footnote (a footnote mark)
foreignphrase - A word or phrase in a language other than the primary language of the document
funcparams - Parameters for a function referenced through a function pointer in a synopsis
funcsynopsisinfo - Information supplementing the FuncDefs of a FuncSynopsis
function - The name of a function or subroutine, as in a programming language
glossseealso - A cross-reference from one GlossEntry to another
highlights - A summary of the main points of the discussed component
holder - The name of the individual or organization that holds a copyright
imageobject - A wrapper for image data and its associated meta-information
informalequation - A displayed mathematical equation without a title
inlineequation - A mathematical equation or expression occurring inline
inlinegraphic - An object containing or pointing to graphical data that will be rendered inline
inlinemediaobject - An inline media object (video, audio, image, and so on)
issn - The International Standard Serial Number of a periodical
itemizedlist - A list in which each entry is marked with a bullet or other dingbat
itermset - A set of index terms in the meta-information of a document
keycode - The internal, frequently numeric, identifier for a key on a keyboard
keyword - One of a set of keywords describing the content of a document
keywordset - A set of keywords describing the content of a document
legalnotice - A statement of legal obligations or requirements
lineage - The portion of a person's name indicating a relationship to ancestors
literallayout - A block of text in which line breaks and white space are to be reproduced faithfully
lot - A list of the titles of formal objects (as tables or figures) in a document
markup - A string of formatting markup in text that is to be represented literally
medialabel - A name that identifies the physical medium on which some information resides
mediaobject - A displayed media object (video, audio, image, etc.)
menuchoice - A selection or series of selections from a menu
modespec - Application-specific information necessary for the completion of an OLink
msgaud - The audience to which a message in a message set is relevant
msgexplan - Explanatory material relating to a message in a message set
msglevel - The level of importance or severity of a message in a message set
msgmain - The primary component of a message in a message set
msgtext - The actual text of a message component in a message set
olink - A link that addresses its target indirectly, through an entity
ooclass - A class in an object-oriented programming language
ooexception - An exception in an object-oriented programming language
oointerface - An interface in an object-oriented programming language
orderedlist - A list in which each entry is marked with a sequentially incremented label
orgname - The name of an organization other than a corporation
othercredit - A person or entity, other than an author or editor, credited in a document
othername - A component of a persons name that is not a first name, surname, or lineage
pagenums - The numbers of the pages in a book, for use in a bibliographic entry
paramdef - Information about a function parameter in a programming language
preface - Introductory matter preceding the first chapter of a book
primary - The primary word or phrase under which an index term should be sorted
primaryie - A primary term in an index entry, not in the text
procedure - A list of operations to be performed in a well-defined sequence
production (EBNF) - A production in a set of EBNF productions
productionrecap (EBNF) - A cross-reference to an EBNF production
programlisting - A literal listing of all or part of a program
programlistingco - A program listing with associated areas used in callouts
prompt - A character or string indicating the start of an input field in a computer display
property - A unit of data associated with some part of a computer system
pubsnumber - A number assigned to a publication other than an ISBN or ISSN or inventory part number
refclass - The scope or other indication of applicability of a reference entry
refdescriptor - A description of the topic of a reference page
refentry - A reference page (originally a UNIX man-style reference page)
refmiscinfo - Meta-information for a reference entry other than the title and volume number
refname - The name of (one of) the subject(s) of a reference page
refnamediv - The name, purpose, and classification of a reference page
refpurpose - A short (one sentence) synopsis of the topic of a reference page
refsynopsisdiv - A syntactic synopsis of the subject of the reference page
releaseinfo - Information about a particular release of a document
remark - A remark (or comment) intended for presentation in a draft manuscript
replaceable - Content that may or must be replaced by the user
revdescription - A extended description of a revision to a document
revision - An entry describing a single revision in the history of the revisions to a document
screen - Text that a user sees or might see on a computer screen
screeninfo - Information about how a screen shot was produced
screenshot - A representation of what the user sees or might see on a computer screen
secondaryie - A secondary term in an index entry, rather than in the text
see - Part of an index term directing the reader instead to another entry in the index
seealso - Part of an index term directing the reader also to another entry in the index
seealsoie - A See also entry in an index, rather than in the text
segmentedlist - A segmented list, a list of sets of elements
segtitle - The title of an element of a list item in a segmented list
shortcut - A key combination for an action that is also accessible through a menu
sidebar - A portion of a document that is isolated from the main narrative flow
simpara - A paragraph that contains only text and inline markup, no block elements
simplelist - An undecorated list of single words or short phrases
simplemsgentry - A wrapper for a simpler entry in a message set
spanspec - Formatting information for a spanned column in a table
structfield - A field in a structure (in the programming language sense)
structname - The name of a structure (in the programming language sense)
subject - One of a group of terms describing the subject matter of a document
subjectset - A set of terms describing the subject matter of a document
subjectterm - A term in a group of terms describing the subject matter of a document
subscript - A subscript (as in H2O, the molecular formula for water)
substeps - A wrapper for steps that occur within steps in a procedure
superscript - A superscript (as in x2, the mathematical notation for x multiplied by itself)
symbol - A name that is replaced by a value before processing
synopfragment - A portion of a CmdSynopsis broken out from the main body of the synopsis
synopfragmentref - A reference to a fragment of a command synopsis
synopsis - A general-purpose element for representing the syntax of commands or functions
term - The word or phrase being defined or described in a variable list
tertiaryie - A tertiary term in an index entry, rather than in the text
textobject - A wrapper for a text description of an object and its associated meta-information
tgroup - A wrapper for the main content of a table, or part of a table
title - The text of the title of a section of a document or of a formal block-level element
tocback - An entry in a table of contents for a back matter component
tocchap - An entry in a table of contents for a component in the body of a document
tocfront - An entry in a table of contents for a front matter component
toclevel1 - A top-level entry within a table of contents entry for a chapter-like component
toclevel2 - A second-level entry within a table of contents entry for a chapter-like component
toclevel3 - A third-level entry within a table of contents entry for a chapter-like component
toclevel4 - A fourth-level entry within a table of contents entry for a chapter-like component
toclevel5 - A fifth-level entry within a table of contents entry for a chapter-like component
tocpart - An entry in a table of contents for a part of a book
ulink - A link that addresses its target by means of a URL (Uniform Resource Locator)
varargs - An empty element in a function synopsis indicating a variable number of arguments
variablelist - A list in which each entry is composed of a set of one or more terms and an associated description
varlistentry - A wrapper for a set of terms and the associated description in a variable list
videoobject - A wrapper for video data and its associated meta-information
void - An empty element in a function synopsis indicating that the function in question takes no arguments
volumenum - The volume number of a document in a set (as of books in a set or articles in a journal)
wordasword - A word meant specifically as a word and not representing anything else
A
- acroread, Translation to PDF
- addresses, Internet syntax, Glossary
- angle brackets
- appearance
- Attributes
- attributes, Glossary
C
- callouts, Glossary
- chunk
- docbook2html, Translation to HTML, A complete example of a DocBook article
- cooked data, Glossary
- raw data
- customization (DocBook DTD)
- parameter entities, using, Glossary
D
- data entities, Glossary
- declarations
- document type declaration, Glossary
- DocBook DTD
- customizing
- parameter entities, Glossary
- docbook2html, Translation to HTML, Handling
- docbook2pdf, Translation to PDF, Handling, A complete example of a DocBook article
- document type declaration, Glossary
- documents
- DTDs
- public identifiers, Glossary
E
- Elements
- abbrev, Overview of all DocBook elements
- abbrev , Bibliograpy elements
- abstract, Meta Information, Overview of all DocBook elements
- abstract , Bibliograpy elements
- accel, Overview of all DocBook elements
- accel - keycap , GUI Interface Elements
- ackno, Overview of all DocBook elements
- acronym, Overview of all DocBook elements
- action, Overview of all DocBook elements
- action , GUI Interface Elements
- address, Overview of all DocBook elements
- address , Bibliograpy elements
- affiliation, Overview of all DocBook elements
- affiliation , Bibliograpy elements
- alt, Overview of all DocBook elements
- anchor, Overview of all DocBook elements
- anchor , Links
- answer, Overview of all DocBook elements
- answer , Lists
- appendix, Overview of all DocBook elements
- appendixinfo, Overview of all DocBook elements
- application, Overview of all DocBook elements
- application , Labelling Tags
- area, Overview of all DocBook elements
- areaset, Overview of all DocBook elements
- areaspec, Overview of all DocBook elements
- arg, Overview of all DocBook elements
- arg , Command Line Elements
- article, Overview of all DocBook elements
- articleinfo, Meta Information, Overview of all DocBook elements
- artpagenums, Overview of all DocBook elements
- artpagenums , Bibliograpy elements
- attribution, Overview of all DocBook elements
- audiodata, Overview of all DocBook elements
- audioobject, Overview of all DocBook elements
- author, Meta Information, Overview of all DocBook elements
- author , Bibliograpy elements
- authorblurb, Overview of all DocBook elements
- authorblurb , Bibliograpy elements
- authorgroup, Meta Information, Overview of all DocBook elements
- authorgroup , Bibliograpy elements
- authorinitials, Meta Information, Overview of all DocBook elements
- authorinitials , Bibliograpy elements
- beginpage, Overview of all DocBook elements
- bibliodiv, Overview of all DocBook elements
- bibliodiv , Bibliograpy elements
- biblioentry, Overview of all DocBook elements
- biblioentry , Bibliograpy elements
- bibliography, Overview of all DocBook elements
- bibliography , Bibliograpy elements
- bibliographyinfo, Overview of all DocBook elements
- bibliographyinfo , Bibliograpy elements
- bibliomisc, Overview of all DocBook elements
- bibliomisc , Bibliograpy elements
- bibliomixe , Bibliograpy elements
- bibliomixed, Overview of all DocBook elements
- bibliomixed , Bibliograpy elements
- bibliomset, Overview of all DocBook elements
- bibliomset , Bibliograpy elements
- biblioset, Overview of all DocBook elements
- biblioset , Bibliograpy elements
- blockquote, Overview of all DocBook elements
- book, Overview of all DocBook elements
- bookinfo, Meta Information, Overview of all DocBook elements
- bridgehead, Overview of all DocBook elements
- callout, Overview of all DocBook elements
- calloutlist, Overview of all DocBook elements
- caption, Overview of all DocBook elements
- caution, Overview of all DocBook elements
- caution , Warnings, Tips, and Notes
- chapter, Overview of all DocBook elements
- chapterinfo, Overview of all DocBook elements
- citation, Overview of all DocBook elements
- citation , Bibliograpy elements
- citerefentry, Overview of all DocBook elements
- citerefentry , Bibliograpy elements
- citetitle, Overview of all DocBook elements
- citetitle , Bibliograpy elements
- city, Overview of all DocBook elements
- city , Bibliograpy elements
- classname, Overview of all DocBook elements
- classname , Elements for classes and methods
- classsynopsis, Overview of all DocBook elements
- classsynopsis , Elements for classes and methods
- classsynopsisinfo, Overview of all DocBook elements
- classsynopsisinfo , Elements for classes and methods
- cmdsynopsis, Overview of all DocBook elements
- cmdsynopsis , Command Line Elements
- co, Overview of all DocBook elements
- collab, Overview of all DocBook elements
- collab , Bibliograpy elements
- collabname, Overview of all DocBook elements
- collabname , Bibliograpy elements
- colophon, Overview of all DocBook elements
- colspec, Overview of all DocBook elements
- command, Overview of all DocBook elements
- command , Command Line Elements
- computeroutput, Overview of all DocBook elements
- computeroutput , Command Line Elements
- confdates, Overview of all DocBook elements
- confgroup, Overview of all DocBook elements
- confgroup , Bibliograpy elements
- confnum, Overview of all DocBook elements
- confsponsor, Overview of all DocBook elements
- conftitle, Overview of all DocBook elements
- constant, Overview of all DocBook elements
- constraint, Overview of all DocBook elements
- constraintdef, Overview of all DocBook elements
- constructorsynopsis, Overview of all DocBook elements
- contractnum, Overview of all DocBook elements
- contractnum , Bibliograpy elements
- contractsponsor, Overview of all DocBook elements
- contractsponsor , Bibliograpy elements
- contrib, Overview of all DocBook elements
- contrib , Bibliograpy elements
- copyright, Overview of all DocBook elements
- copyright , Bibliograpy elements
- corpauthor, Overview of all DocBook elements
- corpauthor , Bibliograpy elements
- corpname, Overview of all DocBook elements
- corpname , Bibliograpy elements
- country, Overview of all DocBook elements
- country , Bibliograpy elements
- database, Overview of all DocBook elements
- date, Meta Information, Overview of all DocBook elements
- date , Bibliograpy elements
- dedication, Overview of all DocBook elements
- destructorsynopsis, Overview of all DocBook elements
- edition, Overview of all DocBook elements
- edition , Bibliograpy elements
- editor, Overview of all DocBook elements
- editor , Bibliograpy elements
- email, Overview of all DocBook elements
- email , Links
- Emphasis, Overview of all DocBook elements
- emphasis , Formatting Tags
- entry, A simple table, Overview of all DocBook elements
- entry , Tables
- entrytbl, A simple table, Overview of all DocBook elements
- entrytbl , Tables
- envar, Overview of all DocBook elements
- envar , Command Line Elements
- epigraph, Overview of all DocBook elements
- equation, Overview of all DocBook elements
- errorcode, Overview of all DocBook elements
- errorname, Overview of all DocBook elements
- errortype, Overview of all DocBook elements
- example, Overview of all DocBook elements
- example , Examples
- exceptionname, Overview of all DocBook elements
- exceptionname , Elements for classes and methods
- fax, Overview of all DocBook elements
- fieldsynopsis, Overview of all DocBook elements
- fieldsynopsis , Elements for classes and methods
- figure, Overview of all DocBook elements
- filename, Overview of all DocBook elements
- filename , Command Line Elements
- firstname, Overview of all DocBook elements
- firstname , Meta Information, Bibliograpy elements
- firstterm, Overview of all DocBook elements
- footnote, Overview of all DocBook elements
- footnoteref, Overview of all DocBook elements
- foreignphrase, Overview of all DocBook elements
- formalpara, Overview of all DocBook elements
- funcdef, Overview of all DocBook elements
- funcdef , Command Line Elements
- funcparams, Overview of all DocBook elements
- funcprototype, Overview of all DocBook elements
- funcprototype , Command Line Elements
- funcsynopsis, Overview of all DocBook elements
- funcsynopsis , Command Line Elements
- funcsynopsisinfo, Overview of all DocBook elements
- funcsynopsisinfo , Command Line Elements
- function, Overview of all DocBook elements
- function , Command Line Elements
- glossary, Overview of all DocBook elements
- glossaryinfo, Overview of all DocBook elements
- glossdef, Overview of all DocBook elements
- glossdiv, Overview of all DocBook elements
- glossentry, Overview of all DocBook elements
- glosslist, Overview of all DocBook elements
- glosssee, Overview of all DocBook elements
- glossseealso, Overview of all DocBook elements
- glossterm, Overview of all DocBook elements
- graphic, Overview of all DocBook elements
- graphicco, Overview of all DocBook elements
- group, Overview of all DocBook elements
- guibutton, Overview of all DocBook elements
- guibutton , GUI Interface Elements
- guiicon, Overview of all DocBook elements
- guiicon , GUI Interface Elements
- guilabel, Overview of all DocBook elements
- guilabel , GUI Interface Elements
- guimenu, Overview of all DocBook elements
- guimenu , GUI Interface Elements
- guimenuitem, Overview of all DocBook elements
- guimenuitem , GUI Interface Elements
- guisubmenu, Overview of all DocBook elements
- guisubmenu , GUI Interface Elements
- hardware, Overview of all DocBook elements
- highlights, Overview of all DocBook elements
- holder, Overview of all DocBook elements
- honorific, Overview of all DocBook elements
- honorific , Bibliograpy elements
- imagedata, Overview of all DocBook elements
- imagedata , Graphics
- imageobject, Graphics, Overview of all DocBook elements
- imageobjectco, Overview of all DocBook elements
- important, Overview of all DocBook elements
- important , Warnings, Tips, and Notes
- index, Overview of all DocBook elements
- indexdiv, Overview of all DocBook elements
- indexentry, Overview of all DocBook elements
- indexinfo, Overview of all DocBook elements
- indexterm, Overview of all DocBook elements
- informalequation, Overview of all DocBook elements
- informalexample, Overview of all DocBook elements
- informalexample , Examples
- informalfigure, Overview of all DocBook elements
- informaltable, Overview of all DocBook elements
- informaltable , Tables
- initializer, Overview of all DocBook elements
- inlineequation, Overview of all DocBook elements
- inlinegraphic, Overview of all DocBook elements
- inlinemediaobject, Graphics, Overview of all DocBook elements
- inlinemediaobject , Graphics
- interface, Overview of all DocBook elements
- interface , GUI Interface Elements
- interfacedefinition , GUI Interface Elements
- interfacename, Overview of all DocBook elements
- invpartnumber, Overview of all DocBook elements
- isbn, Overview of all DocBook elements
- isbn , Bibliograpy elements
- issn, Overview of all DocBook elements
- issn , Bibliograpy elements
- issuenum, Overview of all DocBook elements
- issuenum , Bibliograpy elements
- itemizedlist, Overview of all DocBook elements
- itemizedlist , Lists
- itermset, Overview of all DocBook elements
- jobtitle, Overview of all DocBook elements
- keycap, Overview of all DocBook elements
- keycap , GUI Interface Elements
- keycode, Overview of all DocBook elements
- keycode , GUI Interface Elements
- keycombo, Overview of all DocBook elements
- keycombo , GUI Interface Elements
- keysym, Overview of all DocBook elements
- keysym , GUI Interface Elements
- keyword, Meta Information, Overview of all DocBook elements
- keywordset, Overview of all DocBook elements
- keywordset , Meta Information
- label, Overview of all DocBook elements
- legalnotice, Overview of all DocBook elements
- lhs, Overview of all DocBook elements
- lineage, Overview of all DocBook elements
- lineannotation, Overview of all DocBook elements
- link, Overview of all DocBook elements
- link , Links
- link and xref , Links
- listitem, Overview of all DocBook elements
- listitem , Lists
- literal, Overview of all DocBook elements
- literal , Command Line Elements
- literallayout, Examples, Overview of all DocBook elements
- literallayout , Examples
- lot, Overview of all DocBook elements
- lotentry, Overview of all DocBook elements
- manvolnum, Overview of all DocBook elements
- markup, Overview of all DocBook elements
- markup , Labelling Tags
- medialabel, Overview of all DocBook elements
- mediaobject, Graphics, Overview of all DocBook elements
- mediaobject , Graphics
- mediaobjectco, Overview of all DocBook elements
- member, Overview of all DocBook elements
- member , Lists
- menuchoice, Overview of all DocBook elements
- menuchoice , GUI Interface Elements
- methodname, Overview of all DocBook elements
- methodname , Elements for classes and methods
- methodparam, Overview of all DocBook elements
- methodparam , Elements for classes and methods
- methodsynopsis, Overview of all DocBook elements
- methodsynopsis , Elements for classes and methods
- mml:math, Overview of all DocBook elements
- modespec, Overview of all DocBook elements
- modifier, Overview of all DocBook elements
- modifier , Elements for classes and methods
- mousebutton, Overview of all DocBook elements
- mousebutton , GUI Interface Elements
- msg, Overview of all DocBook elements
- msgaud, Overview of all DocBook elements
- msgentry, Overview of all DocBook elements
- msgexplan, Overview of all DocBook elements
- msginfo, Overview of all DocBook elements
- msglevel, Overview of all DocBook elements
- msgmain, Overview of all DocBook elements
- msgorig, Overview of all DocBook elements
- msgrel, Overview of all DocBook elements
- msgset, Overview of all DocBook elements
- msgsub, Overview of all DocBook elements
- msgtext, Overview of all DocBook elements
- nonterminal, Overview of all DocBook elements
- note, Overview of all DocBook elements
- note , Warnings, Tips, and Notes
- objectinfo, Overview of all DocBook elements
- olink, Overview of all DocBook elements
- olink , Links
- ooclass, Overview of all DocBook elements
- ooclass , Elements for classes and methods
- ooexception, Overview of all DocBook elements
- ooexception , Elements for classes and methods
- oointerface, Overview of all DocBook elements
- oointerface , Elements for classes and methods
- option, Overview of all DocBook elements
- option , Command Line Elements
- optional, Overview of all DocBook elements
- orderedlist, Overview of all DocBook elements
- orderedlist , Lists
- orgdiv, Overview of all DocBook elements
- orgname, Overview of all DocBook elements
- orgname , Bibliograpy elements
- otheraddr, Overview of all DocBook elements
- othercredit, Overview of all DocBook elements
- othercredit , Bibliograpy elements
- othername, Overview of all DocBook elements
- othername , Meta Information, Bibliograpy elements
- pagenums, Overview of all DocBook elements
- pagenums , Bibliograpy elements
- para, Overview of all DocBook elements
- paramdef, Overview of all DocBook elements
- paramdef , Command Line Elements
- parameter, Overview of all DocBook elements
- parameter , Command Line Elements
- part, Overview of all DocBook elements
- partinfo, Overview of all DocBook elements
- partintro, Overview of all DocBook elements
- phone, Overview of all DocBook elements
- phrase, Overview of all DocBook elements
- pob, Overview of all DocBook elements
- postcode, Overview of all DocBook elements
- preface, Overview of all DocBook elements
- prefaceinfo, Overview of all DocBook elements
- primary, Overview of all DocBook elements
- primaryie, Overview of all DocBook elements
- printhistory, Overview of all DocBook elements
- printhistory , Bibliograpy elements
- procedure, Overview of all DocBook elements
- procedure , Lists
- production, Overview of all DocBook elements
- productionrecap, Overview of all DocBook elements
- productionset, Overview of all DocBook elements
- productname, Overview of all DocBook elements
- productnumber, Overview of all DocBook elements
- programlisting, Examples, Overview of all DocBook elements
- programlisting , Examples
- programlistingco, Overview of all DocBook elements
- prompt, Overview of all DocBook elements
- prompt , Command Line Elements
- property, Overview of all DocBook elements
- pubdate, Overview of all DocBook elements
- pubdate , Bibliograpy elements
- publisher, Overview of all DocBook elements
- publisher , Bibliograpy elements
- publishername, Overview of all DocBook elements
- publishername , Bibliograpy elements
- pubsnumber, Overview of all DocBook elements
- pubsnumber , Bibliograpy elements
- qandadiv, Overview of all DocBook elements
- qandaentry, Overview of all DocBook elements
- qandaentry , Lists
- qandaset, Overview of all DocBook elements
- qandaset , Lists
- question, Overview of all DocBook elements
- question , Lists
- quote, Overview of all DocBook elements
- refclass, Overview of all DocBook elements
- refdescriptor, Overview of all DocBook elements
- refentry, Overview of all DocBook elements
- refentryinfo, Overview of all DocBook elements
- refentrytitle, Overview of all DocBook elements
- reference, Overview of all DocBook elements
- referenceinfo, Overview of all DocBook elements
- refmeta, Overview of all DocBook elements
- refmiscinfo, Overview of all DocBook elements
- refname, Overview of all DocBook elements
- refnamediv, Overview of all DocBook elements
- refpurpose, Overview of all DocBook elements
- refsect1, Overview of all DocBook elements
- refsect1info, Overview of all DocBook elements
- refsect2, Overview of all DocBook elements
- refsect2info, Overview of all DocBook elements
- refsect3, Overview of all DocBook elements
- refsect3info, Overview of all DocBook elements
- refsynopsisdiv, Overview of all DocBook elements
- refsynopsisdivinfo, Overview of all DocBook elements
- releaseinfo, Overview of all DocBook elements
- releaseInfo , Meta Information
- releaseinfo , Bibliograpy elements
- remark, Overview of all DocBook elements
- replaceable, Overview of all DocBook elements
- replaceable , Command Line Elements
- returnvalue, Overview of all DocBook elements
- revdescription, Overview of all DocBook elements
- revhistory, Overview of all DocBook elements
- revhistory , Meta Information, Bibliograpy elements
- revision, Overview of all DocBook elements
- revision , Meta Information
- revnumber, Overview of all DocBook elements
- revnumber , Meta Information
- revremark, Overview of all DocBook elements
- revremark , Meta Information
- rhs, Overview of all DocBook elements
- row, A simple table, Overview of all DocBook elements
- row , Tables
- sbr, Overview of all DocBook elements
- screen, Examples, Overview of all DocBook elements
- screen , Examples
- screenco, Overview of all DocBook elements
- screeninfo, Graphics, Overview of all DocBook elements
- screeninfo , Graphics
- screenshot, Graphics, Overview of all DocBook elements
- screenshot , Graphics
- secondary, Overview of all DocBook elements
- secondaryie, Overview of all DocBook elements
- sect1, Overview of all DocBook elements
- sect1info, Overview of all DocBook elements
- sect2, Overview of all DocBook elements
- sect2info, Overview of all DocBook elements
- sect3, Overview of all DocBook elements
- sect3info, Overview of all DocBook elements
- sect4, Overview of all DocBook elements
- sect4info, Overview of all DocBook elements
- sect5, Overview of all DocBook elements
- sect5info, Overview of all DocBook elements
- section, Overview of all DocBook elements
- sectioninfo, Overview of all DocBook elements
- see, Overview of all DocBook elements
- seealso, Overview of all DocBook elements
- seealsoie, Overview of all DocBook elements
- seeie, Overview of all DocBook elements
- seg, Overview of all DocBook elements
- seg , Lists
- seglistitem, Overview of all DocBook elements
- seglistitem , Lists
- segmentedlist, Overview of all DocBook elements
- segmentedlist , Lists
- segtitle, Overview of all DocBook elements
- segtitle , Lists
- seriesvolnums, Overview of all DocBook elements
- seriesvolnums , Bibliograpy elements
- set, Overview of all DocBook elements
- setindex, Overview of all DocBook elements
- setindexinfo, Overview of all DocBook elements
- setinfo, Overview of all DocBook elements
- sgmltag, Overview of all DocBook elements
- shortaffil, Overview of all DocBook elements
- shortcut, Overview of all DocBook elements
- sidebar, Overview of all DocBook elements
- sidebarinfo, Overview of all DocBook elements
- simpara, Overview of all DocBook elements
- simplelist, Overview of all DocBook elements
- simplelist , Lists
- simplemsgentry, Overview of all DocBook elements
- simplesect, Overview of all DocBook elements
- spanspec, Overview of all DocBook elements
- state, Overview of all DocBook elements
- step, Overview of all DocBook elements
- step , Lists
- street, Overview of all DocBook elements
- structfield, Overview of all DocBook elements
- structname, Overview of all DocBook elements
- subject, Overview of all DocBook elements
- subjectset, Overview of all DocBook elements
- subjectterm, Overview of all DocBook elements
- subscript, Overview of all DocBook elements
- subscript , Formatting Tags
- substeps, Overview of all DocBook elements
- substeps , Lists
- subtitle, Overview of all DocBook elements
- subtitle , Bibliograpy elements
- superscript, Overview of all DocBook elements
- superscript , Formatting Tags
- surname, Overview of all DocBook elements
- surname , Meta Information, Bibliograpy elements
- svg:svg, Overview of all DocBook elements
- symbol, Overview of all DocBook elements
- symbol , Command Line Elements
- synopfragment, Overview of all DocBook elements
- synopfragmentref, Overview of all DocBook elements
- synopsis, Overview of all DocBook elements
- systemitem, Overview of all DocBook elements
- table, Overview of all DocBook elements
- table , Tables
- tbody, Overview of all DocBook elements
- tbody , Tables
- term, Overview of all DocBook elements
- term , Lists
- tertiary, Overview of all DocBook elements
- tertiaryie, Overview of all DocBook elements
- textobject, Overview of all DocBook elements
- tfoot, Overview of all DocBook elements
- tfoot , Tables
- tgroup, A simple table, Overview of all DocBook elements
- tgroup , Tables
- thead, Overview of all DocBook elements
- thead , Tables
- tip, Overview of all DocBook elements
- tip , Warnings, Tips, and Notes
- title, A simple table, Overview of all DocBook elements
- title , Meta Information, Links, Bibliograpy elements
- titleabbrev, Overview of all DocBook elements
- titleabbrev , Bibliograpy elements
- toc, Overview of all DocBook elements
- tocback, Overview of all DocBook elements
- tocchap, Overview of all DocBook elements
- tocentry, Overview of all DocBook elements
- tocfront, Overview of all DocBook elements
- toclevel1, Overview of all DocBook elements
- toclevel2, Overview of all DocBook elements
- toclevel3, Overview of all DocBook elements
- toclevel4, Overview of all DocBook elements
- toclevel5, Overview of all DocBook elements
- tocpart, Overview of all DocBook elements
- token, Overview of all DocBook elements
- trademark, Overview of all DocBook elements
- type, Overview of all DocBook elements
- type , Command Line Elements
- ulink, Overview of all DocBook elements
- ulink , Links
- userinput, Overview of all DocBook elements
- userinput , Command Line Elements
- varargs, Overview of all DocBook elements
- variablelist, Overview of all DocBook elements
- variablelist , Lists
- varlistentry, Overview of all DocBook elements
- varlistentry , Lists
- varname, Overview of all DocBook elements
- videodata, Overview of all DocBook elements
- videoobject, Overview of all DocBook elements
- void, Overview of all DocBook elements
- volumenum, Overview of all DocBook elements
- volumenum , Bibliograpy elements
- warning, Overview of all DocBook elements
- warning , Warnings, Tips, and Notes
- wordasword, Overview of all DocBook elements
- xref, Overview of all DocBook elements
- xref , Links
- year, Overview of all DocBook elements
- elements, Glossary
- empty elements, Glossary
- entities, Glossary
- general, Glossary
- Extensible Markup Language
- XML
- external general entities, Glossary
- public identifiers, Glossary
- external subset, Glossary
F
- float, Glossary
G
- general entities, Glossary
- ghostview, Translation to PDF
H
I
M
N
- names
- Internet, syntax, Glossary