$Id: docbook.xml 8779 2010-07-27 18:17:02Z nwalsh $ docbook 5.1b2 ed 01 &root;specs OASIS OASIS DocBook Technical Committee Norman Walsh norman.walsh@marklogic.com MarkLogic Corporation Norman Walsh norman.walsh@marklogic.com MarkLogic Corporation 2010-07-27 http://docbook.org/ns/docbook 200120022003 200420052006 200720082009 2010 The Organization for the Advancement of Structured Information Standards [OASIS]. All Rights Reserved. DocBook is a general purpose schema particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications). The Technical Committee provides the DocBook 5.1 schema in other schema languages, including W3C XML Schema and an XML DTD, but the RELAX NG Schema is now the normative schema. This is a &standard;. It does not necessarily represent the consensus of the committee. Please send comments on this specification to the docbook@lists.oasis-open.org list. To subscribe, please use the OASIS Subscription Manager. Copyright © OASIS® 2010. All Rights Reserved. All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so. OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims. The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see for above guidance.

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 maintains the DocBook schema. Starting with V5.0, DocBook is normatively available as a Schema (with some additional assertions). W3C XML Schema and Document Type Definition (DTD) versions are also available. The Version 5.1 release adds a major new feature to DocBook: the ability to compose document assemblies specifically designed to be suitable for use in topic-based authoring methodologies. It also adds a topic element, in support of topic-based authoring, and fixes a small number of bugs. The DocBook Technical Committee welcomes bug reports and requests for enhancement (RFEs) from the user community. The current list of outstanding requests is available through the SourceForge tracker interface. This is also the preferred mechanism for submitting new requests.

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this &standard; are to be interpreted as described in . Note that for reasons of style, these words are not capitalized in this document.

This release is DocBook V5.1b2. Summary of changes in 5.1 TBD. Changes since 5.1b1: Created a db.any.docbook pattern that matches any single DocBook pattern. This pattern allows, for example, the resource element to contain text or any (single) valid DocBook element. (Allowing for more than one element would introduce the possibility of invalid combinations that would not be easy to detect.) Added renderas to structure. Changed renderas (in at least these contexts) to be a QName). Added override to structure. Took info out of relationship and put association back in. Fixed content model of book and part to make topic an alternative and not part of the component mixture. Fixed a few pattern typos in assembly-core.rnc. Make structure optional in assembly. Removed the description attribute from assemblies. No human readable content in attribute values! (This has turned out to be someone contentious within the Technical Committee.) Added more documentation, though it's still far from complete. Requests for enhancement addressed in 5.1b1: RFE 1679665 Add better support for modular documentation RFE 1722935 Add a proofreader value to the class attribute for othercredit RFE 1770787 Add givenname as an alternative for firstname RFE 1899655 Allow more elements to be the root of a DocBook document RFE 2100736 Allow constant in initializer RFE 2791288 Added several additional elements, including quote, to the ubiquitous inlines RFE 2820190 Add a topic element RFE 2821653 Remove the constraint that indexterm elements must not appear in footnotes RFE 2907124 Allow personal name components directly in bibliomset. RFE 2907125 Allow all inlines in remark RFE 2907131 Allow simplesect in colophon RFE 2964576 Fix the bug that allowed table to appear inside entry

Historically, when DocBook was defined by a DTD, DocBook documents could be identified by the presence of standard public and/or system identifiers in the document type declaration. RELAX NG, the normative schema language for DocBook V5.1, does not provide any equivalent mechanism. For systems that can make use of public identifiers, e.g., systems where the informative DTD is being used, the following public identifier can be used for DocBook V5.1: “-//OASIS//DTD DocBook V5.1//EN//XML”.

This specification normatively defines DocBook V5.1 with a RELAX NG grammar and a set of Schematron assertions. A conformant DocBook V5.1 document must be valid according to both the grammar and the assertions. The reference documentation describes additional constraints and processing expectations. A conformant DocBook V5.1 document should respect those constraints and anticipate those processing expectations.

The DocBook Technical Committee understands that the community benefits from the long-term stability of the DocBook family of schemas. We also understand that DocBook must continue to adapt and change in order to remain relevant in a changing world. All changes, and especially changes that are backwards incompatible (changes that make a currently valid document no longer valid under a new version of the schema), have a cost associated with them. Our duty is to balance those costs against the need to remain responsive to the community's desire to see DocBook grow to cover the new use cases that inevitably arise in documentation. With that in mind, the DocBook Technical Committee has adopted the following policy on backwards incompatible changes. This policy spells out when backwards incompatible changes can occur and how much notice the TC must provide before adopting a schema that is backwards incompatible with the current release. This policy allows DocBook to continue to change and adapt while simultaneously guaranteeing that existing users will have sufficient advance notice to develop reasonable migration plans. With respect to schema changes, the following points must always apply: A point release (X.1 to X.2, X.2 to X.3, X.1 to X.1.2, etc.) must not contain any backwards incompatible changes unless those changes correct obvious bugs accidentally introduced in the preceding version. A major release (X.1 to Y.0, X.2 to Y.0, X.1.2 to Y.0, etc.) may contain backwards incompatible changes if both of the following conditions are true: The change was announced in the release notes for the previous version (major or minor). The change was announced in a release that occurred at least six months previously. By these rules, the TC can announce, in V5.1 for example, its plans to make a backwards incompatible change in V6.0. Then, in V6.0, if it's been at least six months since V5.1 was released, it can make that change. The exclusion in point 1 is designed to allow the committee to correct errors accidentally introduced in a point release, that are technically backwards incompatible, without having to leave them in the schema until the next full version.

See for a list of tools that can validate an XML document using RELAX NG. Note that not all products are capable of evaluating the Schematron assertions in the schema.

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.

This appendix registers a new MIME media type, application/docbook+xml.

MIME media type name: application MIME subtype name: docbook+xml Required parameters: None. Optional parameters: charset This parameter has identical semantics to the charset parameter of the application/xml media type as specified in or its successors. Encoding considerations: By virtue of DocBook XML content being XML, it has the same considerations when sent as application/docbook+xml as does XML. See , Section 3.2. Security considerations: Several DocBook elements may refer to arbitrary URIs. In this case, the security issues of RFC 2396, section 7, should be considered. Interoperability considerations: None. Published specification: This media type registration is for DocBook documents as described by . Applications which use this media type: There is no experimental, vendor specific, or personal tree predecessor to application/docbook+xml, reflecting the fact that no applications currently recognize it. This new type is being registered in order to allow for the deployment of DocBook on the World Wide Web, as a first class XML application. Additional information: Magic number(s): There is no single initial octet sequence that is always present in DocBook documents. File extension(s): DocBook documents are most often identified with the extension .xml. Macintosh File Type Code(s): TEXT Person & email address to contact for further information: Norman Walsh, ndw@nwalsh.com. Intended usage: COMMON Author/Change controller: The DocBook specification is a work product of the DocBook Technical Committee at OASIS.

For documents labeled as application/docbook+xml, the fragment identifier notation is exactly that for application/xml, as specified in or its successors.

The following individuals have participated in the creation of this specification and are gratefully acknowledged: Gary Cornelius, Individual Paul Grosso, Arbortext Dick Hamilton, Individual Nancy Harrison, IBM Scott Hudson, Individual Gershon Joseph, Tech-Tav Documentation Ltd. Jirka Kosek, Individual Larry Rowland, Hewlett-Packard Robert Stayton, Individual (Secretary) Norman Walsh, MarkLogic Corporation (Chair, Editor) This specification does not yet reflect any schema changes.