    |
DocBook: The Definitive Guide 0.0.25 for DocBook V5.0 (Alpha) |
| |
DocBook: The Definitive Guide 0.0.25 for DocBook V5.0 (Alpha) |
$Revision: 7789 $
$Date: 2008-03-03 09:16:22 -0500 (Mon, 03 Mar 2008) $
This chapter explains in concrete, practical terms how to make DocBook documents. It's an overview of all the kinds of markup that are possible in DocBook documents. It explains how to create several kinds of DocBook documents: books, sets of books, chapters, articles, and reference manual entries. The idea is to give you enough basic information to actually start writing. The information here is intentionally skeletal; you can find the details in the reference section of this book.
An XML document consists of an optional XML Declaration, an optional Document Type Declaration, which includes an optional Internal Subset, and a Document (or Root) Element. We'll discuss each of these in turn.
In XML vocabularies like DocBook which are defined with RELAX NG (and also in the case of vocabularies defined with W3C's XML Schema), it is common to omit the Document Type Declaration entirely. The Document Type Declaration associates a document with a particular Document Type Definition (DTD).
XML documents often begin with an XML declaration that identifies a few simple aspects of the document, for example:
<?xml version="1.0" encoding="utf-8"?>
Identifying the version of XML ensures that future changes to the XML specification will not alter the semantics of this document. The encoding declaration tells the processor what character encoding this document uses. It must match the actual encoding that you use. The complete details of the XML declaration are described in the XML specification.
If your document uses XML 1.0 and an encoding of either utf-8 or utf-16, the XML Declaration is not required. But it is never wrong to include it. If you do not include an XML declaration, your document must conform to XML 1.0. If you want to use XML 1.1, you must include an XML Declaration and specify version="1.1" in it.
The XML Declaration is syntactically similar to a processing instruction, but it is not. The XML Declaration, if it is present, must be absolutely the first thing in your document and it may not appear anywhere else.
XML documents don't require a DTD and if you are using RELAX NG, often they will not include one. Historically, DocBook XML documents have almost always had one.
The document type declaration identifies what the root element of the document will be and may specify the DTD that should be used when parsing the document. A typical doctype declaration for a DocBook V4.5 document looks like this:
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
This declaration indicates that the root element will be book and that the DTD used will be DocBook V4.5, identified with both its public and system identifiers. In this example, the DTD identified with an HTTP URI. System identifiers in XML must be URIs. Almost all systems accept filenames and interpret them locally as file: URLs, but it's always correct to fully qualify them.
You can specify a DTD for DocBook V5.0 documents:
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">
But the limited constraints that can be expressed in DTDs mean that the resulting document may or may not really be valid DocBook V5.0. The normative schema for DocBook V5.0 is the RELAX NG Grammar with its Schematron annotations.
The only reason to use a DTD with DocBook V5.0 is if your editing environment (or other tool) requires one, for example, for syntax directed editing. If you're using tools that require DTDs, check with the vendor, maybe a more recent version is available that supports RELAX NG.
One reason to use a Document Type Declaration with DocBook V5.0 is to provide local declarations such as entities:
<?xml version='1.0'?> <!DOCTYPE book [ <!ENTITY nwalsh "Norman Walsh"> <!ENTITY chap1 SYSTEM "chap1.xml"> <!ENTITY chap2 SYSTEM "chap2.xml"> ]>
These declarations form what is known as the internal subset. In this example, the DTD has been omitted, but the two are not mutually exclusive. If you are using a DTD (which is technically known as the “external subset”), you can include the internal subset immediately after the DTD:
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0/EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd" [
<!ENTITY nwalsh "Norman Walsh">
<!ENTITY chap1 SYSTEM "chap1.xml">
<!ENTITY chap2 SYSTEM "chap2.xml">
]>
When both are specified, the internal subset is parsed first. If multiple declarations for an entity occur, the first declaration is used. This means that declarations in the internal subset override declarations in the external subset.
All XML documents must have exactly one root element, although it may have sibling comments and processing instructions. If the document has a document type declaration, the root element usually immediately follows it:
<?xml version='1.0'?> <!DOCTYPE book [ <!ENTITY nwalsh "Norman Walsh"> <!ENTITY chap1 SYSTEM "chap1.xml"> <!ENTITY chap2 SYSTEM "chap2.xml"> ]> <book xmlns="http://docbook.org/ns/docbook">…</book>
The important point is that the root element must be physically present immediately after the document type declaration. You cannot place the root element of the document in an external entity.
When a DTD or other external entity is referenced from a document, the reference can be specified in three ways: using a public identifier, a system identifier, or both. In XML, the system identifier is required and the public identifier is optional. Taken together, the combination of an optional public identifier and a system identifier is known as a external identifier.
A public identifier is a globally unique, abstract name, such as the following, which is the official public identifier for DocBook V4.5:
-//OASIS//DTD DocBook XML V4.5//EN
In XML the system identifier must be a Uniform Resource Identifier (URI). The most common URI today is the Uniform Resource Locator (URL), which is familiar to anyone who browses the Web.
The historical advantage of using a public identifier is that it made your documents more portable. For any system on which DocBook is installed, the public identifier will resolve to the appropriate local version of the DTD (if public identifiers can be resolved at all). Today most systems can resolve system identifiers in a similar way.
Public identifiers have two disadvantages:
Because XML does not require them, and because system identifiers are required, XML tools may not provide adequate support for public identifiers. To work with these systems you must use system identifiers.
Public identifiers aren't magic. They're simply a method of indirection. For them to work, there must be a resolution mechanism for public identifiers. Luckily, there are standards that define mechanisms for mapping public identifiers to system identifers using catalog files.
See FIXME: link to XML Catalogs or OASIS Technical Resolution 9401:1997 (Amendment 2 to TR 9401).
An important characteristic of public identifiers is that they are intended to be globally unique. Referring to a document with a public identifier should mean that the identifier will resolve to the same actual document on any system, even though the location of that document on each system may vary. As a rule, you should never reuse public identifiers, and a published revision should have a new public identifier. Not following these rules defeats one purpose of the public identifier.
A public identifier can be any string of upper- and lowercase letters, digits, any of the following symbols: “'”, “(“, “)”, “+”, “,”, “-”, “.”, “/”, “:”, “=”, “?”, and white space, including line breaks.
The rest of this chapter describes how you can break documents into logical chunks, such as books, chapters, sections, and so on. Before we begin, and while the subject of the internal subset is fresh in your mind, let's take a quick look at how to break documents into separate files.
Actually, we've already told you how to do it. If you recall, in the preceding sections we had declarations of the form:
<!ENTITYnameSYSTEM "filename">
If you refer to the entity name in your document after this declaration, the system will insert the contents of the file filename into your document at that point. So, if you've got a book that consists of three chapters and two appendixes, you might create a file called book.xml, which looks like this:
<!DOCTYPE book [ <!ENTITY chap1 SYSTEM "chap1.xml"> <!ENTITY chap2 SYSTEM "chap2.xml"> <!ENTITY chap3 SYSTEM "chap3.xml"> <!ENTITY appa SYSTEM "appa.xml"> <!ENTITY appb SYSTEM "appb.xml"> ]> <book xmlns="http://docbook.org/ns/docbook"> <title>My First Book</title> &chap1; &chap2; &chap3; &appa; &appb; </book>
You can then write the chapters and appendixes conveniently in separate files. Documents that you reference with external parsed entities are forbidden from having a Document Type Declaration.
For example, Chapter 1 might begin like this:
<chapter id="ch1"><title>My First Chapter</title> <para>My first paragraph.</para> …
But it must not begin with its own document type declaration:
<!DOCTYPE chapter>
<chapter xmlns="http://docbook.org/ns/docbook"
id="ch1">
<title>My First Chapter</title>
<para>My first paragraph.</para>
…
It is also possible to construct documents from different files using XInclude. Recasting the previous example using XInclude, yields:
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>My First Book</title>
<xi:include href="chap1.xml"/>
<xi:include href="chap2.xml"/>
<xi:include href="chap3.xml"/>
<xi:include href="appa.xml"/>
<xi:include href="appb.xml"/>
</book>
Notice that we can completely omit the Document Type Declaration in this case, but we must declare the XInclude namespace.
The essential tradeoffs between external parsed entities and XInclude are:
XInclude can be used in a document that does not have a Document Type Declaration. Many web services applications (ones that rely on SOAP, anyway) forbid a Document Type Declaration and therefore cannot use entities of any sort.
The documents referenced by XInclude are complete, free-standing XML documents. They can declare their own local entities using a Document Type Declaration. Documents referenced by external parsed entities cannot have a Document Type Declaration. If they use entities, those entities must be declared in the document that does the including.
External parsed entities can have multiple top-level elements. They are not required to be “single rooted”. XIncluded documents must be wholly well-formed XML.
All XML parsers support external parsed entities. (Parsers which do not are not conformant XML processors.) XInclude is a separate specification and may or may not be supported by tools.
The XML parser expands entities and therefore “sees” the entire document. This means that ID/IDREF links can freely cross entity boundaries. Because XIncluded documents are free-standing, a document containing an IDREF that crosses a document boundary cannot be valid. It can be well-formed, and processors can do the right thing, but the parser cannot determine that the document is valid. What's more, the same ID value can occur in several XIncluded documents without causing a validity error. This may have a consequence on the resulting processing.
DocBook elements can be divided broadly into these categories:
| Sets |
| Books |
| Divisions, which divide books into parts |
| Components, which divide books or divisions into chapters |
| Sections, which subdivide components |
| Meta-information elements |
| Block elements |
| Inline elements |
In the rest of this section, we'll describe briefly the elements that make up these categories. This section is designed to give you an overview. It is not an exhaustive list of every element in DocBook.
For more information about any specific element and the elements that it may contain, consult the reference page for the element in question.
A set contains two or more books. It's the hierarchical top of DocBook. You use the set tag, for example, for a series of books on a single subject that you want to access and maintain as a single unit, such as the manuals for series of computer systems or the
documentation (tutorial, reference, etc.) for a programming language. Sets are allowed to contain themselves, though this is not common.
A book is probably the most common top-level element in a document. The DocBook definition of a book is very loose and general. Given the variety of books authored with DocBook and the number of different conventions for book organization used in countries around the world, attempting to impose a strict ordering of elements can make the
content model extremely complex. But DocBook gives you free rein. It's very reasonable to use a local Chapter 5, Customizing DocBook to impose a more strict ordering for your applications.
A book consists of a mixture of the following elements:
The dedication pages almost always occur at the front of a book.
There are a couple of component-level elements designed for navigation: toc, for Tables of Contents and Lists of Titles (for lists of figures, tables, examples, and so on); and
index, for indexes.
Divisions are the first hierarchical level below book. They contain parts and references. A part, in turn, contains components. A reference contains refentrys. These are discussed more thoroughly in the section called “Making a Reference Page””.
Books can contain components directly and are not required to contain divisions.
These are the chapter-like elements of a book.
Components are the chapter-like elements of a book or part: preface, chapter, appendix, glossary, and
bibliography. An article can also occur at the component level. We describe articles in more detail in the section titled the section called “Making an Article””. Components generally contain block elements and/or sections, and some can
contain navigational components and refentrys.
There are several flavors of sectioning elements in DocBook:
sect1, sect2, sect3, sect4, sect5The sect1…sect5 elements are the most common sectioning elements. They can occur in most component-level elements. These numbered section elements must be properly nested (sect2s can only occur inside sect1s, sect3s can only occur inside sect2s, and so on). There are five levels of numbered sections.
section elementThe section element is an alternative to numbered sections. The section elements are recursive, meaning that you can nest them to any depth desired.
simplesect elementIn addition to numbered sections, there's the simplesect element. It is a terminal section that can occur at any level, but it cannot have any other sectioning element nested within it.
The distinguishing feature of simplesect is that it does not occur in the Table of Contents.
bridgeheadA bridgehead provides a section title without any containing section.
refsect1…refsect3 elementsThese elements, which occur only in refentrys, are analogous to the numbered section elements in components. There are only three levels of numbered section elements in a refentry.
glossdiv, bibliodiv, and indexdivThe glossary, bibliography, and index elements
can be broken into top-level divisions, but not sections. Unlike sections, these elements do not nest.
All of the elements at the section level and above, and many other elements, include a wrapper for meta-information about the content. That element is named info. In earlier versions of DocBook, there were many similarly named elements for this purpose, bookinfo, chapterinfo, etc.
In DocBook V5.0, there is only one.
The meta-information wrapper is designed to contain bibliographic information about the content (author, title, publisher, and so on) as well as other meta-information such as revision histories, keyword sets, and index terms.
An info can contain:
titleThe text of the title of a section of a document or of a formal block-level element.
titleabbrevThe abbreviation of a title.
subtitleThe subtitle of a document.
abstractA summary.
addressA real-world address, generally a postal address.
annotationAn annotation.
artpagenumsThe page numbers of an article as published.
authorThe name of an individual author.
authorgroupWrapper for author information when a document has multiple authors or collabarators.
authorinitialsThe initials or other short identifier for an author.
bibliocoverageThe spatial or temporal coverage of a document.
biblioidAn identifier for a document.
bibliomiscUntyped bibliographic information.
bibliomsetA cooked container for related bibliographic information.
bibliorelationThe relationship of a document to another.
bibliosetA raw container for related bibliographic information.
bibliosourceThe source of a document.
collabIdentifies a collaborator.
confgroupA wrapper for document meta-information about a conference.
contractnumThe contract number of a document.
contractsponsorThe sponsor of a contract.
copyrightCopyright information about a document.
dateThe date of publication or revision of a document.
editionThe name or number of an edition of a document.
editorThe name of the editor of a document.
extendedlinkAn XLink extended link.
issuenumThe number of an issue of a journal.
itermsetA set of index terms in the meta-information of a document.
keywordsetA set of keywords describing the content of a document.
legalnoticeA statement of legal obligations or requirements.
mediaobjectA displayed media object (video, audio, image, etc.).
orgnameThe name of an organization.
othercreditA person or entity, other than an author or editor, credited in a document.
pagenumsThe numbers of the pages in a book, for use in a bibliographic entry.
printhistoryThe printing history of a document.
productnameThe formal name of a product.
productnumberA number assigned to a product.
pubdateThe date of publication of a document.
publisherThe publisher of a document.
publishernameThe name of the publisher of a document.
releaseinfoInformation about a particular release of a document.
revhistoryA history of the revisions to a document.
seriesvolnumsNumbers of the volumes in a series of books.
subjectsetA set of terms describing the subject matter of a document.
volumenumThe volume number of a document in a set (as of books in a set or articles in a journal).
The title, titleabbrev, and subtitle elements can usually appear either immediately before or inside the info wrapper (but not both). This means you don't need the extra wrapper in the common case where all you want to specify is a title.
The block elements occur immediately below the component and sectioning elements. These are the (roughly) paragraph-level elements in DocBook. They can be divided into a number of categories: lists, admonitions, line-specific environments, synopses of several sorts, tables, figures, examples, and a dozen or more miscellaneous elements.
There are eight list elements in DocBook:
calloutlistA list of callouts and their descriptions. The callouts are marks, frequently numbered and typically on a graphic (imageobjectco) or verbatim environment (programlistingco or screenco), that are described in a calloutlist.
bibliolistA list of bibliography entries (biblioentry or bibliomixed elements).
glosslistitemizedlistAn unordered (bulleted) list. There are attributes to control the marks used.
orderedlistA numbered list. There are attributes to control the type of enumeration.
segmentedlistA repeating set of named items. For example, a list of states and their capitals might be represented as a segmentedlist. Segmented lists consist of segtitles, seglistitems, and segs.
simplelistAn unadorned list of items. simplelists can be inline or arranged in columns.
variablelistA list of terms and definitions or descriptions. (This list of list types is a variablelist.)
There are five types of admonitions in DocBook: caution, important, note, tip, and warning.
All of the admonitions have the same structure: an optional title followed by paragraph-level elements. DocBook does not impose any specific semantics on the individual admonitions. For example, DocBook does not mandate that warnings be reserved for cases where bodily harm can result.
These environments preserve whitespace and line breaks in the source text. DocBook does not provide the equivalent of HTML's br tag, so there's no way to interject a line break into normal running text.
addressThe address element is intended for postal addresses. In addition to being line-specific, address contains additional elements suitable for marking up names and addresses: city, country, fax, otheraddr, personname, phone, phone, pob, postcode, state, and street.
literallayout A literallayout does not have any semantic association beyond the preservation of whitespace and line breaks. In particular, while programlisting and screen are frequently presented in a fixed-width font, a change of fonts is not ordinarily implied
by literallayout.
programlisting A programlisting is a verbatim environment, usually presented in Courier or some other fixed-width font, for program sources, code fragments, and similar listings.
screen A screen is a verbatim or literal environment for text screen-captures, other fragments of an ASCII display, and similar things. screen is also a frequent catch-all for any verbatim text.
screenshot screenshot is actually a wrapper for a mediaobject intended for screen shots of a GUI for example.
synopsis A synopsis is a verbatim environment for command and function synopsis.
Examples, figures, and tables
are supported with the block-level elements: example, informalexample, figure, informalfigure, table, and informaltable.
The distinction between formal and informal elements is that formal elements have titles while informal ones do not.
DocBook supports CALS tables (defined with tgroup, colspec, spanspec, thead, tfoot, tbody, row, entry, entrytbl, and caption) and HTML tables (defined with col, colgroup, thead, tfoot, tbody, tr, td, and caption).
There are three paragraph elements: para, simpara (simple paragraphs may not contain other block-level elements), and formalpara (formal paragraphs have titles).
There are two block-equation elements, equation and informalequation (for inline equations, use inlineequation).
Informal equations don't have titles. For reasons of backward-compatibility, equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate equations if they lack titles.
Graphics occur most frequently in figures and screenshots, but they can also occur outside those wrappers.
DocBook considers a mediaobject a block element, even if it occurs in an inline context. For graphics that you want to be represented inline, use inlinemediaobject.
Media objects (and inline media objects) can contain five kinds of content:
audioobjectA wrapper for audio data and its associated meta-information. (Which contains audiodata.)
imageobjectA wrapper for image data and its associated meta-information. (Which contains imagedata.)
imageobjectcoA wrapper for an image object with callouts. (Which contains imagedata and callout-related information).
videoobjectA wrapper for video data and its associated meta-information. (Which contains videodata.)
textobjectA wrapper for a text description of an object and its associated meta-information. (Which contains textdata.)
The audio, image, video, and text data in a media object are, by definition, alternatives.
The qandaset element is suitable for FAQs (Frequently Asked Questions) and other similar collections of questions and answers. Each qandaentry contains a question and its answer(s). The set of questions and answers can be divided into sections with qandadiv.
A task describes a procedure. Each task has an associated tasksummary, taskprerequisites, optional examples, and a section for taskrelated information.
A procedure contains steps, which may contain substeps or stepalternatives.
DocBook provides a number of elements for describing command, function, and class synopses.
cmdsynopsisA syntax summary for a software command. A cmdsynopsis contains arg, command, and group elements. For long synopses, the sbr tag can be used to indicate where a break should occur. Complex synopses can be composed from synopfragments.
funcsynopsisThe syntax summary for a function definition. A function synopsis consists of one or more funcprototypes and may include additional, literal information in a funcsynopsisinfo. Each prototype consists of modifiers, a funcdef, and a collection of paramdef, varargs, and/or void elements.
classsynopsisThe syntax summary for a class definition. A class synopsis consists of one or more ooclass, ooexception, or oointerface elements followed by zero or more constructorsynopsis,
destructorsynopsis, fieldsynopsis, and methodsynopsis elements Like funcsynopsis, it may include additional, literal information, in this case, in a classsynopsisinfo.
If the HTML Forms module is included, the following HTML 4.01 forms elements are available:
html:buttonA button in an HTML form.
html:fieldsetA fieldset element in an HTML form.
html:formAn HTML form.
html:inputAn input element in an HTML form.
html:labelA label in an HTML form.
html:legendA legend in an HTML form fieldset.
html:optionAn option element in an HTML form.
html:selectA select element in an HTML form.
html:textareaA textarea element in an HTML form.
The following block elements are also available:
blockquote A block quotation. Block quotations may have attributions.
epigraph A short introduction, typically a quotation, at the beginning of a document. epigraphs may have attributions.
msgsetsidebarA sidebar.
Users of DocBook are provided with a surfeit of inline elements. Inline elements are used to mark up running text. In published documents, inline elements often cause a font change or other small change, but they do not cause line or paragraph breaks.
In practice, writers generally settle on the tagging of inline elements that suits their time and subject matter. This may be a large number of elements or only a handful. What is important is that you choose to mark up not every possible item, but only those for which distinctive tagging will be useful in the production of the finished document for the readers who will search through it.
The following comprehensive list may be a useful tool for the process of narrowing down the elements that you will choose to mark up; it is not intended to overwhelm you by its sheer length. For convenience, we've divided the inlines into several subcategories.
The classification used here is not meant to be authoritative, only helpful in providing a feel for the nature of the inlines. Several elements appear in more than one category, and arguments could be made to support the placement of additional elements in other categories or entirely new categories.
These inlines identify things that commonly occur in general writing:
abbrevacronymAn often pronounceable word made from the initial (or selected) letters of a name or phrase.
emphasisfootnoteA footnote. The location of the footnote element identifies the location of the first reference to the footnote. Additional references to the same footnote can be inserted with footnoteref.
phrasequotetrademark The cross reference inlines identify both explicit cross references, such as link, and implicit cross references like glossterm. You can make the most of the implicit
references explicit with a linkend attribute.
These inlines are used to mark up text for special presentation:
foreignphraseA word or phrase in a language other than the primary language of the document.
wordaswordA word meant specifically as a word and not representing anything else.
computeroutputliteralmarkupA string of formatting markup in text that is to be represented literally.
promptA character or string indicating the start of an input field in a computer display.
replaceabletaguserinputDocBook does not define a complete set of elements for representing equations. No one has ever pressed the DocBook maintainers to add this functionality, and the prevailing opinion is that incorporating MathML is probably the best long-term solution. For simple mathematics that doesn't require extensive markup, the mathphrase element may be sufficient.
inlineequationmathphraseA mathematical phrase, an expression that can be represented with ordinary text and a small amount of markup.
subscriptsuperscriptA superscript (as in x^2, the mathematical notation for x multiplied by itself).
These elements describe aspects of a user interface:
accelguibuttonguiiconguilabelThe text of a label in a GUI.
guimenuguimenuitemguisubmenukeycapkeycodeThe internal, frequently numeric, identifier for a key on a keyboard.
keycombokeysymmenuchoicemousebuttonshortcutA key combination for an action that is also accessible through a menu.
Many of the technical inlines in DocBook are related to programming.
classnameThe name of a class, in the object-oriented programming sense.
constanterrorcodeerrornameerrortypefunctionThe name of a function or subroutine, as in a programming language.
literalmsgtextparameterpropertyA unit of data associated with some part of a computer system.
replaceablereturnvaluesymboltokentypevarnameThese inlines identify parts of an operating system, or an operating environment:
applicationcommandThe name of an executable program or other software command.
envarfilenamemsgtextoptionparameterpromptA character or string indicating the start of an input field in a computer display.
systemitemA typical book, in English at least, consists of some meta-information in an info (title, author,
copyright, and so on), one or more prefaces, several chapters, and perhaps a few appendixes. A book may also contain bibliographys, glossarys, indexes and a colophon.
Example 2.1, “A Typical Book” shows the structure of a typical book. Additional content is required where the ellipses occur.
Example 2.1. A Typical Book
<book> <info> <title>My First Book</title> <author><firstname>Jane</firstname><surname>Doe</surname></author> <copyright><year>1998</year><holder>Jane Doe</holder></copyright> </info> <preface><title>Foreword</title> ... </preface> <chapter> ... </chapter> <chapter> ... </chapter> <chapter> ... </chapter> <appendix> ... </appendix> <appendix> ... </appendix> <index> ... </index> </book>
chapters, prefaces, and appendixes all have a similar structure. They consist of a title,
possibly some additional meta-information, and any number of block-level elements followed by any number of top-level sections. Each section may in turn contain any number of block-level elements followed by any number from the next section level, as shown in Example 2.2, “A Typical Chapter”.
Example 2.2. A Typical Chapter
<chapter><title>My Chapter</title> <para> ... </para> <sect1><title>First Section</title> <para> ... </para> <example> ... </example> </sect1> </chapter>
For documents smaller than a book, such as: journal articles, white papers, or technical notes, article is frequently the most logical starting point. The body of an article is essentially the same as the body of a chapter or any other component-level element, as shown in Example 2.3, “A Typical Article”
articles may include appendixes, bibliographys, indexes and glossarys.
Example 2.3. A Typical Article
<article>
<artheader>
<title>My Article</title>
<author><honorific>Dr</honorific><firstname>Emilio</firstname>
<surname>Lizardo</surname></author>
</artheader>
<para> ... </para>
<sect1><title>On the Possibility of Going Home</title>
<para> ... </para>
</sect1>
<bibliography> ... </bibliography>
</article>
The reference page or manual page in DocBook was inspired by, and in fact designed to reproduce, the common UNIX “manpage” concept. (We use the word "page" loosely here to mean a document of variable length containing reference material on a specific topic.) DocBook is rich in markup tailored for such documents, which often vary greatly in content, however well-structured they may be. To reflect both the structure and the variability of such texts, DocBook specifies that reference pages have a strict sequence of parts, even though several of them are actually optional.
Of the following sequence of elements that may appear in a refentry, only two are obligatory: refnamediv and refsect1.
infoThe info element contains meta-information about the reference page (which should not be confused with refmeta, which it precedes). It marks up information about the author of the document, or the product to which it pertains, or the document's revision history, or other such
information.
refmeta refmeta contains a title for the reference page (which may be inferred if the refmeta element is not present) and an indication of the volume number in which this reference page occurs. The manvolnum is a very UNIX-centric concept. In traditional UNIX documentation, the subject of a reference page is typically identified by name and volume number; this allows you to distinguish between the uname command, “uname(1)” in volume 1 of the documentation and the uname function, “uname(3)” in volume 3.
Additional information of this sort such as conformance or vendor information specific to the particular environment you are working in, may be stored in refmiscinfo.
refnamediv The first obligatory element is refnamediv, which is a wrapper for
information about whatever you're documenting, rather than the document itself. It can begin with a refdescriptor if several items are being documented as a group and the group has a name. The refnamediv must contain at least one refname, that is, the name of whatever you're documenting, and a single short
statement that sums up the use or function of the item(s) at a glance: their refpurpose. Also available is the refclass, intended to detail the operating system configurations that the software element in question supports.
If no refentrytitle is given in the refmeta, the title of the reference page is the refdescriptor, if present, or the first refname.
refsynopsisdiv A refsynopsisdiv is intended to provide a quick synopsis of the topic covered by the reference page. For commands, this is generally a syntax summary of the command, and
for functions, the function prototype, but other options are possible. A title is allowed, but not required, presumably because the application that processes reference pages will generate the appropriate title if it is not given. In traditional UNIX documentation, its title is always “Synopsis”.
refsect1…refsect3 Within refentrys, there are only three levels of sectioning elements: refsect1, refsect2, and refsect3.
Example 2.4, “A Sample Reference Page” shows the beginning of a refentry that illustrates one possible reference page:
Example 2.4. A Sample Reference Page
<refentry xml:id="printf" > <refmeta> <refentrytitle>printf</refentrytitle> <manvolnum>3S</manvolnum> </refmeta> <refnamediv> <refname>printf</refname> <refname>fprintf</refname> <refname>sprintf</refname> <refpurpose>print formatted output</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> <funcsynopsisinfo> #include <stdio.h> </funcsynopsisinfo> <funcprototype> <funcdef>int <function>printf</function></funcdef> <paramdef>const char *<parameter>format</parameter></paramdef> <varargs/> </funcprototype> <funcprototype> <funcdef>int <function>fprintf</function></funcdef> <paramdef>FILE *<parameter>strm</parameter></paramdef> <paramdef>const char *<parameter>format</parameter></paramdef> <varargs/> </funcprototype> <funcprototype> <funcdef>int <function>sprintf</function></funcdef> <paramdef>char *<parameter>s</parameter></paramdef> <paramdef>const char *<parameter>format</parameter></paramdef> <varargs/> </funcprototype> </funcsynopsis> </refsynopsisdiv> <refsect1><title>Description</title> <para> <indexterm><primary>functions</primary> <secondary>printf</secondary></indexterm> <indexterm><primary>printing function</primary></indexterm> <function>printf</function> places output on the standard output stream stdout. … </para> </refsect1> </refentry>
DocBook contains markup for the usual variety of front- and backmatter necessary for books and articles: indexes, glossaries, bibliographies, and tables of contents. In many cases, these components are generated automatically, at least in part, from your document by an external processor, but you can create them by hand, and in either case, store them in DocBook.
Some forms of backmatter, like indexes and glossaries, usually require additional markup in the document to make generation by an application possible. Bibliographies are usually composed by hand like the rest of your text, unless you are automatically selecting bibliographic entries out of some larger database. Our principal concern here is to acquaint you with the kind of markup you need to include in your documents if you want to construct these components.
Frontmatter, like the table of contents, is almost always generated automatically from the text of a document by the processing application. If you need information about how to mark up a table of contents in DocBook, please consult the reference page for toc.
In some highly-structured documents such as reference manuals, you can automate the whole process of generating an index successfully without altering or adding to the original source. You can design a processing application to select the information and compile it into an adequate index. But this is rare.
In most cases—and even in the case of some reference manuals—a useful index still requires human intervention to mark occurrences of words or concepts that will appear in the text of the index.
Docbook distinguishes two kinds of index markers: those that are singular and result in a single page entry in the index itself, and those that are multiple and refer to a range of pages.
You put a singular index marker where the subject it refers to actually occurs in your text:
<para> The tiger<indexterm> <primary>Big Cats</primary> <secondary>Tigers</secondary></indexterm> is a very large cat indeed. </para>This index term has two levels,
primary and secondary. They correspond to an increasing amount of indented text in the resultant index. DocBook allows for three levels of index terms, with the third labeled tertiary.
There are two ways that you can index a range of text. The first is to put index marks at both the beginning and end of the discussion. The mark at the beginning asserts that it is the start of a range, and the mark at the end refers back to the beginning. In this way, the processing application can determine what range of text is indexed. Here's the previous tiger example recast as starting and ending index terms:
<para> The tiger<indexterm id="tiger-desc" class="startofrange"> <primary>Big Cats</primary> <secondary>Tigers</secondary></indexterm> is a very large cat indeed… </para> ⋮ <para> So much for tigers<indexterm startref="tiger-desc" class="endofrange"/>. Let's talk about leopards. </para>
Note that the mark at the start of the range identifies itself as the start of a range with the class attribute, and provides an id. The mark at the end of the range points back to the start.
Another way to mark up a range of text is to specify that the entire content of an element, such as a chapter or section, is the complete range. In this case, all you need is for the index term to point to the id of the element that contains the content in question. The zone attribute of indexterm provides this functionality.
One of the interesting features of this method is that the actual index marks do not have to occur anywhere near the text being indexed. It is possible to collect all of them together, for example, in one file, but it is not invalid to have the index marker occur near the element it indexes.
Suppose the discussion of tigers in your document comprises a whole text object (like a sect1 or a chapter) with an id value of tiger-desc. You can put the following tag anywhere in your document to index that range of text:
<indexterm zone="tiger-desc"> <primary>Big Cats</primary> <secondary>Tigers</secondary></indexterm>
DocBook also contains markup for index hits that point to other index hits (of the same type such as "See Cats, big" or "See also Lions"). See the reference pages for see and seealso.
After you have added the appropriate markup to your document, an external application can use this information to build an index. The resulting index must have information about the page numbers on which the concepts appear. It's usually the document formatter that builds the index. In this case, it may never be instantiated in DocBook.
However, there are applications that can produce an index marked up in DocBook. The following example includes some one- and two-level indexentry elements (which correspond to the primary and secondary levels in the indexterms themselves) that begin with the letter D:
<index><title>Index</title>
<indexdiv><title>D</title>
<indexentry>
<primaryie>database (bibliographic), 253, 255</primaryie>
<secondaryie>structure, 255</secondaryie>
<secondaryie>tools, 259</secondaryie>
</indexentry>
<indexentry>
<primaryie>dates (language specific), 179</primaryie>
</indexentry>
<indexentry>
<primaryie>DC fonts, <emphasis>172</emphasis>, 177</primaryie>
<secondaryie>Math fonts, 177</secondaryie>
</indexentry>
</indexdiv>
</index>
The structure of indexentry is parallel to the structure of indexterm. Where indexterm has primary, secondary, tertiary, see, and seealso indexentry, has primaryie, secondaryie, and tertiaryie,
seeie, and seealsoie.
glossarys, like bibliographys, are often constructed by hand. However, some applications are capable of building a skeletal index from glossary term markup in the document. If all of your terms are defined in some glossary database, it may even be possible to construct the complete glossary automatically.
To enable automatic glossary generation, or simply automatic linking from glossary terms in the text to glossary entries, you must add markup to your documents. In the text, you markup a term for compilation later with the inline glossterm tag. This tag can have a linkend attribute whose value is the ID of the actual entry in the glossary.[1]
For instance, if you have this markup in your document:
<glossterm linkend="xml">Extensible Markup Language</glossterm> is a new standard…
your glossary might look like this:
<glossary><title>Example Glossary</title> ⋮ <glossdiv><title>E</title> <glossentry id="xml"><glossterm>Extensible Markup Language</glossterm> <acronym>XML</acronym> <glossdef> <para>Some reasonable definition here.</para> <glossseealso otherterm="sgml"> </glossdef> </glossentry> </glossdiv>
Note that the glossterm tag reappears in the glossary to mark up the term and distinguish it from its definition within the glossentry. The id that the glossentry referenced in the text is the ID of the glossentry in the glossary itself. You can use the link between source and glossary to create a link in the online form of your document, as we have done with the online form of the glossary in this book.
There are two ways to set up a bibliography in DocBook: you can have the data raw or cooked. Here's an example of a raw bibliographical item, wrapped in the biblioentry element:
<biblioentry xreflabel="Kites75">
<authorgroup>
<author><firstname>Andrea</firstname><surname>Bahadur</surname></author>
<author><firstname>Mark</firstname><surname>Shwarek</surname></author>
</authorgroup>
<copyright><year>1974</year><year>1975</year>
<holder>Product Development International Holding N. V.</holder>
</copyright>
<isbn>0-88459-021-6</isbn>
<publisher>
<publishername>Plenary Publications International, Inc.</publishername>
</publisher>
<title>Kites</title>
<subtitle>Ancient Craft to Modern Sport</subtitle>
<pagenums>988-999</pagenums>
<seriesinfo>
<title>The Family Creative Workshop</title>
<seriesvolnums>1-22</seriesvolnums>
<editor>
<firstname>Allen</firstname>
<othername role=middle>Davenport</othername>
<surname>Bragdon</surname>
<contrib>Editor in Chief</contrib>
</editor>
</seriesinfo>
</biblioentry>
The “raw” data in a biblioentry is comprehensive to a fault—there are enough fields to suit a host of different bibliographical styles, and that is the point. An abundance of data requires processing applications to select, punctuate, order, and format the bibliographical data, and it is unlikely that all the information provided will actually be output.
All the “cooked” data in a bibliomixed entry in a bibliography, on the other hand, is intended to be presented to the reader in the form and sequence in which it is provided. It even includes punctuation between the fields of data:
<bibliomixed>
<bibliomset relation=article>
<surname>Walsh</surname>, <firstname>Norman</firstname>.
<title role=article>Introduction to Cascading Style Sheets</title>.
</bibliomset>
<bibliomset relation=journal>
<title>The World Wide Web Journal</title>
<volumenum>2</volumenum><issuenum>1</issuenum>.
<publishername>O'Reilly & Associates, Inc.</publishername> and
<corpname>The World Wide Web Consortium</corpname>.
<pubdate>Winter, 1996</pubdate></bibliomset>.
</bibliomixed>
Clearly, these two ways of marking up bibliographical entries are suited to different circumstances. You should use one or the other for your bibliography, not both. Strictly speaking, mingling the raw and the cooked may be “kosher” as far as the DTD is concerned, but it will almost certainly cause problems for most processing applications.
[1] Some sophisticated formatters might even be able to establish the link simply by examining the content of the terms and the glossary. In that case, the author is not required to make explicit links.
| |
|
|
| Getting Started with XML | |
Parsing DocBook Documents |