Part II. Reference

This reference describes every element in DocBook V5.0.

Organization of Reference Pages

The description of each element in this reference is divided into the following sections:

Synopsis

Provides a quick synopsis of the element. The content of the synopsis varies according to the nature of the element described, but may include any or all of the following sections:

Content Model

Describes the content model of the element, the mixture of things that it can contain. See Understanding Content Models.

Attributes

Provides a synopsis of the attributes on the element. For brevity, common attributes are described only once, in this introduction. Likewise, common linking attributes are described once.

Additional Constraints

Provides a synopsis of any additional constraints on the element. These constraints are expressed using Schematron in the RELAX NG grammar.

Description

Describes the semantics of the element.

Processing expectations

Summarizes specific formatting expectations of the element. Many processing expectations are influenced by attribute values. Be sure to consult the description of element attributes as well.

Future changes

Identifies changes that are scheduled for future versions of the schema. These changes are highlighted because they involve some backward incompatibility that may make currently valid DocBook documents no longer valid under the new version.

Attributes

Describes the semantics of each attribute.

See Also

Lists similar or related elements.

Examples

Provides examples of proper usage for the element. Generally, the smallest example required to reasonably demonstrate the element is used. In many cases, a formatted version of the example is also shown.

All of the examples in the book are valid according to the RELAX NG grammar.

Formatted examples are indicated using a vertical bar.

Understanding Content Models

Each element synopsis begins with a description of its content model. Content models are the way that grammars describe the name, number, and order of other elements that may be used inside an element.

Content model notation

Presenting the content models is an editorial challenge. Presenting the RELAX NG patterns would be easy and absolutely correct, but would only be valuable to readers who understand both RELAX NG and the patterns in the schema. Presenting the RELAX NG patterns “fully expanded” to just element and attribute names would remove the requirement to understand the patterns, but the result is so verbose that it completely obscures the actual meaning.

On the Web and in other interactive media, it’s possible to format the content models in a “natural language” list format with names that can be expanded to show more detail. That format is useful even without the ability to expand patterns interactively. Unfortunately, that presentation occupies significant vertical space and, were it used, this book would run to more than a thousand pages. That’s not really practical.

Instead, we compromise with a compact syntax reminiscent of DTD syntax. It’s not any sort of standard, but it has the dual advantages of being reasonably concise and reasonably easy to understand:

name

A name is the name of a DocBook element.

( )

Parentheses delimit groups.

*, +, ?

Symbols appear after names and groups to indicate how many occurrences are allowed. If a “*” is present, zero or more occurrences are allowed; if a “+” is present, one or more occurrences are allowed; if a “?” is present, the symbol may occur zero or one time; if no symbol is present, exactly one occurrence is allowed.

|

A vertical bar indicates a choice. Either the item that precedes or the item that follows the bar is allowed.

&

An ampersand indicates an “interleave.” Both the item that precedes and the item that follows the & are allowed, but they may occur in any order.

,

A comma separates items in a sequence. Both the item that precedes and the item that follows the “,” are allowed, and they must occur in that order.

Here are a few examples:

A

Exactly one “A” element is allowed.

A | B | C

Exactly one “A”, or exactly one “B”, or exactly one “C” is allowed.

A,B,C

Exactly one “A”, followed by exactly one “B”, followed by exactly one “C” is allowed.

A & B & C

Exactly one “A” and exactly one “B” and exactly one “C” is allowed in any order. This pattern allows <A/><B/><C/>, <B/><C/><A/>, <C/><A/><B/>, etc. but does not allow <A/><A/><C/> or <A/><B/>.

A+,B*,C?

At least one, but possibly more than one “A”, followed by zero or more “B”s, followed by an optional (zero or one) “C” is allowed.

A,(B|C)+,D

Exactly one “A”, followed by one or more “B” or “C” elements, followed by exactly one “D” is allowed. Because the group can be repeated, this pattern matches <A/><B/><D/>, <A/><C/><D/>, <A/><B/><C/><D/>, <A/><B/><C/><C/><C/><D/>, etc.

Some element names are defined by more than one pattern. When this is the case, the name of the pattern is explicitly shown in a superscript following the name.

In order to avoid long, repetitive lists of element names, similar items are grouped together and only the name of the group is given. For example, a para may contain the “Bibliography inlines,” the “Error inlines,” etc. The author has the choice of using any of the elements belonging to the group. Here is a summary of the elements included in each group:

Bibliography inlines

A choice of one of the following: citation, citerefentry, citetitle, citebiblioid, author, person, personname, org, orgname, editor, or jobtitle

Computer-output inlines

A choice of one of the following: inlinemediaobject, remark, superscript, subscript, xref, link, olink, anchor, biblioref, alt, annotation, indexterm, prompt, envar, filename, command, computeroutput, userinput, replaceable, package, parameter, termdef, nonterminal, systemitem, option, optional, property, co, tag, markup, token, symbol, literal, code, constant, email, or uri

