+++ /dev/null
-<?xml version="1.0" encoding="utf-8"?> <!-- -*- nxml -*- -->
-<!DOCTYPE book [
-<!ENTITY version "5.0">
-<!--
-<!ENTITY yes "<phrase dbk:role='unicode yes'>✔</phrase>">
-<!ENTITY no "<phrase dbk:role='unicode no'>✘</phrase>">
--->
-<!ENTITY yes "<phrase dbk:role='unicode yes'>YES</phrase>">
-<!ENTITY no "<phrase dbk:role='unicode no'>NO</phrase>">
-]>
-<book xmlns="http://docbook.org/ns/docbook" xmlns:dbk="http://docbook.org/ns/docbook"
- xmlns:xl="http://www.w3.org/1999/xlink" xml:lang="en">
-<article>
-<info>
-<title>DocBook V5.0</title>
-<subtitle>The Transition Guide</subtitle>
-
-<authorgroup>
-<author><personname>Jirka Kosek</personname>
- <email>jirka@kosek.cz</email></author>
-<author><personname>Norman Walsh</personname>
- <email>ndw@nwalsh.com</email>
- <contrib>§convert4to5, proofreading</contrib></author>
-<author><personname>Dick Hamilton</personname>
- <email>rlhamilton@frii.com</email>
- <contrib>§changes-removed, customization, proofreading</contrib></author>
-<othercredit
- dbk:class="other"
- dbk:otherclass="contributor"
- ><personname>Michael(tm) Smith</personname>
- <email>smith@sideshowbarker.net</email>
- <contrib>§dbxsl-ns</contrib>
-</othercredit>
-</authorgroup>
-
-<pubdate>2009-06-16</pubdate>
-<pubdate>2008-02-06</pubdate>
-<pubdate>2007-10-28</pubdate>
-<pubdate>2006-10-22</pubdate>
-<pubdate>2006-05-16</pubdate>
-<pubdate>2006-03-01</pubdate>
-<pubdate>2005-12-28</pubdate>
-<pubdate>2005-10-27</pubdate>
-
-</info>
-
-<para>This document is targeted at DocBook users who are considering
-switching from DocBook V4.x to DocBook V5.0. It describes
-differences between DocBook V4.x and V5.0 and provides some suggestions about
-how to edit and process DocBook V5.0 documents. There is
-also a section devoted to conversion of legacy documents from DocBook
-4.x to DocBook V5.0.</para>
-
-<para>At the time this was written the current version of DocBook V5.0
-was &version;. However, almost all of the information in this document is
-general and applies to any newer version of DocBook V5.0.
-</para>
-
-<section xml:id="introduction">
-<title>Introduction</title>
-
-<para>The differences between DocBook V4.x and V5.0 are quite radical in
-some aspects, but the basic idea behind DocBook is still the same, and
-almost all element names are unchanged. Because of this it is very
-easy to become familiar with DocBook V5.0 if you know any previous version of
-DocBook. You can find a complete list of changes in
-<citation>DB5SPEC</citation>, here we will discuss only the most
-fundamental changes.</para>
-
-<section xml:id="introduction-ns">
-<title>Finally in a namespace</title>
-
-<para>All DocBook V5.0 elements are in the namespace
-<uri>http://docbook.org/ns/docbook</uri>. <acronym>XML<alt>Extensible
-Markup Language</alt></acronym> namespaces are used to distinguish
-between different element sets. In the last few years, almost all new
-XML grammars have used their own namespace. It is easy to
-create compound documents that contain elements from different XML
-vocabularies. DocBook V5.0 is following this design rule. Using
-namespaces in your documents is very easy. Consider this
-simple article marked up in DocBook V4.5:</para>
-
-<programlisting><![CDATA[<article>
- <title>Sample article</title>
- <para>This is a really short article.</para>
-</article>]]></programlisting>
-
-<para>The corresponding DocBook V5.0 article will look very similar:</para>
-
-<programlisting><![CDATA[<article xmlns="http://docbook.org/ns/docbook" …>
- <title>Sample article</title>
- <para>This is a really short article.</para>
-</article>]]></programlisting>
-
-<para>The only change is the addition of a default namespace declaration
-(<code>xmlns="http://docbook.org/ns/docbook"</code>) on the root
-element. This declaration applies the namespace to the root element and
-all nested elements. Each
-element is now uniquely identified by its local name and namespace.</para>
-
-<note>
-<para>The namespace name <uri>http://docbook.org/ns/docbook</uri> serves
-only as an identifier. This resource is not fetched during processing
-of DocBook documents, and you are not required to have an Internet
-connection during processing. If you access the namespace URI with a browser,
-you will find a short explanatory document about the namespace. In the
-future this document will probably conform to (some version of) RDDL
-and provide pointers to related resources.</para>
-</note>
-
-</section>
-
-<section xml:id="introduction-rng">
-<title>Relaxing with DocBook</title>
-
-<para>For more than a decade, the DocBook schema was defined using a
-DTD. However, DTDs have serious limitations, and DocBook V5.0 is thus
-defined using a very powerful schema language called RELAX NG. Thanks
-to RELAX NG, it is now much easier to create customized versions of
-DocBook, and some content models are now cleaner and more
-precise.</para>
-
-<para>Using RELAX NG has an impact on the document prolog. The following
-example shows the typical prolog of a DocBook V4.x document. The version of
-the DocBook DTD (in this case 4.5) is indicated in the document type
-declaration (!DOCTYPE) which points to a particular version of the
-DTD.</para>
-
-<example xml:id="ex.docbook45">
-<title>DocBook V4.5 document</title>
-<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
- 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
-<article lang="en">
- <title>Sample article</title>
- <para>This is a very short article.</para>
-</article>]]></programlisting>
-</example>
-
-<para>In contrast, DocBook V5.0 does not depend on DTDs anymore. This
-mean that there is no document type declaration and the version of DocBook
-used is indicated with the <tag dbk:class="attribute">version</tag>
-attribute instead.</para>
-
-<example xml:id="ex.docbook5">
-<title>DocBook V5.0 document</title>
-<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8"?>
-<article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
- <title>Sample article</title>
- <para>This is a very short article.</para>
-</article>]]></programlisting>
-</example>
-
-<para>As you can see, DocBook V5.0 is built on top of existing XML
-standards as much as possible, for example the <tag
-dbk:class="attribute">lang</tag> attribute is superseded by the standard
-<tag xl:href="http://www.w3.org/TR/REC-xml/#sec-lang-tag"
-dbk:class="attribute">xml:lang</tag> attribute.</para>
-
-<para>Another fundamental change is that there is no direct indication
-of the schema used. Later in this document, you will learn how you can
-specify a schema to be used for document validation.</para>
-
-<note>
-<para>Although we recommend the RELAX NG schema for DocBook
-V5.0, there are also DTD and W3C XML Schema versions available (see <xref
-dbk:linkend="schemas"/>) for tools that do not yet support RELAX NG.</para>
-</note>
-
-</section>
-
-<section xml:id="introduction-why-to-switch">
-<title>Why switch to DocBook V5.0?</title>
-
-<para>The simple answer is <quote>because DocBook V5.0 is the
-future</quote>. Apart from this marketing blurb, there are also more
-technical reasons:</para>
-
-<itemizedlist>
-<listitem>
-<para><emphasis>DocBook V4.x is feature frozen.</emphasis>DocBook V4.5
-is the last version of DocBook in the V4.x series. Any new DocBook
-development, like the addition of new elements, will be done in
-DocBook V5.0. It is only matter of time before useful, new elements
-will be added into DocBook V5.0, but they are not likely to be back
-ported into DocBook V4.x. DocBook V4.x will be in maintenance mode and
-errata will be published if necessary. </para>
-</listitem>
-<listitem>
-<para><emphasis>DocBook V5.0 offers new functionality.</emphasis>
-DocBook V5.0 provides significant improvements over DocBook V4.x. For
-example there is general markup for annotations, a new and flexible
-system for linking, and unified markup for information sections using
-the <tag>info</tag> element.</para>
-</listitem>
-<listitem>
-<para><emphasis>DocBook V5.0 is more extensible.</emphasis> Having
-DocBook V5.0 in a separate namespace allows you to easily mix DocBook
-markup with other XML-based languages like SVG, MathML, XHTML or even
-FooBarML.</para>
-</listitem>
-<listitem>
-<para><emphasis>DocBook V5.0 is easier to customize.</emphasis> RELAX
-NG offers many powerful constructs that make customization much easier
-than it would be using a DTD (see <xref dbk:linkend="customizations"/>).</para>
-</listitem>
-</itemizedlist>
-
-</section>
-
-<section xml:id="introduction-schemas">
-<title>Schema jungle</title>
-
-<para>Schemas for DocBook V5.0 are available in several formats at
-<link xl:href="http://www.oasis-open.org/docbook/xml/&version;/"/> (or the
-mirror at <link xl:href="http://docbook.org/xml/&version;/"/>).
-Only the RELAX NG schema is normative
-and it is preferred over the other schema languages. However, for your
-convenience there are also DTD and W3C XML Schema versions provided for DocBook
-V5.0. But please note that neither the DTD nor the W3C XML schema are able to
-capture all the constraints of DocBook V5.0. This mean that a
-document that validates against the DTD or XML schema is not necessarily
-valid against the RELAX NG schema and thus may not be a valid
-DocBook V5.0 document. See <xref dbk:linkend="t.schema-comparison"/> for
-summary of constraints that are checked by different schemas.</para>
-
-<para>DTD and W3C XML Schema versions of the DocBook V5.0 grammar are provided
-as a convenience for users who want to use DocBook V5.0 with legacy tools
-that don't support RELAX NG. Authors are encouraged to switch to RELAX
-NG based tools as soon as possible, or at least to validate documents
-against the RELAX NG schema before further processing.</para>
-
-<para>Some document constraints can't be expressed in schema languages
-like RELAX NG or W3C XML Schema. To check for these additional
-constraints DocBook V5.0 uses Schematron. We recommend that you
-validate your document against both the RELAX NG and
-Schematron schemas.</para>
-
-<table xml:id="t.schema-comparison">
- <title>Schema Comparison</title>
- <tgroup dbk:cols="6">
- <colspec dbk:colwidth="4*"/>
- <colspec dbk:colwidth="1*" dbk:align="center"/>
- <colspec dbk:colwidth="1*" dbk:align="center"/>
- <colspec dbk:colwidth="1*" dbk:align="center"/>
- <colspec dbk:colwidth="1*" dbk:align="center"/>
- <colspec dbk:colwidth="1*" dbk:align="center"/>
- <thead>
- <row>
- <entry>Description</entry>
- <entry>DTD</entry>
- <entry>W3C XML Schema</entry>
- <entry>W3C XML Schema + Schematron</entry>
- <entry>RELAX NG</entry>
- <entry>RELAX NG + Schematron/NVDL</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Basic document structure</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- </row>
- <row>
- <entry>ID/IDREF datatypes</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- </row>
- <row>
- <entry>Datatypes<footnote>
- <para>In a very few places RELAX NG specifies datatype
- like number (mainly for length specifications) or
- enumeration between <literal>0</literal> and
- <literal>1</literal>.</para>
- <para>In general those datatypes can be also supported in
- W3C XML Schema, but currently this schema is generated
- from DTD which lacks datatype information.</para>
- </footnote>
- </entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- </row>
- <row>
- <entry>Co-occurrences<footnote>
- <para>RELAX NG grammar enforces exclusivity of several
- elements. For example if you have <tag>title</tag> inside
- <tag>info</tag> then it is not allowed to have another
- <tag>title</tag> outside <tag>info</tag>. Similarly,
- models of HTML and CALS tables are separated and validated
- properly, where in DTD and WXS only union of both models is
- available.</para>
- <para>On other places co-occurrences enforces particular
- content model based on presence of specific attribute or
- attribute value.</para>
- <para>Please also note that in theory co-occurences can be
- validated using Schematron, but the current DocBook schema
- uses RELAX NG for these definitions. Schematron can be used
- only for validation, whereas grammar based schemas like
- RELAX NG are useful also for other purposes like guided editing.</para>
- </footnote></entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- </row>
- <row>
- <entry>Hooks for MathML and SVG content</entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- <entry>&yes;</entry>
- </row>
- <row>
- <entry>Link type integrity<footnote>
- <para>Check whether ID/IDREF links are pointing to element
- of corresponding type. For example that
- <tag>footnoteref</tag> points to
- <tag>footnote</tag>.</para></footnote></entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- </row>
- <row>
- <entry>Presence of <tag dbk:class="attribute">version</tag>
- attribute on the root element</entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- </row>
- <row>
- <entry>Miscellaneous checks<footnote>
- <para>For example consistency of segmented lists, only one
- term inside term definition etc.</para></footnote></entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- </row>
- <row>
- <entry>Element exclusions<footnote>
- <para>Prevents improper nesting of elements, like admonition
- inside admonition.</para></footnote></entry>
- <entry>&no;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- <entry>&no;</entry>
- <entry>&yes;</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<section xml:id="schemas">
-<title>Where to get the schemas</title>
-
-<para>The latest versions of schemas can be obtained from <link
-xl:href="http://docbook.org/schemas/5x.html"/>. At the time this was
-written the latest version was &version;. Individual schemas are
-available at the following locations:</para>
-
-<variablelist>
-<varlistentry>
-<term>RELAX NG schema</term>
-<listitem><para><link xl:href="http://docbook.org/xml/&version;/rng/docbook.rng"/></para></listitem>
-</varlistentry>
-<varlistentry>
-<term>RELAX NG schema in compact syntax</term>
-<listitem><para><link xl:href="http://docbook.org/xml/&version;/rng/docbook.rnc"/></para></listitem>
-</varlistentry>
-<varlistentry>
-<term>DTD</term>
-<listitem><para><link xl:href="http://docbook.org/xml/&version;/dtd/docbook.dtd"/></para></listitem>
-</varlistentry>
-<varlistentry>
-<term>W3C XML Schema</term>
-<listitem><para><link xl:href="http://docbook.org/xml/&version;/xsd/docbook.xsd"/></para></listitem>
-</varlistentry>
-<varlistentry>
-<term>Schematron schema with additional checks</term>
-<listitem><para><link xl:href="http://docbook.org/xml/&version;/sch/docbook.sch"/></para></listitem>
-</varlistentry>
-</variablelist>
-
-<para>These schemas are also available from the mirror at
-<link xl:href="http://www.oasis-open.org/docbook/xml/&version;/"/>.</para>
-
-</section>
-
-<section xml:id="docs">
-<title>DocBook documentation</title>
-
-<para>Detailed documentation about each DocBook V5.0 element is
-presented in <link
-xl:href="http://docbook.org/tdg5/en/html/pt02.html">the reference part
-of <citetitle>DocBook: The Definitive Guide</citetitle></link>.</para>
-
-<note>
-<para>Other parts of <citetitle>DocBook: The Definitive
-Guide</citetitle> have not yet been updated to reflect the changes
-made in DocBook V5.0. Please do not be confused by this.</para>
-</note>
-
-</section>
-
-</section>
-
-</section>
-
-<section xml:id="tools">
-<title>Tool chain</title>
-
-<para>This section briefly describes tools and procedures to edit and
-process content stored in DocBook V5.0.</para>
-
-<section xml:id="editors">
-<title>Editing DocBook V5.0</title>
-
-<para>Because DocBook is an XML-based format and XML is a text-based
-format, you can use any text editor to create and edit DocBook V5.0
-documents. However, using <quote>dumb</quote> editors like Notepad is
-not very productive. You will do better if you use an editor that
-supports XML. Although there are DTD and W3C XML Schemas available for
-DocBook V5.0, which means you can use any editor that works with DTDs
-or W3C XML Schemas, we recommend that you use the RELAX NG grammar
-with DocBook V5.0. The rest of this section contains an overview of
-XML editors (listed in alphabetical order) that are known to work with
-RELAX NG schemas and that offer guided editing based on the RELAX NG
-schema.</para>
-
-<section xml:id="editors-nxml">
-<title>Emacs and nXML</title>
-
-<para><link xl:href="http://www.thaiopensource.com/nxml-mode/">nXML
-mode</link> is an add-on for the <application
-xl:href="http://www.gnu.org/software/emacs/emacs.html">GNU
-Emacs</application> text editor. By installing nXML you can turn Emacs
-into a very powerful XML editor that offers guided editing and
-validation of XML documents.</para>
-
-<figure xml:id="f.emacs">
-<title>Emacs with nXML mode provides guided editing and validation</title>
-<mediaobject>
-<imageobject dbk:role="html">
-<imagedata dbk:fileref="images/emacs.png"/>
-</imageobject>
-<imageobject dbk:role="fo">
-<imagedata dbk:fileref="images/emacs.png" dbk:width="100%"/>
-</imageobject>
-</mediaobject>
-</figure>
-
-<para>nXML uses a special configuration file named
-<filename>schemas.xml</filename> to associate schemas with XML
-documents. Often you will find this file in the directory
-<filename>site-lisp/nxml/schema</filename> inside the Emacs installation
-directory. Adding the following line into the configuration file,
-will associate DocBook V5.0 elements with the appropriate
-schema:</para>
-
-<programlisting><namespace ns="http://docbook.org/ns/docbook" uri="<replaceable>/path/to/</replaceable>docbook.rnc"/></programlisting>
-
-<note>
-<para>Please note that nXML ships with a file named
-<filename>docbook.rnc</filename>. This file contains the RELAX NG grammar
-for DocBook V4.x. Be sure that you associate the DocBook V5.0 namespace
-with the corresponding DocBook V5.0 grammar.</para>
-</note>
-
-<para>If you can't edit the global <filename>schemas.xml</filename> file,
-you can create this file in the same directory as your document. nXML will
-find associations placed there also. In this case you must create a
-complete configuration file like:</para>
-
-<programlisting><locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
- <namespace ns="http://docbook.org/ns/docbook" uri="<replaceable>/path/to/</replaceable>docbook.rnc"/>
-</locatingRules></programlisting>
-
-</section>
-
-<section xml:id="editors-oxygen">
-<title>oXygen</title>
-
-<para><application
-xl:href="http://www.oxygenxml.com/">oXygen</application> is a feature
-rich XML editor. It has built-in support for many schema languages
-including RELAX NG and it is preconfigured with many document types
-including DocBook. oXygen will assist you with writing DocBook V5.0
-content, and you will be able to validate your documents against both
-RELAX NG and Schematron schemas.</para>
-
-<figure xml:id="f.oxygen.open5">
-<title>DocBook V5.0 document opened in oXygen</title>
-<mediaobject>
-<imageobject>
-<imagedata dbk:fileref="images/oxygen4.png" dbk:width="100%"/>
-</imageobject>
-</mediaobject>
-</figure>
-
-<figure xml:id="f.oxygen.author.mode">
-<title>DocBook V5.0 document opened in oXygen in Author mode</title>
-<mediaobject>
-<imageobject>
-<imagedata dbk:fileref="images/oxygen5.png" dbk:width="100%"/>
-</imageobject>
-</mediaobject>
-</figure>
-
-</section>
-
-<section xml:id="editors-xxe">
-<title>XML Mind XML editor</title>
-
-<para><application xl:href="http://www.xmlmind.com/xmleditor/">XML
-Mind XML editor</application> (XXE) is a visual validating XML editor that
-provides a wordprocessor-like interface to users. It is available in
-two versions, Standard and Professional. The Standard version is free and
-provides everything you need to edit DocBook V5.0 documents.</para>
-
-<figure xml:id="f.xmlmind">
-<title>XML Mind XML Editor – feels almost like MS Word but real DocBook V5.0 markup is created</title>
-<mediaobject>
-<imageobject>
-<imagedata dbk:fileref="images/xxe.png" dbk:width="100%"/>
-</imageobject>
-</mediaobject>
-</figure>
-
-<para>In order to use DocBook V5.0 in XXE you have to install
-an add-on. Go to
-<menuchoice><guimenu>Options</guimenu><guimenuitem>Install
-Add-ons…</guimenuitem></menuchoice>. Then choose <guilabel>DocBook
-5 configuration</guilabel> and press the <guibutton>OK</guibutton>
-button. After restart, XXE is ready to work with DocBook V5.0
-documents.</para>
-
-</section>
-
-</section>
-
-<section xml:id="validators">
-<title>Validating DocBook V5.0</title>
-
-<para>If you are not using a RELAX NG-based validating editor when you
-create documents, we strongly recommend that you validate your
-documents against RELAX NG and Schematron schemas before processing
-them. Only after successful validation can you be sure that your
-document is really DocBook V5.0 and that processing tools will be able
-to process it correctly.</para>
-
-<para>For validation you can use tools that support simultaneous RELAX NG and
-Schematron validation, or you can use NVDL to orchestrate validation using
-the two schemas.</para>
-
-<section xml:id="validators-rng-sch">
-<title>Using RELAX NG and Schematron</title>
-
-<para>You can find a list of RELAX NG validators at <link
-xl:href="http://relaxng.org/#validators"/>. It is best to use
-validators with support for embedded Schematron rules inside RELAX NG
-schemas. Schematron is a rule-based validation language which is used
-to impose additional constraints on DocBook documents. Schematron rules
-assert conditions which are impossible or difficult to express
-in a pure RELAX NG schema.</para>
-
-<para><application xl:href="https://msv.dev.java.net/">Sun
-Multi-Schema XML Validator (MSV)</application> is able to validate an XML
-document against a RELAX NG schema and Schematron rules at the same time.
-To install and use MSV follow these steps:</para>
-
-<procedure>
-<step>
-<para>Download <filename>relames.zip</filename> from <link xl:href="https://msv.dev.java.net/servlets/ProjectDocumentList?folderID=101"/>.</para>
-</step>
-<step>
-<para>Unpack the downloaded file into an arbitrary directory.</para>
-</step>
-<step>
-<para>Validate your document using the following command:</para>
-<screen><command>java</command> -Xss512K -jar <replaceable>/path/to/</replaceable>relames.jar <replaceable>/path/to/</replaceable>docbook.rng document.xml</screen>
-<note>
-<para>The switch <option>-Xss512K</option> increases the stack size
-of the Java virtual machine. This is necessary because the DocBook schema is
-quite large. If you get stack overflow errors from MSV, increase
-this value. You may get spurious error messages if the value
-is too small, so if you get a stack overflow error, ignore any other error
-messages and try a larger value for the stack size.
-If you are not using Sun's Java implementation, please consult the
-documentation for your virtual machine to learn how to increase the stack
-size.</para>
-</note>
-</step>
-</procedure>
-
-<para>There is also an <link
-xl:href="http://relaxed.vse.cz/docbookvalidator/">on-line DocBook V5.0
-validator</link> that validates DocBook V5.0 documents against the normative
-RELAX NG schema with embedded Schematron rules.</para>
-
-</section>
-
-<section>
-<title>Using NVDL</title>
-
-<para>NVDL is a meta-schema language which can validate a document
-against several schemas. DocBook V5.0 comes with a NVDL
-schema which specifies that DocBook documents should be validated
-against both RELAX NG and Schematron schemas.</para>
-
-<para>You can find a list of NVDL validators at <link
-xl:href="http://nvdl.org/"/>. The following procedures show how to
-install and use the <application
-xl:href="http://www.oxygenxml.com/onvdl.html">oNVDL</application> and
-<application xl:href="http://jnvdl.sourceforge.net">JNVDL</application>
-validators.</para>
-
-<procedure>
-<title>oNVDL installation and usage</title>
-<step>
-<para>Download <filename
-xl:href="http://www.oxygenxml.com/InstData/onvdl/onvdl-20070517.zip">onvdl-20070517.zip</filename>.</para>
-</step>
-<step>
-<para>Unpack the downloaded file into an arbitrary directory.</para>
-</step>
-<step>
-<para>Validate your document using the following command:</para>
-<screen><command>java</command> -jar <replaceable>/path/to/oNVDL/</replaceable>bin/onvdl.jar <replaceable>/path/to/</replaceable>docbook.nvdl document.xml</screen>
-</step>
-</procedure>
-
-<procedure>
-<title>JNVDL installation and usage</title>
-<step>
-<para>Download the latest release of JNVDL from <link
-xl:href="http://sourceforge.net/project/showfiles.php?group_id=164464"/>.</para>
-</step>
-<step>
-<para>Unpack the downloaded file into an arbitrary directory.</para>
-</step>
-<step>
-<para>Modify file <filename>jnvdl.bat</filename> (or <filename>jnvdl.sh</filename> on Unix based systems) to include <option>-Xss512K</option> switch directly after <command>java</command> command.</para>
-</step>
-<step>
-<para>On Windows systems, validate your document using the following command:</para>
-<screen><replaceable>/path/to/jnvdl/</replaceable><command>jnvdl</command> -nt -s <replaceable>/path/to/</replaceable>docbook.nvdl document.xml</screen>
-<para>On Unix systems, validate your document using the following command:</para>
-<screen><replaceable>/path/to/jnvdl/</replaceable><command>jnvdl.sh</command> -nt -s <replaceable>/path/to/</replaceable>docbook.nvdl document.xml</screen>
-</step>
-</procedure>
-
-</section>
-
-</section>
-
-<section xml:id="processing">
-<title>Processing DocBook V5.0</title>
-
-<para>Part of DocBook's great success can be attributed to the
-availability of free
-tools that can be used to transform DocBook content into various
-target formats including HTML and PDF. The DocBook XSL Stylesheets are
-very popular tools.</para>
-
-<section xml:id="dbxsl">
-<title>DocBook XSL Stylesheets</title>
-
-<para>The DocBook stylesheets are designed to process content written in
-different versions of DocBook (for example 3.1 and 4.2). Recent
-versions of the stylesheets are also able to process DocBook V5.0
-with some limitations.</para>
-
-<para>You can process DocBook V5.0 documents with the DocBook XSL
-stylesheets in exactly the same way you process DocBook V4.x documents.
-You do not need special software; you can stick to your preferred
-XSLT processor, be it Saxon, xsltproc, Xalan or whatever else (but see
-the note about the lost base URI below).</para>
-
-<para>During document processing, the stylesheets strip
-namespaces from DocBook V5.0 to get a document which will be
-very similar to DocBook V4.x. This is necessary because from the XSLT
-point of view, elements from different namespaces are distinct and cannot
-be easily processed by the same set of templates. This process is
-completely transparent to the user. If you are processing DocBook V5.0
-documents, the only difference is that you will see the following
-additional message:</para>
-
-<screen>Note: namesp. cut : stripped namespace before processing
-Note: namesp. cut : processing stripped document</screen>
-
-<para>Although you can successfully use the existing stylesheets to
-process DocBook V5.0, there are some limitations and unsupported
-features. The unsupported features include:</para>
-
-<itemizedlist>
-<listitem><para>general annotations;</para></listitem>
-<listitem><para>general XLink links on all elements.</para></listitem>
-</itemizedlist>
-
-<note>
-<para>During namespace stripping, the base URI of the document is
-lost. This means that in rare situations, relatively referenced
-resources like images or programlistings can be processed incorrectly.
-The stylesheets attempt to compensate for this problem, but that is not always
-possible. When an XSLT processor other than Saxon or Xalan is used, a warning
-message is generated:
-
-<screen>WARNING: cannot add @xml:base to node set root element. Relative paths may not work.</screen>
-</para>
-
-</note>
-</section>
-
-<section xml:id="dbxsl-ns">
-<title>DocBook XSL-NS Stylesheets</title>
-<para>As you can see from reading the previous section, namespace
- stripping has limitations that will cause trouble in some
- situations. To overcome those limitations, Bob Stayton created a
- build system for taking the non-namespace-aware DocBook XSL
- stylesheets and generating namespace-aware versions from them.
- The DocBook <link
- xl:href="http://docbook.sourceforge.net/release/xsl-ns/current/"
- >XSL-NS stylesheets</link> are the result.</para>
-
-<para>The DocBook XSL-NS stylesheets are released side-by-side
- with the DocBook XSL stylesheets, as a separate <link
- xl:href="https://sourceforge.net/project/showfiles.php?group_id=21935&package_id=219178"
- ><package>docbook-xsl-ns</package></link> package. They are the
-recommended XSLT 1.0 stylesheets to use for transforming
-namespaced (DocBook V5.0) documents.</para>
-</section>
-
-<section xml:id="dbxsl2">
-<title>XSLT 2.0 based re-implementation</title>
-
-<para>XSLT 1.0 is missing some important features. To work around
-these missing features, the current DocBook XSL stylesheets use some
-implementation-specific extensions.
-XSLT 2.0 adds many new and previously missing features into the language.
-A new set of DocBook stylesheets is being implemented based on XSLT 2.0
-to take advantage of these features and to fully support DocBook V5.0.
-</para>
-
-<para>The XSLT 2.0 based stylesheets have many new features, including:</para>
-
-<itemizedlist>
-<listitem><para>seamless integration of profiling (conditional
-documents) with external bibliographies and
-glossaries;</para></listitem>
-<listitem><para>no need for (most) external extensions;</para></listitem>
-<listitem><para>internationalized indexes;</para></listitem>
-<listitem><para>easy to customize titlepage templates.</para></listitem>
-</itemizedlist>
-
-<para>The XSLT 2.0 based stylesheets are still under development. At
-this writing, they only support HTML and chunked HTML output. As time
-permits, the stylesheet developers will be adding other formats. Since
-the stylesheets are developed in the limited free time the developers
-have, there's no specific schedule.</para>
-
-<para>There are not very many XSLT 2.0 implementations available.
-But, if you want to try the new stylesheets, grab a snapshot of
-the development version from <link
-xl:href="http://docbook.sourceforge.net/snapshots/docbook-xsl2-snapshot.zip"/>
-and unpack it somewhere. Then download and install Saxon 9 from <link
-xl:href="http://saxon.sf.net"/>.</para>
-
-<para>To transform a DocBook V5.0 document to a single HTML page use the command:</para>
-
-<screen><command>java</command> -jar <replaceable>/path/to/</replaceable>saxon9.jar -o output.html document.xml <replaceable>/path/to/</replaceable>docbook-xsl2-snapshot/html/docbook.xsl</screen>
-
-<para>To transform a DocBook V5.0 document to a set of chunked HTML pages use the command:</para>
-
-<screen><command>java</command> -jar <replaceable>/path/to/</replaceable>saxon9.jar document.xml <replaceable>/path/to/</replaceable>docbook-xsl2-snapshot/html/chunk.xsl</screen>
-
-</section>
-
-</section>
-
-</section>
-
-<section xml:id="changes">
-<title>Markup changes</title>
-
-<para>This section describes the most common markup changes
-between DocBook V4.x and V5.0.
-You can find a complete list of changes in
-<citation>DB5SPEC</citation>.</para>
-
-<section xml:id="changes-linking">
-<title>Improved cross-referencing and linking</title>
-
-<para>In DocBook V4.x the attribute <tag dbk:class="attribute">id</tag> is
-used to assign a unique identifier to an element. In DocBook V5.0 this
-attribute is renamed <tag dbk:class="attribute">xml:id</tag> in order
-to comply with <citation>XMLID</citation>.</para>
-
-<para>Now you can use almost any inline element as the source of a link,
-not just <tag>xref</tag> or <tag>link</tag>. For example, the following
-DocBook 4.x content:</para>
-
-<programlisting><![CDATA[<section id="dir">
- <title>DIR command</title>
- <para>...</para>
-</section>
-
-<section id="ls">
- <title>LS command</title>
- <para>This command is a synonym for <link linkend="dir"><command>DIR</command></link> command.</para>
-</section>]]></programlisting>
-
-<para>is written in DocBook V5.0 as:</para>
-
-<programlisting><![CDATA[<section xml:id="dir">
- <title>DIR command</title>
- <para>...</para>
-</section>
-
-<section xml:id="ls">
- <title>LS command</title>
- <para>This command is a synonym for <command linkend="dir">DIR</command> command.</para>
-</section>]]></programlisting>
-
-<para>The <tag dbk:class="attribute">linkend</tag> attribute was added to all
-inline elements together with the <tag dbk:class="attribute">href</tag>
-attribute from the XLink namespace. This means that you can use any inline
-element as the source of a hypertext link. To use XLinks you have
-to declare the XLink namespace (most often on the root element of your
-document):</para>
-
-<programlisting><![CDATA[<article xmlns="http://docbook.org/ns/docbook"
- xmlns:xl="http://www.w3.org/1999/xlink" version="5.0">
- <title>Test article</title>
-
- <para><application xl:href="http://www.gnu.org/software/emacs/emacs.html">Emacs</application>
- is my favourite text editor.</para>]]>
- …</programlisting>
-
-<para>The <tag dbk:condition="v4">ulink</tag> element was removed from DocBook V5.0
-in favor of XLink linking. Instead of the DocBook V4.x <tag dbk:condition="v4">ulink</tag>
-element:</para>
-
-<programlisting><![CDATA[<ulink url="http://docbook.org">DocBook site</ulink>]]></programlisting>
-
-<para>you can now use <tag>link</tag></para>
-
-<programlisting><![CDATA[<link xl:href="http://docbook.org">DocBook site</link>]]></programlisting>
-
-<para>XLink links may contain a fragment identifier, which you can
-use instead of <tag dbk:class="attribute">linkend</tag> to form
-cross-references inside a document; for example:</para>
-
-<programlisting><![CDATA[<command xl:href="#dir">DIR</command>]]></programlisting>
-
-<para>However XLink links are not checked during validation, while <tag
-dbk:class="attribute">xml:id</tag>/<tag dbk:class="attribute">linkend</tag>
-links are checked for ID/IDREF consistency.
-One place where the XLink-based, fragment identifier scheme is
-useful is when XInclude is being used, since XML ID/IDREF links
-cannot span XInclude boundaries.
-You can use whichever approach better suits your needs.</para>
-</section>
-
-<section xml:id="changes-renamed">
-<title>Renamed elements</title>
-
-<para>Some elements were renamed to better express their meaning or to
-reduce the total number of elements available in DocBook.</para>
-
-<table xml:id="t.renamed">
-<title>Renamed elements</title>
-<tgroup dbk:cols="2">
-<thead>
-<row>
-<entry>Old name</entry>
-<entry>New name</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><tag dbk:condition="v4">sgmltag</tag></entry>
-<entry><tag>tag</tag></entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">bookinfo</tag>, <tag dbk:condition="v4">articleinfo</tag>,
-<tag dbk:condition="v4">chapterinfo</tag>, <tag dbk:condition="nolink">*info</tag></entry>
-<entry><tag>info</tag></entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">authorblurb</tag></entry>
-<entry><tag>personblurb</tag></entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">collabname</tag>, <tag dbk:condition="v4">corpauthor</tag>,
-<tag dbk:condition="v4">corpcredit</tag>, <tag dbk:condition="v4">corpname</tag></entry>
-<entry><tag>orgname</tag></entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">isbn</tag>, <tag dbk:condition="v4">issn</tag>,
-<tag dbk:condition="v4">pubsnumber</tag></entry>
-<entry><tag>biblioid</tag></entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">lot</tag>, <tag dbk:condition="v4">lotentry</tag>, <tag dbk:condition="v4">tocback</tag>,
-<tag dbk:condition="v4">tocchap</tag>, <tag dbk:condition="v4">tocfront</tag>, <tag dbk:condition="v4">toclevel1</tag>,
-<tag dbk:condition="v4">toclevel2</tag>, <tag dbk:condition="v4">toclevel3</tag>, <tag dbk:condition="v4">toclevel4</tag>,
-<tag dbk:condition="v4">toclevel5</tag>, <tag dbk:condition="v4">tocpart</tag></entry>
-<entry><tag>tocdiv</tag></entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">graphic</tag>, <tag dbk:condition="v4">graphicco</tag>,
-<tag dbk:condition="v4">inlinegraphic</tag>, <tag dbk:condition="v4">mediaobjectco</tag></entry>
-<entry><tag>mediaobject</tag> and <tag>inlinemediaobject</tag></entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">ulink</tag></entry>
-<entry><tag>link</tag></entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">ackno</tag></entry>
-<entry><tag>acknowledgements</tag></entry>
-</row>
-</tbody>
-</tgroup>
-</table>
-
-</section>
-
-<section xml:id="changes-removed">
-<title>Removed elements</title>
-
-<para>The following elements were removed from DocBook V5.0 without
-direct replacements: <tag dbk:condition="v4">action</tag>, <tag
-dbk:condition="v4">beginpage</tag>, <tag dbk:condition="v4">highlights</tag>,
-<tag dbk:condition="v4">interface</tag>, <tag
-dbk:condition="v4">invpartnumber</tag>, <tag
-dbk:condition="v4">medialabel</tag>, <tag dbk:condition="v4">modespec</tag>,
-<tag dbk:condition="v4">structfield</tag>, <tag
-dbk:condition="v4">structname</tag>.
-If you use one or more of these elements, here are some suggestions
-as to how to re-code them in DocBook V5.0.
-</para>
-
-<table xml:id="t.removed">
-<title>Recommended mapping for removed elements</title>
-<tgroup dbk:cols="2">
-<thead>
-<row>
-<entry>Old name</entry>
-<entry>Recommended mapping</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><tag dbk:condition="v4">action</tag></entry>
-<entry>Use <computeroutput><<tag>phrase</tag> remap="action"></computeroutput>.</entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">beginpage</tag></entry>
-<entry>Remove: <tag dbk:condition="v4">beginpage</tag> is advisory only
-and has tended to cause confusion. A processing instruction or
-comment should be a workable replacement if one is needed.</entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">highlights</tag></entry>
-<entry>Use <tag>abstract</tag>. Note that because <tag
-dbk:condition="v4">highlights</tag> has a broader content model, you may
-need to wrap contents in a <tag>para</tag> inside
-<tag>abstract</tag>.</entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">interface</tag></entry>
-<entry>Use one of the <quote>gui*</quote> elements
-(<tag>guibutton</tag>, <tag>guiicon</tag>, <tag>guilabel</tag>,
-<tag>guimenu</tag>, <tag>guimenuitem</tag>, or
-<tag>guisubmenu</tag>).</entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">invpartnumber</tag></entry>
-<entry>Use <computeroutput><<tag>biblioid</tag> class="other"
-otherclass="medialabel"></computeroutput>. The
-<tag>productnumber</tag> element is another alternative.</entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">medialabel</tag></entry>
-<entry>Use <computeroutput><<tag>citetitle</tag>
-pubwork="<replaceable>mediatype</replaceable>"></computeroutput>,
-where <replaceable>mediatype</replaceable> is the type of media being
-labeled (e.g.,<tag dbk:class="attvalue">cdrom</tag> or <tag
-dbk:class="attvalue">dvd</tag>).</entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">modespec</tag></entry>
-<entry>No longer needed. The current processing model for
-<tag>olink</tag> renders <tag dbk:condition="v4">modespec</tag>
-unnecessary.</entry>
-</row>
-<row>
-<entry><tag dbk:condition="v4">structfield</tag>, <tag dbk:condition="v4">structname</tag></entry>
-<entry>Use <tag>varname</tag>. If you need to distinguish between the
-two, use <computeroutput><<tag>varname</tag>
-remap="<replaceable>structname or
-structfield</replaceable>"></computeroutput>. In some contexts, it
-may also be appropriate to use <tag>property</tag> for <tag
-dbk:condition="v4">structfield</tag>.</entry>
-</row>
-</tbody>
-</tgroup>
-</table>
-
-</section>
-
-</section>
-
-<section xml:id="convert4to5">
-<title>Converting DocBook V4.x documents to DocBook V5.0</title>
-
-<para>The DocBook V5.0 schema ships with an XSLT 1.0 stylesheet that
-is designed to transform valid DocBook V4.x documents to valid
-DocBook V5.0 documents.</para>
-
-<para>To convert your document, <filename>doc.xml</filename> in the
-examples below, follow these steps:</para>
-
-<procedure>
-<step>
-<para>Check the validity of your DocBook XML V4.x document. The
-conversion tool assumes that the input document is valid. If the input
-document contains markup errors, the results will be unpredictable at
-best.</para>
-</step>
-<step>
-<para>Transform <filename>doc.xml</filename> to
-<filename>newdoc.xml</filename> with the
-<filename>db4-upgrade.xsl</filename> stylesheet included in the
-DocBook V5.0 distribution that you are using.</para>
-</step>
-<step>
-<para>Check the validity of your DocBook XML V5.0 document against
-the DocBook V5.0 RELAX NG grammar.</para>
-</step>
-</procedure>
-
-<para>In the vast majority of cases, the resulting document should
-be valid and your conversion process is finished.</para>
-
-<para>If the document is not valid, please report the problem.
-(Over time, we'll have more experience with the sorts of things
-that can go wrong and we'll update this document to reflect that
-experience.)</para>
-
-<section xml:id="entities">
-<title>What About Entities?</title>
-
-<para>Using XSLT to transform existing documents to DocBook V5.0 has
-one potential disadvantage: it removes all entity references from
-your document.</para>
-
-<para>If preserving entities is an important aspect of your production
-work flow, you will have to engage in a semi-manual process to
-preserve them.</para>
-
-<procedure>
-<step>
-<para>Open your existing document using your favorite editing tool.
-You must use a tool that <emphasis>is not</emphasis> XML-aware, or one
-that allows you to edit markup “in the raw”.</para>
-</step>
-<step>
-<para>Replace all occurrences of the entity references that you want
-to preserve with some unique string. For example, if you want to preserve
-“<literal>&Product;</literal>” references, you could replace them
-all with “<literal>[[[Product]]]</literal>” (assuming that the string
-“<literal>[[[Product]]]</literal>” doesn't occur anywhere else in your document).</para>
-</step>
-<step>
-<para>Copy the document type declaration off of your document and save
-it some place. The document type declaration is everything from
-“<literal><!DOCTYPE</literal>” to the closing “<literal>]></literal>”.
-</para>
-</step>
-<step>
-<para>Perform the conversion described in <xref dbk:linkend="convert4to5"/>.
-</para>
-</step>
-<step>
-<para>Open the new document using your favorite editing tool. Replace
-all occurrences of the unique string you used to save the entity references
-with the corresponding entity references.</para>
-</step>
-<step>
-<para>Paste the document type declaration that you saved onto the top
-of your new document.</para>
-</step>
-<step>
-<para>Remove the external identifier (the <literal>PUBLIC</literal>
-and/or <literal>SYSTEM</literal> keywords) from the document type
-declaration. A document that begins:</para>
-<programlisting><![CDATA[<!DOCTYPE book [
-<!ENTITY someEntity "some replacement text">
-]>]]></programlisting>
-<para>is perfectly well-formed. If you don't remove the references to
-the DTD, then your parser will likely try to validate against DocBook
-V4.0 and that's not going to work. Alternatively, you could refer
-to the DocBook V5.0 DTD.</para>
-</step>
-</procedure>
-
-<tip>
-<para>Steps 2 and 5 from previous procedure can be automated using the
-<link xl:href="http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/contrib/tools/cloak">cloak
-script</link> written by Michael Smith.</para>
-</tip>
-
-<section xml:id="extparsedentities">
-<title>External Parsed Entities</title>
-
-<para>External parsed entities, entities which load part of a document
-from another file, are a special case. These can often be replaced
-with XInclude elements.</para>
-
-<para>The Perl script <filename>db4-entities.pl</filename>, also included
-in the DocBook V5.0 distribution attempts to perform this replacement
-for you. To use the script, perform the following steps:</para>
-
-<procedure>
-<step>
-<para>Process your document with <filename>db4-entities.pl</filename>.
-The script expects a single filename and prints the XInclude version
-on standard output.</para>
-</step>
-<step>
-<para>Process the XInclude version as described in <xref
-dbk:linkend="convert4to5"/>.
-</para>
-</step>
-</procedure>
-</section>
-</section>
-
-</section>
-
-<section xml:id="customizations">
- <title>Customizing DocBook V5.0</title>
- <!--
- ** RNG schema organization
- ** Removing attributes
- ** Adding new attributes
- ** Changing permitted content of attribute
- ** Removing elements
- ** Adding new elements
- ** Customizing content models
- ** Naming and versioning of DocBook customizations
- -->
-
- <para>
- It's much easier to customize DocBook V5.0 than it was to
- customize earlier releases. This is partly because RELAX NG
- provides better support for modifications than DTDs and partly
- because the DocBook schema is designed to take full advantage
- of the capabilities RELAX NG provides.
- This section describes the organization of the RELAX NG schema for
- DocBook, methods and examples for adding, removing, and modifying elements
- and attributes, and conventions for naming and versioning
- DocBook customizations.
- It assumes some familiarity with RELAX NG. If you are unfamiliar
- with RELAX NG, you can find a tutorial introduction in
- <citation>RNCTUT</citation>.
- </para>
- <section xml:id="relaxngorg">
- <title>DocBook RELAX NG schema organization</title>
- <para>
- The DocBook RELAX NG schema is highly modular, using named
- patterns extensively. Every element, attribute, attribute
- list, and enumeration has its own named pattern. In addition,
- there are named patterns for logical combinations of elements
- and attributes. These named patterns provide <quote>hooks</quote>
- into the schema that allow you to do a wide range of customization
- by simply redefining one or more of the named patterns.
- </para>
- <para>
- An important design characteristic of the schema is that
- duplication is minimized. This is done through the use of
- named patterns for common groupings that can be re-used.
- For example, the <tag>imagedata</tag> and <tag>videodata</tag>
- elements each have an <tag dbk:class="attribute">align</tag> attribute
- that takes the same set of enumerated values. Rather than
- repeating those values, a single pattern,
- <varname>db.halign.enumeration</varname> is referenced by
- the <varname>db.videodata.align.enumeration</varname>
- and <varname>db.imagedata.align.enumeration</varname> patterns,
- which are in turn referenced by the
- <varname>db.videodata.align.attribute</varname>
- and <varname>db.imagedata.align.attribute</varname> patterns.
- While this may seem like overkill, it allows a customizer to modify
- the allowed enumerations for these two attributes separately or together,
- or to completely re-define the allowed content of either or both,
- by redefining one or more of these named patterns.
- </para>
- <section xml:id="patternnames"><title>Pattern Names</title>
- <para>
- Because named patterns are used extensively, the RELAX NG schema uses
- several naming conventions. These are:
- <itemizedlist dbk:spacing="compact">
- <listitem>
- <para>
- Names have two or more parts, separated by dots <quote>.</quote>
- </para>
- </listitem>
- <listitem>
- <para>
- The first part of each name is the prefix <quote>db</quote>
- </para>
- </listitem>
- <listitem>
- <para>
- Each element has a named pattern in the form
- <varname>db.<replaceable>elementname</replaceable></varname>.
- Elements that have different content models in different
- contexts will also have patterns in the form
- <varname>db.<replaceable>context.elementname</replaceable></varname>. For example, <varname>db.figure.info</varname>
- defines the content model for the <tag>info</tag> element
- when it appears as a child of the <tag>figure</tag> element.
- <replaceable>Context</replaceable> may have several parts.
- For example, <varname>db.cals.entrytbl.thead</varname>.
- </para>
- </listitem>
- <listitem>
- <para>
- Most attributes have a named pattern in the form
- <varname>db.<replaceable>attributename</replaceable>.attribute</varname>.
- Attributes that have different content models in different
- contexts will also have patterns in the form
- <varname>db.<replaceable>context.attributename</replaceable>.attribute</varname>.
- For example,
- <varname>db.olink.localinfo.attribute</varname> defines the content
- model of the <tag dbk:class="attribute">localinfo</tag> attribute when
- it appears in <tag>olink</tag>.
- There are a few attributes that do not have individual named
- patterns. For example, the effectivity attributes are grouped
- into <varname>db.effectivity.attributes</varname> and not identified
- separately.
- </para>
- </listitem>
- <listitem>
- <para>
- Each element has a named pattern for its attribute list in
- the form
- <varname>db.<replaceable>elementname</replaceable>.attlist</varname>
-
- that defines the list of attributes for that element.
- Elements that have different attribute lists in different
- contexts will also have patterns in the form
- <varname>db.<replaceable>context.elementname</replaceable>.attlist</varname>
- For example, <varname>db.html.table.attlist</varname> defines
- the attribute list for the html <tag dbk:condition="nolink">table</tag> element and
- <varname>db.cals.table.attlist</varname> defines the attribute
- list for a cals <tag dbk:condition="nolink">table</tag> element.
- </para>
- </listitem>
- <listitem>
- <para>
- Each attribute that has enumerated values has a
- named pattern in the form
- <varname>db.<replaceable>[context.]attributename</replaceable>.enumeration</varname>.
- If the enumeration for a particular attribute depends on
- context, optional context is provided.
- For example,
- <varname>db.verbatim.continuation.enumeration</varname> defines
- the enumeration values for the
- <tag dbk:class="attribute">continuation</tag> attribute that is used
- in verbatim contexts like <tag>screen</tag>.
- Unlike elements and attributes, there is not necessarily a
- named pattern for enumerated attributes outside their context.
- For example, there is no <varname>db.class.enumeration</varname>
- because the <tag dbk:class="attribute">class</tag> attribute has
- a broad and non-intersecting range of uses.
- </para>
- </listitem>
- <listitem>
- <para>
- There are several different groupings of elements and attributes.
- Here are the major ones:
- <variablelist dbk:spacing="compact">
- <varlistentry>
- <term>inlines</term>
- <listitem>
- <para>
- Combinations of inline elements, for example,
- <varname>db.error.inlines</varname>, which contains
- <varname>db.errorcode</varname>,
- <varname>db.errortext</varname>, etc.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>blocks</term>
- <listitem>
- <para>
- Combinations of block elements, for example,
- <varname>db.verbatim.blocks</varname>, which contains
- <varname>db.programlisting</varname>,
- <varname>db.screen</varname>, etc.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>attributes</term>
- <listitem>
- <para>
- Combinations of attributes, for example,
- <varname>db.effectivity.attributes</varname>,
- which contains the attributes
- <tag dbk:class="attribute">arch</tag>,
- <tag dbk:class="attribute">condition</tag>,
- <tag dbk:class="attribute">conformance</tag>, etc.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>components</term>
- <listitem>
- <para>
- High level components of the schema, for example,
- <varname>db.navigation.components</varname>, which contains
- <varname>db.glossary</varname>,
- <varname>db.bibliography</varname>,
- <varname>db.index</varname>, and
- <varname>db.toc</varname>, and is used inside the
- content model for <tag>chapter</tag>, <tag>appendix</tag>,
- and <tag>preface</tag>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>contentmodel</term>
- <listitem>
- <para>
- Shared content models, for example,
- <varname>db.admonition.contentmodel</varname>, which contains
- the content model for <tag>tip</tag>, <tag>warning</tag>,
- <tag>note</tag>, etc.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- There are a couple of other groupings designed to minimize
- duplication, but these are the most important.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-</section>
-<section xml:id="customconsiderations">
- <title>General customization considerations</title>
- <para>
- Creating a customized schema is similar to
- creating a customization layer for XSL. The schema customization
- layer is a new RELAX NG schema that defines your changes and
- includes the standard docbook schema. You then validate using
- the schema customization as your schema.
- </para>
- <para>
- <xref dbk:linkend="ex-empty" dbk:xrefstyle="select: label"/> is an empty
- RELAX NG customization that does nothing
- except define the name spaces and include the standard DocBook schema.
- The <tag dbk:class="attribute">href</tag> attribute of the
- <tag dbk:condition="nolink">include</tag> element points to
- the location of the standard DocBook V5.0
- schema.<footnote><para>The examples in this section use
- <filename>docbook.rng</filename> as the schema location. If you want
- to create a portable schema customization you should use a standard
- web-accessible location like
- <uri>http://docbook.org/xml/&version;/rng/docbook.rng</uri> and
- then use <link
- xl:href="http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html">XML
- catalogs</link> to resolve this location to your local copy of the
- schema for improved performance. Unfortunately, at the time of
- this writing not all RELAX NG validators support XML catalogs.</para></footnote>
- All of the examples are given in both RNG and RNC form.
-<example xml:id="ex-empty"><title>Empty customization file</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng"/>
-
- <!-- redefinitions of named patterns -->
-
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc" inherit = db
-# redefinitions of named patterns]]></programlisting>
-</example>
- </para>
-</section>
- <section xml:id="cust-elements">
- <title>Elements</title>
- <section xml:id="cust-add-elements">
- <title>Adding elements</title>
- <para>
- Adding an element typically takes two definitions.
- The first defines the new element and
- its content model, and the second adds the
- new element into the schema. We'll show two examples.
- </para>
- <para>
- <xref dbk:linkend="ex-add-element-1" dbk:xrefstyle="select: label"/>
- adds a new element,
- <tag dbk:condition="nolink">person</tag>, with the same
- content model as <tag>author</tag>. The new element will be
- allowed to appear wherever <tag>author</tag> can appear.
- </para>
- <para>
- The <varname>db.author</varname> pattern is copied
- and renamed <varname>dbx.person</varname>, defining
- a new element called <tag dbk:condition="nolink">person</tag>.
- Then, the <varname>db.author</varname> pattern is redefined
- to be a choice of the current value or <varname>dbx.person</varname>.
- The <tag dbk:class="attribute">combine</tag> attribute tells
- RELAX NG to combine this pattern with the existing named
- pattern. In this case, the value
- of the <tag dbk:class="attribute">combine</tag> attribute is
- <quote>choice</quote>, which tells the parser that either
- the original pattern or this new pattern is a valid match.
- </para>
-<example xml:id="ex-add-element-1"><title>Adding a new element by duplicating an existing one</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng"/>
- <!-- define the new element -->
- <define name="dbx.person">
- <element name="person">
- <ref name="db.author.attlist"/>
- <ref name="db.credit.contentmodel"/>
- </element>
- </define>
- <!-- redefine the db.author pattern to allow db.person in
- the same places as db.author -->
- <define name="db.author" combine="choice">
- <ref name="dbx.person"/>
- </define>
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[default namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc"
-# define the new element
-dbx.person =
- element person { db.author.attlist, db.credit.contentmodel }
-# redefine the db.author pattern to allow db.person in
-# the same places as db.author
-db.author |= dbx.person]]></programlisting>
-</example>
- <para>
- The preceding method works well when you'd like a new element
- to be a clone or near-clone of an existing element. It gives
- you complete control over the content model, but
- only limited control over where the element is allowed. It
- works well when you want to allow the element in the same places
- as an existing element, and for this example that works
- nicely, since <tag>author</tag> is allowed in four different
- named patterns, each of which would have had to be redefined to
- allow <tag dbk:condition="nolink">person</tag>.
- But, if you can't find an existing element that is allowed in
- exactly the places you need, this method doesn't work as well.
- </para>
- <para>
- <xref dbk:linkend="ex-add-element-2" dbk:xrefstyle="select: label"/>
- adds two new elements by combining them into
- a higher level pattern. In this example, we'll add
- two new inline elements for writing about assembly language,
- <tag dbk:condition="nolink">register</tag> and
- <tag dbk:condition="nolink">instruction</tag>.
- We will allow them wherever programming inlines
- or operating system inlines are allowed.
- <xref dbk:linkend="ex-add-element-2" dbk:xrefstyle="select: label"/>
- defines the two elements, creates a new named pattern
- (<varname>dbx.asm.inlines</varname>) that contains them, and adds
- that pattern to <varname>db.programming.inlines</varname> and
- <varname>db.os.inlines</varname>. Since these two patterns
- don't have any elements in common, the strategy used in
- <xref dbk:linkend="ex-add-element-1" dbk:xrefstyle="select: label"/>
- would require selecting two different elements to <quote>clone</quote>,
- which would be messy.
- </para>
-<example xml:id="ex-add-element-2"><title>Adding new inline elements</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng"/>
- <!-- define the new elements -->
- <define name="dbx.register">
- <element name="register">
- <text/>
- </element>
- </define>
- <define name="dbx.instruction">
- <element name="instruction">
- <text/>
- </element>
- </define>
- <!-- create a new pattern that contains the new inlines -->
- <define name="dbx.asm.inlines">
- <choice>
- <ref name="dbx.register"/>
- <ref name="dbx.instruction"/>
- </choice>
- </define>
- <!-- add the new inlines to programming and os inlines -->
- <define name="db.programming.inlines" combine="choice">
- <ref name="dbx.asm.inlines"/>
- </define>
- <define name="db.os.inlines" combine="choice">
- <ref name="dbx.asm.inlines"/>
- </define>
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[default namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc"
-# define the new elements
-dbx.register = element register { text }
-dbx.instruction = element instruction { text }
-# create a new pattern that contains the new inlines
-dbx.asm.inlines = dbx.register | dbx.instruction
-# add the new inlines to programming and os inlines
-db.programming.inlines |= dbx.asm.inlines
-db.os.inlines |= dbx.asm.inlines]]></programlisting>
-</example>
- </section>
- <section xml:id="cust-delete-elements">
- <title>Deleting elements</title>
- <para>
- Deleting elements is straightforward, but takes some
- care and planning. <xref dbk:linkend="ex-delete-element"
- dbk:xrefstyle="select: label"/> deletes
- the <tag>important</tag> admonition element by redefining
- it with a content model of <varname>notAllowed</varname>.
- Note that in this example, the redefinition is inside
- the <tag dbk:condition="nolink">include</tag> element.
- This is required for
- redefinitions that completely replace an existing pattern.
- </para>
- <para>
- Be careful; If you delete an element that is a required part
- of another element's content model, you can make it
- impossible to create a valid document.
- For example, if you delete the <tag>title</tag>
- element, you won't be able to validate a <tag>book</tag>
- because a <tag>book</tag> requires a <tag>title</tag>.
- </para>
-<example xml:id="ex-delete-element"><title>Deleting an element</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng">
- <!-- redefine important element as notAllowed -->
- <define name="db.important">
- <notAllowed/>
- </define>
- </include>
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc" inherit = db {
- # redefine important element as notAllowed
- db.important = notAllowed
-}]]></programlisting>
-</example>
- </section>
- <section xml:id="cust-modify-elements">
- <title>Customizing the content model of existing elements</title>
- <para>
- <xref dbk:linkend="ex-modify-element" dbk:xrefstyle="select: label"/>
- expands the definition of <tag>author</tag> to include two
- new elements, <tag dbk:condition="nolink">born</tag> and
- <tag dbk:condition="nolink">died</tag>.
- The <tag>author</tag> element allows two content models,
- <varname>db.person.author.contentmodel</varname>, which
- defines an author who is a person, and
- <varname>db.org.author.contentmodel</varname>, which
- defines an author that is an organization. We will modify
- <varname>db.person.author.contentmodel</varname> so that
- only authors who are persons can have the new elements.
-<example xml:id="ex-modify-element"><title>Modifying the content model of an element</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng"/>
-
- <define name="db.person.author.contentmodel" combine="interleave">
- <interleave>
- <optional>
- <element name="born">
- <ref name="db.date.contentmodel"/>
- </element>
- </optional>
- <optional>
- <element name="died">
- <ref name="db.date.contentmodel"/>
- </element>
- </optional>
- </interleave>
- </define>
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[default namespace = "http://docbook.org/ns/docbook"
-namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc"
-
-db.person.author.contentmodel &=
- element born { db.date.contentmodel }?
- & element died { db.date.contentmodel }?]]></programlisting>
-</example>
- </para>
- <para>
- This modification will allow instances like this:
-<programlisting><![CDATA[<author>
- <personname>Babe Ruth</personname>
- <born>02/06/1895</born>
- <died>08/16/1948</died>
-</author>]]></programlisting>
-but because we only modified the content model for authors
-who are human, it won't allow an instance like this, which
-uses <varname>db.org.author.contentmodel</varname>:
-<programlisting><![CDATA[<!-- INVALID -->
-<author>
- <orgname>Boston Red Sox</orgname>
- <died>1919</died>
- <born>2004</born>
-</author>]]></programlisting>
- </para>
- </section>
- </section>
- <section xml:id="cust-attributes">
- <title>Attributes</title>
- <section xml:id="cust-add-attributes">
- <title>Adding attributes</title>
- <para>
- The simplest way to add an attribute to a single element
- is to add it to the attlist pattern for that element.
- <xref dbk:linkend="ex-add-attr" dbk:xrefstyle="select: label"/>
- adds the optional attributes <tag dbk:class="attribute">born</tag>
- and <tag dbk:class="attribute">died</tag> to the attribute
- list for <tag>author</tag>.
- The <varname>db.author.attlist</varname>
- named pattern is redefined with the
- <tag dbk:class="attribute">combine</tag> attribute set to
- <quote>interleave</quote>, which interleaves the two new
- optional attributes with the existing attributes on the list.
- </para>
-<example xml:id="ex-add-attr"><title>Adding attributes</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng"/>
-
- <define name="db.author.attlist" combine="interleave">
- <interleave>
- <optional>
- <attribute name="born">
- <ref name="db.date.contentmodel"/>
- </attribute>
- </optional>
- <optional>
- <attribute name="died">
- <ref name="db.date.contentmodel"/>
- </attribute>
- </optional>
- </interleave>
- </define>
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc" inherit = db
-
-db.author.attlist &=
- attribute born { db.date.contentmodel }?
- & attribute died { db.date.contentmodel }?]]></programlisting>
-</example>
- <para>
- Unlike
- <xref dbk:linkend="ex-modify-element" dbk:xrefstyle="select: label"/>,
- <xref dbk:linkend="ex-add-attr" dbk:xrefstyle="select: label"/> allows
- the new attributes to appear on any <tag>author</tag>
- element, not just those using the person content model.
- </para>
- <para>
- <xref dbk:linkend="ex-add-attr-2" dbk:xrefstyle="select: label"/> shows
- how you could limit the use of these attributes to authors who
- are persons. In this example, the new attributes are interleaved
- with the <varname>db.person.author.contentmodel</varname>.
- The only difference between this example and
- <xref dbk:linkend="ex-modify-element" dbk:xrefstyle="select: label"/> is
- that the added patterns are identified as attributes rather than
- elements. This shows some of the flexibility of RELAX NG, which
- treats attributes and elements very consistently.
-<example xml:id="ex-add-attr-2"><title>Adding attributes; alternate method</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng"/>
- <!-- redefinitions of named patterns -->
- <define name="db.person.author.contentmodel" combine="interleave">
- <interleave>
- <optional>
- <attribute name="born">
- <ref name="db.date.contentmodel"/>
- </attribute>
- </optional>
- <optional>
- <attribute name="died">
- <ref name="db.date.contentmodel"/>
- </attribute>
- </optional>
- </interleave>
- </define>
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc" inherit = db
-# redefinitions of named patterns
-db.person.author.contentmodel &=
- attribute born { db.date.contentmodel }?
- & attribute died { db.date.contentmodel }?]]></programlisting>
-</example>
-There is one difference in the treatment of attributes and elements
-that is worth noting. By the XML 1.0 definition, the relative order
-of attributes is not significant. Therefore, the
-<tag dbk:condition="nolink">interleave</tag> block is not required for
-attributes, though it does no harm.
- </para>
- </section>
- <section xml:id="cust-delete-attributes">
- <title>Deleting attributes</title>
- <para>
- Deleting an attribute is similar to deleting an element,
- except that you use the RELAX NG <varname>empty</varname>
- pattern rather than <varname>notAllowed</varname>.
- <xref dbk:linkend="ex-delete-attr" dbk:xrefstyle="select: label"/>
- deletes the linking attributes, which are collected in the
- <varname>db.common.linking.attributes</varname> pattern,
- by defining that pattern as <varname>empty</varname>.
- </para>
-<example xml:id="ex-delete-attr"><title>Deleting an attribute</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng">
- <define name="db.common.linking.attributes">
- <empty/>
- </define>
- </include>
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc" inherit = db {
- db.common.linking.attributes = empty
-}]]></programlisting>
-</example>
- <para>
- Generally, <varname>empty</varname> is used when deleting
- attributes and <varname>notAllowed</varname> is used when
- deleting elements.
- </para>
- </section>
- <section xml:id="cust-modify-attributes">
- <title>Changing permitted content of attributes</title>
- <para>
- <xref dbk:linkend="ex-modify-attr" dbk:xrefstyle="select: label"/>
- modifies <varname>db.spacing.enumeration</varname> to
- add the additional value <quote>large</quote>. Note
- that to remove a value from an enumeration, you need
- to redefine the entire enumeration, minus the values
- you don't need.
- </para>
-<example xml:id="ex-modify-attr"><title>Deleting an attribute</title>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns:db="http://docbook.org/ns/docbook"
- ns="http://docbook.org/ns/docbook"
- xmlns="http://relaxng.org/ns/structure/1.0">
- <include href="docbook.rng"/>
- <!-- add value to an enumeration -->
- <define name="db.spacing.enumeration" combine="choice">
- <value>large</value>
- </define>
-</grammar>]]></programlisting>
-<programlisting dbk:language="rnc"><![CDATA[namespace db = "http://docbook.org/ns/docbook"
-
-include "docbook.rnc" inherit = db
-# add value to an enumeration
-db.spacing.enumeration |= "large"]]></programlisting>
-</example>
- </section>
- </section>
-
-<section xml:id="cust-naming">
-<title>Naming and versioning DocBook customizations</title>
-
-<para>DocBook V5.0 is not tightly coupled with some particular
-validation technology like DTDs. This also means that DocBook V5.0
-documents don't have to (and usually don't) start with a
-document type declaration (<!DOCTYPE…>) to specify the schema
-(DTD) to use. Instead, DocBook V5.0 instances can be easily
-distinguished from other XML vocabularies by using elements in the
-<uri>http://docbook.org/ns/docbook</uri> namespace. This namespace is
-enough to distinguish DocBook from other XML based formats. But the
-DocBook schema evolves over time and there are several versions of
-DocBook (e.g. 3.1, 4.2, 4.5 and 5.0). Since DocBook version 5.0, the
-actual version used is indicated in the <tag
-dbk:class="attribute">version</tag> attribute on a root element.</para>
-
-<programlisting><![CDATA[<book xmlns="http://docbook.org/ns/docbook"
- version="5.0">
- …
-</book>]]></programlisting>
-
-<para>Future versions of DocBook documents will start with the same
-markup, except the version number will be raised, for example to 5.1
-or 6.0.
-The namespace will remain the same until the semantics of the elements
-change in a backward incompatible way, which is very unlikely to happen.</para>
-
-<para>If you create a DocBook schema customization you must change the <tag
-dbk:class="attribute">version</tag> attribute to distinguish your
-customization from the <quote>official</quote> DocBook. Changing the
-namespace is not recommended because that would break the processing
-tools. Remember that changing namespaces is the same as renaming all
-elements in the namespace.</para>
-
-<para>When you customize the schema, use the following syntax to
-identify your DocBook derivation:</para>
-
-<programlisting><replaceable>base_version</replaceable>-[subset|extension|variant] [<replaceable>name</replaceable>[-<replaceable>version</replaceable>]?]+</programlisting>
-
-<para>For example:</para>
-
-<programlisting>5.0-subset simplified-1.0
-5.0-variant ASMBook
-5.0-variant ASMBook-2006
-5.0-extension MathML-2.0 SVG-1.1</programlisting>
-
-<para>The first part of the version identifier is the version number of the
-DocBook schema from which you derived your customization.</para>
-
-<para>If your schema is a proper subset, you can advertise this status
-by using the <literal>subset</literal> keyword in the description. If
-your schema contains any markup model extensions, you can advertise
-this status by using the <literal>extension</literal> keyword. If
-you'd rather not characterize your variant specifically as a subset or
-an extension, use the <literal>variant</literal> keyword.</para>
-
-<para>After these keywords you may add a whitespace separated list of
-customization identifiers. Each name may be optionally followed by its
-version number.</para>
-
-</section>
-
-</section>
-
-<section xml:id="faq">
-<title>FAQ</title>
-
-<qandaset>
-<qandadiv>
-<title>Authoring</title>
-
-<qandaentry xml:id="faq-authoring-schema-association">
-<question>
-<para>How do I attach a schema to a DocBook V5.0 document when I do not
-want to use DTDs and !DOCTYPE?</para>
-</question>
-<answer>
-<para>There is no standard way of associating a RELAX NG schema with a
-document. Most tools provide some mechanism for performing this
-association, consult the documentation for your application. In some
-tools you must specify schema manually each time you want to
-edit/process your document.</para>
-</answer>
-</qandaentry>
-
-<qandaentry xml:id="faq-authoring-general-entities">
-<question>
-<para>How do I use entities like <tag dbk:class="genentity">ndash</tag> in
-DocBook V5.0?</para>
-</question>
-<answer>
-<para>Modern schema languages (including RELAX NG and W3X XML Schema)
-do not provide any means to define entities that can be used for easier
-typing of special characters. Some editors provide functions or
-special toolbars that allow you to easily pick necessary character
-and insert it into document as a raw Unicode character or a numeric
-character reference.</para>
-<para>Another possibility is to include entity definitions in the
-prolog of your document. <link
-xl:href="http://www.w3.org/2003/entities/">Entity definition
-files</link> are now maintained by W3C. You can reference definition
-files with entity definitions you are interested in and then reference
-imported entities. For example:</para>
-<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE article [
-<!ENTITY % isopub SYSTEM "http://www.w3.org/2003/entities/iso8879/isopub.ent">
-%isopub;
-]>
-<article xmlns="http://docbook.org/ns/docbook" version="5.0">
-<title>DocBook V5.0 – the superb documentation format</title>]]>
-…</programlisting>
-<para>For your convenience there is also flattened entity definition
-file which contains all entity definitions.</para>
-<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE article [
-<!ENTITY % allent SYSTEM "http://www.w3.org/2003/entities/2007/w3centities-f.ent">
-%allent;
-]>
-<article xmlns="http://docbook.org/ns/docbook" version="5.0">
-<title>DocBook V5.0 – the superb documentation format</title>]]>
-…</programlisting>
-</answer>
-</qandaentry>
-
-<qandaentry xml:id="faq-authoring-modularization">
-<question>
-<para>How to modularize documents?</para>
-</question>
-<answer>
-<para>You can use <link
-xl:href="http://www.w3.org/TR/xinclude/">XInclude</link> for this
-task. There is an alternative schema for DocBook V5.0 that
-contains XInclude elements. This is necessary to make some XML editors
-happy. This schema can be found in files that end with letters <quote>xi</quote>, e.g.
-<filename>docbookxi.rnc</filename> instead of
-<filename>docbook.rnc</filename>.</para>
-</answer>
-</qandaentry>
-
-<qandaentry xml:id="faq-authoring-validating-xincludes">
-<question>
-<para>How to validate documents which are composed by XInclude?</para>
-</question>
-<answer>
-<para>If you are using XIncludes you should make sure that the final
-document after resolving all inclusions is valid DocBook V5.0
-instance. This means that all XIncludes should be processed before
-validation takes place. The following command can be used to enable
-XInclude processing in oNVDL.</para>
-<screen><command>java</command> -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration -jar <replaceable>/path/to/oNVDL/</replaceable>bin/onvdl.jar <replaceable>/path/to/</replaceable>docbook.nvdl document.xml</screen>
-<para>For JNVDL you can use switch <option>-xi</option> to enable XInclude processing.</para>
-</answer>
-</qandaentry>
-
-</qandadiv>
-
-<qandadiv>
-<title>Stylesheets</title>
-
-<qandaentry xml:id="faq-stylesheets-future">
-<question>
-<para>Will the current DocBook XSL stylesheets (XSLT 1.0 based
-implementation) be maintained and improved in the future since work on
-a new XSLT 2.0 based implementation has started?</para>
-</question>
-<answer>
-<para>Yes, the current stylesheets (like 1.73.x) will be supported and
-improved further because they are very widely deployed and work with
-many existing XSLT processors.</para>
-<para>Surely there will be a point in a future when all new development
-will be switched to the XSLT 2.0 based implementation. But this
-will not happen until all features of the current stylesheets are
-implemented in the new stylesheets, and until there is more than
-one usable XSLT 2.0 processor available.</para>
-</answer>
-</qandaentry>
-
-</qandadiv>
-
-<qandadiv>
-<title>Schema customizations</title>
-
-<qandaentry xml:id="faq-customization-mathml">
-<question>
-<para>How can I extend the DocBook schema with MathML elements?</para>
-</question>
-<answer>
-<para>The basic DocBook schema allows elements from the MathML namespace
-to appear inside the <tag>equation</tag> element. This means that you can
-validate a DocBook+MathML document, but MathML content will be ignored
-during the validation. You will also not be able to use guided editing
-for the MathML content.</para>
-<para>If you need strict validation of MathML content or guided
-editing for MathML, you can easily extend the base DocBook schema with
-the MathML schema.</para>
-<procedure>
-<title>Extending the DocBook schema with the MathML schema</title>
-<step>
-<para>Download the MathML RELAX NG schema from <link
-xl:href="http://yupotan.sppd.ne.jp/relax-ng/mml2.html"/> and unpack it
-somewhere (e.g. into a <filename>mathml</filename> subdirectory).</para>
-</step>
-<step>
-<para>Create a schema customization in compact syntax—<filename>dbmathml.rnc</filename>:</para>
-<programlisting dbk:language="rnc">namespace html = "http://www.w3.org/1999/xhtml"
-namespace mml = "http://www.w3.org/1998/Math/MathML"
-namespace db = "http://docbook.org/ns/docbook"
-
-include "/path/to/docbook.rnc" {
- db._any.mml = external "mathml/mathml2.rnc"
- db._any =
- element * - (db:* | html:* | mml:*) {
- (attribute * { text }
- | text
- | db._any)*
- }
-}</programlisting>
-<para>Or, alternatively, you can use the XML syntax of RELAX NG—<filename>dbmathml.rng</filename>:</para>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns="http://relaxng.org/ns/structure/1.0">
-
-<include href="/path/to/docbook.rng">
- <define name="db._any.mml">
- <externalRef href="mathml/mathml2.rng"/>
- </define>
-
- <define name="db._any">
- <element>
- <anyName>
- <except>
- <nsName ns="http://docbook.org/ns/docbook"/>
- <nsName ns="http://www.w3.org/1999/xhtml"/>
- <nsName ns="http://www.w3.org/1998/Math/MathML"/>
- </except>
- </anyName>
- <zeroOrMore>
- <choice>
- <attribute>
- <anyName/>
- </attribute>
- <text/>
- <ref name="db._any"/>
- </choice>
- </zeroOrMore>
- </element>
- </define>
-</include>
-
-</grammar>]]></programlisting>
-</step>
-<step>
-<para>Now use the customized schema (<filename>dbmathml.rnc</filename>
-or <filename>dbmathml.rng</filename>) instead of the original
-DocBook schema.</para>
-</step>
-</procedure>
-</answer>
-</qandaentry>
-
-<qandaentry xml:id="faq-customization-svg">
-<question>
-<para>How can I extend the DocBook schema with SVG elements?</para>
-</question>
-<answer>
-<para>The situation is the same as with MathML support. You can use
-elements from the SVG namespace inside the <tag>imageobject</tag>
-element.</para>
-<procedure>
-<title>Extending the DocBook schema with the SVG schema</title>
-<step>
-<para>Download the SVG RELAX NG schema from <link
-xl:href="http://www.w3.org/Graphics/SVG/1.1/rng/rng.zip"/> and unpack it
-somewhere (e.g. into an <filename>svg</filename> subdirectory).</para>
-</step>
-<step>
-<para>Create a schema customization in compact syntax—<filename>dbsvg.rnc</filename>:</para>
-<programlisting dbk:language="rnc">namespace html = "http://www.w3.org/1999/xhtml"
-namespace db = "http://docbook.org/ns/docbook"
-namespace svg = "http://www.w3.org/2000/svg"
-
-include "/path/to/docbook.rnc" {
- db._any.svg = external "svg/svg11.rnc"
- db._any =
- element * - (db:* | html:* | svg:*) {
- (attribute * { text }
- | text
- | db._any)*
- }
-}</programlisting>
-<para>Or, alternatively, you can use the XML syntax of RELAX NG—<filename>dbsvg.rng</filename>:</para>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns="http://relaxng.org/ns/structure/1.0">
-
-<include href="/path/to/docbook.rng">
- <define name="db._any.svg">
- <externalRef href="svg/svg11.rng"/>
- </define>
-
- <define name="db._any">
- <element>
- <anyName>
- <except>
- <nsName ns="http://docbook.org/ns/docbook"/>
- <nsName ns="http://www.w3.org/1999/xhtml"/>
- <nsName ns="http://www.w3.org/2000/svg"/>
- </except>
- </anyName>
- <zeroOrMore>
- <choice>
- <attribute>
- <anyName/>
- </attribute>
- <text/>
- <ref name="db._any"/>
- </choice>
- </zeroOrMore>
- </element>
- </define>
-</include>
-
-</grammar>]]></programlisting>
-</step>
-<step>
-<para>Now use the customized schema (<filename>dbsvg.rnc</filename>
-or <filename>dbsvg.rng</filename>) instead of the original
-DocBook schema.</para>
-</step>
-</procedure>
-</answer>
-</qandaentry>
-
-<qandaentry xml:id="faq-customization-mathml-svg">
-<question>
-<para>Is it possible to use the previous two customizations for MathML
-and SVG together?</para>
-</question>
-<answer>
-<para>Yes, you can create a special schema customization that combines
-both MathML and SVG with the DocBook schema. In compact syntax, the merged
-schema is:</para>
-<programlisting dbk:language="rnc">namespace html = "http://www.w3.org/1999/xhtml"
-namespace mml = "http://www.w3.org/1998/Math/MathML"
-namespace db = "http://docbook.org/ns/docbook"
-namespace svg = "http://www.w3.org/2000/svg"
-
-include "/path/to/docbook.rnc" {
- db._any.mml = external "mahtml/mathml2.rnc"
- db._any.svg = external "svg/svg11.rnc"
- db._any =
- element * - (db:* | html:* | mml:* | svg:*) {
- (attribute * { text }
- | text
- | db._any)*
- }
-}</programlisting>
-<para>Or alternatively in the full RELAX NG syntax:</para>
-<programlisting dbk:language="rng"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns="http://relaxng.org/ns/structure/1.0">
-
-<include href="/path/to/docbook.rng">
- <define name="db._any.mml">
- <externalRef href="mathml/mathml2.rng"/>
- </define>
-
- <define name="db._any.svg">
- <externalRef href="svg/svg11.rng"/>
- </define>
-
- <define name="db._any">
- <element>
- <anyName>
- <except>
- <nsName ns="http://docbook.org/ns/docbook"/>
- <nsName ns="http://www.w3.org/1999/xhtml"/>
- <nsName ns="http://www.w3.org/1998/Math/MathML"/>
- <nsName ns="http://www.w3.org/2000/svg"/>
- </except>
- </anyName>
- <zeroOrMore>
- <choice>
- <attribute>
- <anyName/>
- </attribute>
- <text/>
- <ref name="db._any"/>
- </choice>
- </zeroOrMore>
- </element>
- </define>
-</include>
-
-</grammar>]]></programlisting>
-</answer>
-</qandaentry>
-
-<qandaentry xml:id="faq-customization-links">
-<question>
-<para>Are there any other examples of schema customization
-available?</para>
-</question>
-<answer>
-<para>Sure. Some of the are listed bellow:</para>
-<itemizedlist>
-<listitem><para><link
-xl:href="http://www.w3.org/TR/xml-i18n-bp/#docbook-plus-its">Sample
-customization of ITS and DocBook</link></para></listitem>
-<listitem><para><link
-xl:href="http://wiki.docbook.org/topic/DocbookSchemas">Examples on
-DocBook WiKi</link></para></listitem>
-</itemizedlist>
-</answer>
-</qandaentry>
-
-</qandadiv>
-
-<qandadiv>
-<title>Tool specific problems</title>
-
-<qandaentry xml:id="faq-tools-xmlspy-xmlid">
-<question>
-<para>I'm using Altova XMLSpy to validate DocBook V5.0 instances
-against the W3C XML Schema (<filename>docbook.xsd</filename>). XMLSpy
-complains about undefined <tag dbk:class="attribute">xml:id</tag>
-attributes?</para>
-</question>
-<answer>
-<para>XMLSpy always uses its own bundled version of
-<filename>xml.xsd</filename> which unfortunately doesn't define the <tag
-dbk:class="attribute">xml:id</tag> attribute. The bundled version of
-<filename>xml.xsd</filename> is hardwired into the program and cannot
-be replaced by a newer version. To solve this problem you must upgrade
-to version 2006 SP1.</para>
-</answer>
-</qandaentry>
-
-</qandadiv>
-
-</qandaset>
-</section>
-
-<bibliography xml:id="references">
-
-<bibliomixed>
-<abbrev>RNCTUT</abbrev>
-Clark, James – Cowan, John – MURATA, Makoto: <title>RELAX NG Compact Syntax Tutorial</title>.
-Working Draft, 26 March 2003. OASIS. <bibliomisc><link xl:href="http://relaxng.org/compact-tutorial-20030326.html"/></bibliomisc>
-</bibliomixed>
-
-<bibliomixed>
-<abbrev>NVDLTUT</abbrev>
-Nálevka, Petr:
-<title>NVDL Tutorial</title>.
-<bibliomisc><link xl:href="http://jnvdl.sourceforge.net/tutorial.html"/></bibliomisc>
-</bibliomixed>
-
-<bibliomixed>
-<abbrev>XMLID</abbrev>
-Marsh, Jonathan –
-Veillard, Daniel –
-Walsh, Norman: <title>xml:id Version 1.0</title>. W3C Recommendation, 9 September 2005. <bibliomisc><link xl:href="http://www.w3.org/TR/xml-id/"/></bibliomisc>
-</bibliomixed>
-
-<bibliomixed>
-<abbrev>DB5SPEC</abbrev>
-Norman, Walsh: <title>The DocBook Schema</title>.
-Working Draft 5.0a1, OASIS, 29 June 2005.
-<bibliomisc><link xl:href="http://www.docbook.org/specs/wd-docbook-docbook-5.0a1.html"/></bibliomisc>
-</bibliomixed>
-
-</bibliography>
-</article>
-</book>
projects / lgpl / argeo-commons.git / blobdiff