DocBook 5.2 CR5 Release Notes

Table of Contents

1 Background

DocBook is general purpose XML schema particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

The DocBook Technical Committee at OASIS Open maintains the DocBook schema. Starting with V5.0, DocBook is normatively available as a RELAX NG Schema (with some additional Schematron assertions). DocBook builds on existing XML technologies: it uses XLink for linking, W3C XML Datatypes for atomic data types, and supports the use of XInclude for transclusion.

ⓘ
Note

DocBook has been under active maintenance for more than 20 years, it began life as an SGML document type definition.

The current DocBook released standard is version 5.1. The version described here is DocBook version 5.2 Candidate Release 2. Before submission to the OASIS standards process, the DocBook Technical Committee is making it available to the DocBook user community for review and testing.

The DocBook Technical Committee welcomes bug reports from the user community. Please send comments and requests for enhancement to the DocBook comments list, docbook-comment@lists.oasis-open.org mailing list. Outstanding requests can be seen in the archives as well as in the issues tracker on Github.

2 Significant differences in 5.2

  1. Many new synopsis elements for programming languages.

  2. New danger admonition element.

  3. New formalgroup element to support subfigures, etc.

  4. New transclusion fixup attributes.

  5. New class attribute on sectioning elements support legal sections.

  6. New meta element added to info.

  7. Added XInclude-enabled schema versions of Assembly and International Tag Set (ITS) schemas.

  8. Added missing fragid and set-xml-id to the XInclude-enabled schema.

  9. Allow info as top-level element.

  10. Allow foreign namespace-qualified attributes on DocBook elements.

3 Changes from DocBook 5.2 CR4 to DocBook 5.2 CR5

Fixed the bug where the cols attribute on CALS entrytbl was optional. It is required by the CALS specification.

4 Changes from DocBook 5.2 CR3 to DocBook 5.2 CR4

  • Fix OASIS identifiers in the XML catalog.

  • Allow info as a top-level element.

  • Fixed inconsistencies in XInclude declarations.

  • Small documentation improvements.

5 Changes from DocBook 5.2 CR2 to DocBook 5.2 CR3

Allow attributes in foreign namespaces (and not in the DocBook, XML, XLink, or transclusion namespaces) to appear on any DocBook element.

6 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.

7 Changes from DocBook 5.1 to DocBook 5.2 CR1

The following lists describe all the changes in 5.2. For details about elements, attributes, and content models, please refer to the online documentation for the DocBook 5.2 schema in DocBook 5.2: The Definitive Guide which has been updated to include all these changes.

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.