Preface to the DocBook V5.2 Edition

This is version 5.2.18 of DocBook 5: The Definitive Guide. It describes the DocBook V5.2 schema, currently version 5.2CS01.

You can get the latest version of the DocBook reference books and the DocBook sources for them from https://github.com/docbook/defguide/.

The current O'Reilly edition covers DocBook V5.0, the OASIS Standard.

Summary of Changes in DocBook V5.2

Many new synopsis elements for programming languages.
New danger admonition element.
New formalgroup element to support subfigures, etc.
New transclusion fixup attributes.
New class attribute on sectioning elements support legal sections.
New meta element added to info.
Added XInclude-enabled schema versions of Assembly and BITS schemas.

Changes from DocBook 5.2 CR1 to DocBook 5.2 CR2

Updated content models so that modifier can appear after classname in ooclass, interfacename in oointerface, exceptionname in ooexception, varname in fieldsynopsis, methodname in constructorsynopsis, methodname in destructorsynopsis, and enumname in enumsynopsis. (It was already allowed parameter in methodparam, templatename in template, package in packagesynopsis, macroname in macrosynopsis, macrodef in macroprototype, unionname in unionsynopsis, and typedefname in typedefsynopsis.

Changes from DocBook 5.1 to DocBook 5.2 CR1

The following lists describe all the changes in 5.2CR1.

New Elements

Added new element buildtarget.
Added new element danger.
Added new element enumidentifier.
Added new element enumitem.
Added new element enumitemdescription.
Added new element enunname.
Added new element enumsynopsis.
Added new element enumvalue.
Added new element formalgroup to contain multiple figure, table, example, or equation elements. (But not mixtures of them).
Added new element macrodef.
Added new element macroname.
Added new element macroprototype.
Added new element macrosynopsis.
Added new element meta.
Added new element packagesynopsis.
Added new element specializedtemplate.
Added new element synopsisinfo with a verbatim content model.
Added new element template.
Added new element templatename.
Added new element typedefname.
Added new element typedefsynopsis.
Added new element union.
Added new element unionname.
Added new element unionsynopsis.

New Attributes

Added db.trans.idfixup.attribute = "none|suffix|auto".
Added db.trans.suffix.attribute as “text” with a Schematron rule to force idfixup attribute if suffix used.
Added db.trans.linkscope.attribute = "user|local|near|global".
Added trans:idfixup, trans:suffix, and trans:linkscope to common attributes.
Added pubwork attribute with the possible values: article, bbs, book, cdrom, chapter, dvd, emailmessage, gopher, journal, manuscript, newsposting, other, part, refentry, section, series, set, webpage, and wiki to biblioentry and bibliomixed.
Added otherpubwork attribute for when pubwork has the valeu “other” specified, but no Schematron to enforce it.
Added optional type attribute (text) to procedure element.
Added optional type attribute to example, informalexample, figure, and informalfigure elements.
Added fgstyle attribute, used in formalgroup only.
Added enumerated class attribute to the section elements (section and sect1 through sect5) with the values legal or other.
Added otherclass attribute to section elements to support other values.
Added other to the existing article class attribute enumeration.
Added otherclass attribute to article.
Added a type attribute to table and informaltable elements (CALS and HTML table syntax).
Added a type attribute to equation and informalequation.
Added class attribute with enumerated values union and intersection to the type element.
Added Schematron rule to exclude danger element as descendant of admonitions.
Added packageref attribute to cmdsynopsis, funcsynopsis, classsynopsis, fieldsynopsis, constructorsynopsis, destructorsynopsis, methodsynopsis, macrosynopsis, unionsynopsis, enumsynopsis, typedefsynopsis, and packagesynopsis.

Content Model Changes

Added db.programmingsynopsis elements to db.synopsis.blocks.
Changed db._any to remove HTML namespace reference.
Added db.revnumber to db.publishing.inlines.
Added db.wrapper.blocks to db.nopara.blocks.
Added meta element to info set. Can be empty or have block and inline content.
Changed abstract content from db.para.blocks+ to db.all.blocks+ to expand its content model.
Added Schematron rule to footnote to exclude danger element (similar to other admonitions).
Added Schematron rule to caption to exclude danger element (similar to other admonitions).
Added Schematron rule to exclude danger element as descendant of admonitions.
Added optional info child to listitem element.
Added multimediaparam children to imagedata element (already allowed on audiodata and videodata).
Allowed refentry in sect1 through sect5 (already allowed in section).
Added elements buildtarget, templatename, macroname, unionname, enumname, enumvalue, enumidentifier, and typedefname to the list of programming inlines.
Added elements enumsynopsis, typedefsynopsis, packagesynopsis, macrosynopsis, unionsynopsis, enumsynopsis, and typedefsynopsis to the list in db.synopsis.blocks.
Added elements packagesynopsis, macrosynopsis, typedefsynopsis, and enumsynopsis to the db.programmingsynopsis set.
Added elements templatename and void to the funcdef content model.
Added elements templatename and modifier to the paramdef content model.
Added elements info, templatename, template, and ooexception to the classsynopsis content model.
Added elements info and synopsisinfo to the constructorsynopsis content model.
Added elements info and synopsisinfo to the destructorsynopsis content model.
Added elements info, synopsisinfo, and templatename to the fieldsynopsis content model.
Added elements info, synopsisinfo, and templatename to the methodsynopsis content model.
Added element templatename to the methodparam content model.
Added programming inlines to the type element.
Allow optional element to nest in an optional element.

Other Changes

Added trans namespace declarations for transclusion.
Added 10 s: schematron namespace declarations.
Added db.wrapper.blocks to “start” set.
Defined db.wrapper.blocks as db.formalgroup.
Deleted db.programmingsynopsis named pattern (only used in start, now handled by db.synopsis.blocks).
Removed unnecessary \x{a} whitespace from Schematron rules.
Added a Schematron rule to callout element so arearefs must point to areaset, area, or co.
Added a Schematron rule to EBNF constraint element so its linkend must point to a constraintdef.
Added a Schematron rule to EBNF productionrecap element so its linkend must point to a production.

Backwards incompatible changes planned for DocBook V6.0

The following backwards incompatible changes are planned for DocBook V6.0:

The linking elements will be removed from the content model of biblioid.
The common linking attributes will be removed from indexterm.
The xml:id attribute will be made required on startofrange indexterms.
A Schematron constraint will be added to assert that for every startofrange indexterm there is exactly one endofrange indexterm that points to it.
The language attribute will be removed from address; use xml:lang instead.
The arc and locator elements will be dropped; instead link will be allowed in extendedlink.
The indexterm elements will be removed from primary, secondary, and tertiary. Nested index terms are not supported.