Error inlines

A choice of one of the following: errorcode, errortext, errorname, or errortype

Graphic inlines

inlinemediaobject

GUI inlines

A choice of one of the following: guiicon, guibutton, guimenuitem, guimenu, guisubmenu, guilabel, menuchoice, or mousebutton

Indexing inlines

indexterm

Keyboard inlines

A choice of one of the following: keycombo, keycap, keycode, keysym, shortcut, or accel

Linking inlines

A choice of one of the following: xref, link, olink, anchor, or biblioref

Markup inlines

A choice of one of the following: tag, markup, token, symbol, literal, code, constant, email, or uri

Math inlines

inlineequation

Object-oriented programming inlines

A choice of one of the following: ooclass, ooexception, or oointerface

Operating system inlines

A choice of one of the following: prompt, envar, filename, command, computeroutput, or userinput

Product inlines

A choice of one of the following: trademark, productnumber, productname, database, application, or hardware

Programming inlines

A choice of one of the following: function, parameter, varname, returnvalue, type, classname, exceptionname, interfacename, methodname, modifier, initializer, ooclass, ooexception, or oointerface

Publishing inlines

A choice of one of the following: abbrev, acronym, date, emphasis, footnote, footnoteref, foreignphrase, phrase, quote, subscript, superscript, wordasword, firstterm, glossterm, or coref

Technical inlines

A choice of one of the following: replaceable, package, parameter, termdef, nonterminal, systemitem, option, optional, or property

Ubiquitous inlines

A choice of one of the following: inlinemediaobject, remark, superscript, subscript, xref, link, olink, anchor, biblioref, alt, annotation, or indexterm

User-input inlines

A choice of one of the following: inlinemediaobject, remark, superscript, subscript, xref, link, olink, anchor, biblioref, alt, annotation, indexterm, prompt, envar, filename, command, computeroutput, userinput, replaceable, package, parameter, termdef, nonterminal, systemitem, option, optional, property, co, tag, markup, token, symbol, literal, code, constant, email, uri, guiicon, guibutton, guimenuitem, guimenu, guisubmenu, guilabel, menuchoice, mousebutton, keycombo, keycap, keycode, keysym, shortcut, or accel

Admonition elements

A choice of one of the following: caution, important, note, tip, or warning

Formal elements

A choice of one of the following: example, figure, table, or equation

Graphic elements

A choice of one of the following: mediaobject or screenshot

“Info” elements

A choice of one of the following: abstract, address, artpagenums, author, authorgroup, authorinitials, bibliocoverage, biblioid, bibliosource, collab, confgroup, contractsponsor, contractnum, copyright, cover, date, edition, editor, issuenum, keywordset, legalnotice, mediaobject, org, orgname, othercredit, pagenums, printhistory, pubdate, publisher, publishername, releaseinfo, revhistory, seriesvolnums, subjectset, volumenum, annotation, extendedlink, bibliomisc, bibliomset, bibliorelation, biblioset, itermset, productname, or productnumber

Informal elements

A choice of one of the following: informalexample, informalfigure, informaltable, or informalequation

List elements

A choice of one of the following: itemizedlist, orderedlist, procedure, simplelist, variablelist, segmentedlist, glosslist, bibliolist, calloutlist, or qandaset

Paragraph elements

A choice of one of the following: anchor, para, formalpara, or simpara

Publishing elements

A choice of one of the following: sidebar, blockquote, address, or epigraph

Synopsis elements

A choice of one of the following: funcsynopsis, classsynopsis, methodsynopsis, constructorsynopsis, destructorsynopsis, fieldsynopsis, or cmdsynopsis

Technical elements

A choice of one of the following: procedure, task, productionset, constraintdef, or msgset

Verbatim elements

A choice of one of the following: screen, literallayout, programlistingco, screenco, programlisting, or synopsis

Content models and validity

A validator uses the content models to determine if a given document is valid. In order for a document to be valid, the content of every element in the document must “match” the content model for that element.

In practical terms, “match” means that it must be possible to expand the content model until it exactly matches the sequence of elements in the document.

For example, consider the content model of the epigraph:

epigraph ::= (info?db.titleforbidden.info, attribution?,(literallayout | Paragraph elements)+)

Does the following example “match” that content model?

<epigraph>
<para>Some text</para>
</epigraph>

Yes, it is valid because the following expansion of the content model exactly matches the actual content: choose zero occurrences of info, choose zero occurrences of attribution, choose the alternative para from the “Paragraph elements” choice, and choose to let the “one or more” match once.

By the same token, this example is not valid because there is no expansion of the content model that can match it:

<epigraph>
<para>Some text</para>
<attribution>John Doe</attribution>
</epigraph>
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.216.197.92