1 <?xml version=
"1.0" encoding=
"utf-8"?> <!-- -*- nxml -*- -->
3 <!ENTITY version
"5.0">
5 <!ENTITY yes "<phrase dbk:role='unicode yes'>✔</phrase>">
6 <!ENTITY no "<phrase dbk:role='unicode no'>✘</phrase>">
8 <!ENTITY yes
"<phrase dbk:role='unicode yes'>YES</phrase>">
9 <!ENTITY no
"<phrase dbk:role='unicode no'>NO</phrase>">
11 <book xmlns=
"http://docbook.org/ns/docbook" xmlns:
dbk=
"http://docbook.org/ns/docbook"
12 xmlns:
xl=
"http://www.w3.org/1999/xlink" xml:
lang=
"en">
15 <title>DocBook V5.0
</title>
16 <subtitle>The Transition Guide
</subtitle>
19 <author><personname>Jirka Kosek
</personname>
20 <email>jirka@kosek.cz
</email></author>
21 <author><personname>Norman Walsh
</personname>
22 <email>ndw@nwalsh.com
</email>
23 <contrib>§convert4to5, proofreading
</contrib></author>
24 <author><personname>Dick Hamilton
</personname>
25 <email>rlhamilton@frii.com
</email>
26 <contrib>§changes-removed, customization, proofreading
</contrib></author>
29 dbk:
otherclass=
"contributor"
30 ><personname>Michael(tm) Smith
</personname>
31 <email>smith@sideshowbarker.net
</email>
32 <contrib>§dbxsl-ns
</contrib>
36 <pubdate>2009-
06-
16</pubdate>
37 <pubdate>2008-
02-
06</pubdate>
38 <pubdate>2007-
10-
28</pubdate>
39 <pubdate>2006-
10-
22</pubdate>
40 <pubdate>2006-
05-
16</pubdate>
41 <pubdate>2006-
03-
01</pubdate>
42 <pubdate>2005-
12-
28</pubdate>
43 <pubdate>2005-
10-
27</pubdate>
47 <para>This document is targeted at DocBook users who are considering
48 switching from DocBook V4.x to DocBook V5.0. It describes
49 differences between DocBook V4.x and V5.0 and provides some suggestions about
50 how to edit and process DocBook V5.0 documents. There is
51 also a section devoted to conversion of legacy documents from DocBook
52 4.x to DocBook V5.0.
</para>
54 <para>At the time this was written the current version of DocBook V5.0
55 was
&version;. However, almost all of the information in this document is
56 general and applies to any newer version of DocBook V5.0.
59 <section xml:
id=
"introduction">
60 <title>Introduction
</title>
62 <para>The differences between DocBook V4.x and V5.0 are quite radical in
63 some aspects, but the basic idea behind DocBook is still the same, and
64 almost all element names are unchanged. Because of this it is very
65 easy to become familiar with DocBook V5.0 if you know any previous version of
66 DocBook. You can find a complete list of changes in
67 <citation>DB5SPEC
</citation>, here we will discuss only the most
68 fundamental changes.
</para>
70 <section xml:
id=
"introduction-ns">
71 <title>Finally in a namespace
</title>
73 <para>All DocBook V5.0 elements are in the namespace
74 <uri>http://docbook.org/ns/docbook
</uri>.
<acronym>XML
<alt>Extensible
75 Markup Language
</alt></acronym> namespaces are used to distinguish
76 between different element sets. In the last few years, almost all new
77 XML grammars have used their own namespace. It is easy to
78 create compound documents that contain elements from different XML
79 vocabularies. DocBook V5.0 is following this design rule. Using
80 namespaces in your documents is very easy. Consider this
81 simple article marked up in DocBook V4.5:
</para>
83 <programlisting><![CDATA[
<article>
84 <title>Sample article
</title>
85 <para>This is a really short article.
</para>
86 </article>]]
></programlisting>
88 <para>The corresponding DocBook V5.0 article will look very similar:
</para>
90 <programlisting><![CDATA[
<article xmlns=
"http://docbook.org/ns/docbook" …
>
91 <title>Sample article
</title>
92 <para>This is a really short article.
</para>
93 </article>]]
></programlisting>
95 <para>The only change is the addition of a default namespace declaration
96 (
<code>xmlns=
"http://docbook.org/ns/docbook"</code>) on the root
97 element. This declaration applies the namespace to the root element and
98 all nested elements. Each
99 element is now uniquely identified by its local name and namespace.
</para>
102 <para>The namespace name
<uri>http://docbook.org/ns/docbook
</uri> serves
103 only as an identifier. This resource is not fetched during processing
104 of DocBook documents, and you are not required to have an Internet
105 connection during processing. If you access the namespace URI with a browser,
106 you will find a short explanatory document about the namespace. In the
107 future this document will probably conform to (some version of) RDDL
108 and provide pointers to related resources.
</para>
113 <section xml:
id=
"introduction-rng">
114 <title>Relaxing with DocBook
</title>
116 <para>For more than a decade, the DocBook schema was defined using a
117 DTD. However, DTDs have serious limitations, and DocBook V5.0 is thus
118 defined using a very powerful schema language called RELAX NG. Thanks
119 to RELAX NG, it is now much easier to create customized versions of
120 DocBook, and some content models are now cleaner and more
123 <para>Using RELAX NG has an impact on the document prolog. The following
124 example shows the typical prolog of a DocBook V4.x document. The version of
125 the DocBook DTD (in this case
4.5) is indicated in the document type
126 declaration (!DOCTYPE) which points to a particular version of the
129 <example xml:
id=
"ex.docbook45">
130 <title>DocBook V4.5 document
</title>
131 <programlisting><![CDATA[
<?xml version=
"1.0" encoding=
"utf-8"?>
132 <!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
133 'http://www.oasis-open.org/docbook/xml/
4.5/docbookx.dtd'
>
135 <title>Sample article
</title>
136 <para>This is a very short article.
</para>
137 </article>]]
></programlisting>
140 <para>In contrast, DocBook V5.0 does not depend on DTDs anymore. This
141 mean that there is no document type declaration and the version of DocBook
142 used is indicated with the
<tag dbk:
class=
"attribute">version
</tag>
143 attribute instead.
</para>
145 <example xml:
id=
"ex.docbook5">
146 <title>DocBook V5.0 document
</title>
147 <programlisting><![CDATA[
<?xml version=
"1.0" encoding=
"utf-8"?>
148 <article xmlns=
"http://docbook.org/ns/docbook" version=
"5.0" xml:
lang=
"en">
149 <title>Sample article
</title>
150 <para>This is a very short article.
</para>
151 </article>]]
></programlisting>
154 <para>As you can see, DocBook V5.0 is built on top of existing XML
155 standards as much as possible, for example the
<tag
156 dbk:
class=
"attribute">lang
</tag> attribute is superseded by the standard
157 <tag xl:
href=
"http://www.w3.org/TR/REC-xml/#sec-lang-tag"
158 dbk:
class=
"attribute">xml:lang
</tag> attribute.
</para>
160 <para>Another fundamental change is that there is no direct indication
161 of the schema used. Later in this document, you will learn how you can
162 specify a schema to be used for document validation.
</para>
165 <para>Although we recommend the RELAX NG schema for DocBook
166 V5.0, there are also DTD and W3C XML Schema versions available (see
<xref
167 dbk:
linkend=
"schemas"/>) for tools that do not yet support RELAX NG.
</para>
172 <section xml:
id=
"introduction-why-to-switch">
173 <title>Why switch to DocBook V5.0?
</title>
175 <para>The simple answer is
<quote>because DocBook V5.0 is the
176 future
</quote>. Apart from this marketing blurb, there are also more
177 technical reasons:
</para>
181 <para><emphasis>DocBook V4.x is feature frozen.
</emphasis>DocBook V4.5
182 is the last version of DocBook in the V4.x series. Any new DocBook
183 development, like the addition of new elements, will be done in
184 DocBook V5.0. It is only matter of time before useful, new elements
185 will be added into DocBook V5.0, but they are not likely to be back
186 ported into DocBook V4.x. DocBook V4.x will be in maintenance mode and
187 errata will be published if necessary.
</para>
190 <para><emphasis>DocBook V5.0 offers new functionality.
</emphasis>
191 DocBook V5.0 provides significant improvements over DocBook V4.x. For
192 example there is general markup for annotations, a new and flexible
193 system for linking, and unified markup for information sections using
194 the
<tag>info
</tag> element.
</para>
197 <para><emphasis>DocBook V5.0 is more extensible.
</emphasis> Having
198 DocBook V5.0 in a separate namespace allows you to easily mix DocBook
199 markup with other XML-based languages like SVG, MathML, XHTML or even
203 <para><emphasis>DocBook V5.0 is easier to customize.
</emphasis> RELAX
204 NG offers many powerful constructs that make customization much easier
205 than it would be using a DTD (see
<xref dbk:
linkend=
"customizations"/>).
</para>
211 <section xml:
id=
"introduction-schemas">
212 <title>Schema jungle
</title>
214 <para>Schemas for DocBook V5.0 are available in several formats at
215 <link xl:
href=
"http://www.oasis-open.org/docbook/xml/&version;/"/> (or the
216 mirror at
<link xl:
href=
"http://docbook.org/xml/&version;/"/>).
217 Only the RELAX NG schema is normative
218 and it is preferred over the other schema languages. However, for your
219 convenience there are also DTD and W3C XML Schema versions provided for DocBook
220 V5.0. But please note that neither the DTD nor the W3C XML schema are able to
221 capture all the constraints of DocBook V5.0. This mean that a
222 document that validates against the DTD or XML schema is not necessarily
223 valid against the RELAX NG schema and thus may not be a valid
224 DocBook V5.0 document. See
<xref dbk:
linkend=
"t.schema-comparison"/> for
225 summary of constraints that are checked by different schemas.
</para>
227 <para>DTD and W3C XML Schema versions of the DocBook V5.0 grammar are provided
228 as a convenience for users who want to use DocBook V5.0 with legacy tools
229 that don't support RELAX NG. Authors are encouraged to switch to RELAX
230 NG based tools as soon as possible, or at least to validate documents
231 against the RELAX NG schema before further processing.
</para>
233 <para>Some document constraints can't be expressed in schema languages
234 like RELAX NG or W3C XML Schema. To check for these additional
235 constraints DocBook V5.0 uses Schematron. We recommend that you
236 validate your document against both the RELAX NG and
237 Schematron schemas.
</para>
239 <table xml:
id=
"t.schema-comparison">
240 <title>Schema Comparison
</title>
241 <tgroup dbk:
cols=
"6">
242 <colspec dbk:
colwidth=
"4*"/>
243 <colspec dbk:
colwidth=
"1*" dbk:
align=
"center"/>
244 <colspec dbk:
colwidth=
"1*" dbk:
align=
"center"/>
245 <colspec dbk:
colwidth=
"1*" dbk:
align=
"center"/>
246 <colspec dbk:
colwidth=
"1*" dbk:
align=
"center"/>
247 <colspec dbk:
colwidth=
"1*" dbk:
align=
"center"/>
250 <entry>Description
</entry>
252 <entry>W3C XML Schema
</entry>
253 <entry>W3C XML Schema + Schematron
</entry>
254 <entry>RELAX NG
</entry>
255 <entry>RELAX NG + Schematron/NVDL
</entry>
260 <entry>Basic document structure
</entry>
268 <entry>ID/IDREF datatypes
</entry>
276 <entry>Datatypes
<footnote>
277 <para>In a very few places RELAX NG specifies datatype
278 like number (mainly for length specifications) or
279 enumeration between
<literal>0</literal> and
280 <literal>1</literal>.
</para>
281 <para>In general those datatypes can be also supported in
282 W3C XML Schema, but currently this schema is generated
283 from DTD which lacks datatype information.
</para>
293 <entry>Co-occurrences
<footnote>
294 <para>RELAX NG grammar enforces exclusivity of several
295 elements. For example if you have
<tag>title
</tag> inside
296 <tag>info
</tag> then it is not allowed to have another
297 <tag>title
</tag> outside
<tag>info
</tag>. Similarly,
298 models of HTML and CALS tables are separated and validated
299 properly, where in DTD and WXS only union of both models is
301 <para>On other places co-occurrences enforces particular
302 content model based on presence of specific attribute or
303 attribute value.
</para>
304 <para>Please also note that in theory co-occurences can be
305 validated using Schematron, but the current DocBook schema
306 uses RELAX NG for these definitions. Schematron can be used
307 only for validation, whereas grammar based schemas like
308 RELAX NG are useful also for other purposes like guided editing.
</para>
317 <entry>Hooks for MathML and SVG content
</entry>
325 <entry>Link type integrity
<footnote>
326 <para>Check whether ID/IDREF links are pointing to element
327 of corresponding type. For example that
328 <tag>footnoteref
</tag> points to
329 <tag>footnote
</tag>.
</para></footnote></entry>
337 <entry>Presence of
<tag dbk:
class=
"attribute">version
</tag>
338 attribute on the root element
</entry>
346 <entry>Miscellaneous checks
<footnote>
347 <para>For example consistency of segmented lists, only one
348 term inside term definition etc.
</para></footnote></entry>
356 <entry>Element exclusions
<footnote>
357 <para>Prevents improper nesting of elements, like admonition
358 inside admonition.
</para></footnote></entry>
369 <section xml:
id=
"schemas">
370 <title>Where to get the schemas
</title>
372 <para>The latest versions of schemas can be obtained from
<link
373 xl:
href=
"http://docbook.org/schemas/5x.html"/>. At the time this was
374 written the latest version was
&version;. Individual schemas are
375 available at the following locations:
</para>
379 <term>RELAX NG schema
</term>
380 <listitem><para><link xl:
href=
"http://docbook.org/xml/&version;/rng/docbook.rng"/></para></listitem>
383 <term>RELAX NG schema in compact syntax
</term>
384 <listitem><para><link xl:
href=
"http://docbook.org/xml/&version;/rng/docbook.rnc"/></para></listitem>
388 <listitem><para><link xl:
href=
"http://docbook.org/xml/&version;/dtd/docbook.dtd"/></para></listitem>
391 <term>W3C XML Schema
</term>
392 <listitem><para><link xl:
href=
"http://docbook.org/xml/&version;/xsd/docbook.xsd"/></para></listitem>
395 <term>Schematron schema with additional checks
</term>
396 <listitem><para><link xl:
href=
"http://docbook.org/xml/&version;/sch/docbook.sch"/></para></listitem>
400 <para>These schemas are also available from the mirror at
401 <link xl:
href=
"http://www.oasis-open.org/docbook/xml/&version;/"/>.
</para>
405 <section xml:
id=
"docs">
406 <title>DocBook documentation
</title>
408 <para>Detailed documentation about each DocBook V5.0 element is
410 xl:
href=
"http://docbook.org/tdg5/en/html/pt02.html">the reference part
411 of
<citetitle>DocBook: The Definitive Guide
</citetitle></link>.
</para>
414 <para>Other parts of
<citetitle>DocBook: The Definitive
415 Guide
</citetitle> have not yet been updated to reflect the changes
416 made in DocBook V5.0. Please do not be confused by this.
</para>
425 <section xml:
id=
"tools">
426 <title>Tool chain
</title>
428 <para>This section briefly describes tools and procedures to edit and
429 process content stored in DocBook V5.0.
</para>
431 <section xml:
id=
"editors">
432 <title>Editing DocBook V5.0
</title>
434 <para>Because DocBook is an XML-based format and XML is a text-based
435 format, you can use any text editor to create and edit DocBook V5.0
436 documents. However, using
<quote>dumb
</quote> editors like Notepad is
437 not very productive. You will do better if you use an editor that
438 supports XML. Although there are DTD and W3C XML Schemas available for
439 DocBook V5.0, which means you can use any editor that works with DTDs
440 or W3C XML Schemas, we recommend that you use the RELAX NG grammar
441 with DocBook V5.0. The rest of this section contains an overview of
442 XML editors (listed in alphabetical order) that are known to work with
443 RELAX NG schemas and that offer guided editing based on the RELAX NG
446 <section xml:
id=
"editors-nxml">
447 <title>Emacs and nXML
</title>
449 <para><link xl:
href=
"http://www.thaiopensource.com/nxml-mode/">nXML
450 mode
</link> is an add-on for the
<application
451 xl:
href=
"http://www.gnu.org/software/emacs/emacs.html">GNU
452 Emacs
</application> text editor. By installing nXML you can turn Emacs
453 into a very powerful XML editor that offers guided editing and
454 validation of XML documents.
</para>
456 <figure xml:
id=
"f.emacs">
457 <title>Emacs with nXML mode provides guided editing and validation
</title>
459 <imageobject dbk:
role=
"html">
460 <imagedata dbk:
fileref=
"images/emacs.png"/>
462 <imageobject dbk:
role=
"fo">
463 <imagedata dbk:
fileref=
"images/emacs.png" dbk:
width=
"100%"/>
468 <para>nXML uses a special configuration file named
469 <filename>schemas.xml
</filename> to associate schemas with XML
470 documents. Often you will find this file in the directory
471 <filename>site-lisp/nxml/schema
</filename> inside the Emacs installation
472 directory. Adding the following line into the configuration file,
473 will associate DocBook V5.0 elements with the appropriate
476 <programlisting><namespace
ns=
"http://docbook.org/ns/docbook" uri=
"<replaceable>/path/to/</replaceable>docbook.rnc"/></programlisting>
479 <para>Please note that nXML ships with a file named
480 <filename>docbook.rnc
</filename>. This file contains the RELAX NG grammar
481 for DocBook V4.x. Be sure that you associate the DocBook V5.0 namespace
482 with the corresponding DocBook V5.0 grammar.
</para>
485 <para>If you can't edit the global
<filename>schemas.xml
</filename> file,
486 you can create this file in the same directory as your document. nXML will
487 find associations placed there also. In this case you must create a
488 complete configuration file like:
</para>
490 <programlisting><locatingRules
xmlns=
"http://thaiopensource.com/ns/locating-rules/1.0">
491 <namespace
ns=
"http://docbook.org/ns/docbook" uri=
"<replaceable>/path/to/</replaceable>docbook.rnc"/>
492 </locatingRules
></programlisting>
496 <section xml:
id=
"editors-oxygen">
497 <title>oXygen
</title>
500 xl:
href=
"http://www.oxygenxml.com/">oXygen
</application> is a feature
501 rich XML editor. It has built-in support for many schema languages
502 including RELAX NG and it is preconfigured with many document types
503 including DocBook. oXygen will assist you with writing DocBook V5.0
504 content, and you will be able to validate your documents against both
505 RELAX NG and Schematron schemas.
</para>
507 <figure xml:
id=
"f.oxygen.open5">
508 <title>DocBook V5.0 document opened in oXygen
</title>
511 <imagedata dbk:
fileref=
"images/oxygen4.png" dbk:
width=
"100%"/>
516 <figure xml:
id=
"f.oxygen.author.mode">
517 <title>DocBook V5.0 document opened in oXygen in Author mode
</title>
520 <imagedata dbk:
fileref=
"images/oxygen5.png" dbk:
width=
"100%"/>
527 <section xml:
id=
"editors-xxe">
528 <title>XML Mind XML editor
</title>
530 <para><application xl:
href=
"http://www.xmlmind.com/xmleditor/">XML
531 Mind XML editor
</application> (XXE) is a visual validating XML editor that
532 provides a wordprocessor-like interface to users. It is available in
533 two versions, Standard and Professional. The Standard version is free and
534 provides everything you need to edit DocBook V5.0 documents.
</para>
536 <figure xml:
id=
"f.xmlmind">
537 <title>XML Mind XML Editor – feels almost like MS Word but real DocBook V5.0 markup is created
</title>
540 <imagedata dbk:
fileref=
"images/xxe.png" dbk:
width=
"100%"/>
545 <para>In order to use DocBook V5.0 in XXE you have to install
547 <menuchoice><guimenu>Options
</guimenu><guimenuitem>Install
548 Add-ons…
</guimenuitem></menuchoice>. Then choose
<guilabel>DocBook
549 5 configuration
</guilabel> and press the
<guibutton>OK
</guibutton>
550 button. After restart, XXE is ready to work with DocBook V5.0
557 <section xml:
id=
"validators">
558 <title>Validating DocBook V5.0
</title>
560 <para>If you are not using a RELAX NG-based validating editor when you
561 create documents, we strongly recommend that you validate your
562 documents against RELAX NG and Schematron schemas before processing
563 them. Only after successful validation can you be sure that your
564 document is really DocBook V5.0 and that processing tools will be able
565 to process it correctly.
</para>
567 <para>For validation you can use tools that support simultaneous RELAX NG and
568 Schematron validation, or you can use NVDL to orchestrate validation using
569 the two schemas.
</para>
571 <section xml:
id=
"validators-rng-sch">
572 <title>Using RELAX NG and Schematron
</title>
574 <para>You can find a list of RELAX NG validators at
<link
575 xl:
href=
"http://relaxng.org/#validators"/>. It is best to use
576 validators with support for embedded Schematron rules inside RELAX NG
577 schemas. Schematron is a rule-based validation language which is used
578 to impose additional constraints on DocBook documents. Schematron rules
579 assert conditions which are impossible or difficult to express
580 in a pure RELAX NG schema.
</para>
582 <para><application xl:
href=
"https://msv.dev.java.net/">Sun
583 Multi-Schema XML Validator (MSV)
</application> is able to validate an XML
584 document against a RELAX NG schema and Schematron rules at the same time.
585 To install and use MSV follow these steps:
</para>
589 <para>Download
<filename>relames.zip
</filename> from
<link xl:
href=
"https://msv.dev.java.net/servlets/ProjectDocumentList?folderID=101"/>.
</para>
592 <para>Unpack the downloaded file into an arbitrary directory.
</para>
595 <para>Validate your document using the following command:
</para>
596 <screen><command>java
</command> -Xss512K -jar
<replaceable>/path/to/
</replaceable>relames.jar
<replaceable>/path/to/
</replaceable>docbook.rng document.xml
</screen>
598 <para>The switch
<option>-Xss512K
</option> increases the stack size
599 of the Java virtual machine. This is necessary because the DocBook schema is
600 quite large. If you get stack overflow errors from MSV, increase
601 this value. You may get spurious error messages if the value
602 is too small, so if you get a stack overflow error, ignore any other error
603 messages and try a larger value for the stack size.
604 If you are not using Sun's Java implementation, please consult the
605 documentation for your virtual machine to learn how to increase the stack
611 <para>There is also an
<link
612 xl:
href=
"http://relaxed.vse.cz/docbookvalidator/">on-line DocBook V5.0
613 validator
</link> that validates DocBook V5.0 documents against the normative
614 RELAX NG schema with embedded Schematron rules.
</para>
619 <title>Using NVDL
</title>
621 <para>NVDL is a meta-schema language which can validate a document
622 against several schemas. DocBook V5.0 comes with a NVDL
623 schema which specifies that DocBook documents should be validated
624 against both RELAX NG and Schematron schemas.
</para>
626 <para>You can find a list of NVDL validators at
<link
627 xl:
href=
"http://nvdl.org/"/>. The following procedures show how to
628 install and use the
<application
629 xl:
href=
"http://www.oxygenxml.com/onvdl.html">oNVDL
</application> and
630 <application xl:
href=
"http://jnvdl.sourceforge.net">JNVDL
</application>
634 <title>oNVDL installation and usage
</title>
636 <para>Download
<filename
637 xl:
href=
"http://www.oxygenxml.com/InstData/onvdl/onvdl-20070517.zip">onvdl-
20070517.zip
</filename>.
</para>
640 <para>Unpack the downloaded file into an arbitrary directory.
</para>
643 <para>Validate your document using the following command:
</para>
644 <screen><command>java
</command> -jar
<replaceable>/path/to/oNVDL/
</replaceable>bin/onvdl.jar
<replaceable>/path/to/
</replaceable>docbook.nvdl document.xml
</screen>
649 <title>JNVDL installation and usage
</title>
651 <para>Download the latest release of JNVDL from
<link
652 xl:
href=
"http://sourceforge.net/project/showfiles.php?group_id=164464"/>.
</para>
655 <para>Unpack the downloaded file into an arbitrary directory.
</para>
658 <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>
661 <para>On Windows systems, validate your document using the following command:
</para>
662 <screen><replaceable>/path/to/jnvdl/
</replaceable><command>jnvdl
</command> -nt -s
<replaceable>/path/to/
</replaceable>docbook.nvdl document.xml
</screen>
663 <para>On Unix systems, validate your document using the following command:
</para>
664 <screen><replaceable>/path/to/jnvdl/
</replaceable><command>jnvdl.sh
</command> -nt -s
<replaceable>/path/to/
</replaceable>docbook.nvdl document.xml
</screen>
672 <section xml:
id=
"processing">
673 <title>Processing DocBook V5.0
</title>
675 <para>Part of DocBook's great success can be attributed to the
677 tools that can be used to transform DocBook content into various
678 target formats including HTML and PDF. The DocBook XSL Stylesheets are
679 very popular tools.
</para>
681 <section xml:
id=
"dbxsl">
682 <title>DocBook XSL Stylesheets
</title>
684 <para>The DocBook stylesheets are designed to process content written in
685 different versions of DocBook (for example
3.1 and
4.2). Recent
686 versions of the stylesheets are also able to process DocBook V5.0
687 with some limitations.
</para>
689 <para>You can process DocBook V5.0 documents with the DocBook XSL
690 stylesheets in exactly the same way you process DocBook V4.x documents.
691 You do not need special software; you can stick to your preferred
692 XSLT processor, be it Saxon, xsltproc, Xalan or whatever else (but see
693 the note about the lost base URI below).
</para>
695 <para>During document processing, the stylesheets strip
696 namespaces from DocBook V5.0 to get a document which will be
697 very similar to DocBook V4.x. This is necessary because from the XSLT
698 point of view, elements from different namespaces are distinct and cannot
699 be easily processed by the same set of templates. This process is
700 completely transparent to the user. If you are processing DocBook V5.0
701 documents, the only difference is that you will see the following
702 additional message:
</para>
704 <screen>Note: namesp. cut : stripped namespace before processing
705 Note: namesp. cut : processing stripped document
</screen>
707 <para>Although you can successfully use the existing stylesheets to
708 process DocBook V5.0, there are some limitations and unsupported
709 features. The unsupported features include:
</para>
712 <listitem><para>general annotations;
</para></listitem>
713 <listitem><para>general XLink links on all elements.
</para></listitem>
717 <para>During namespace stripping, the base URI of the document is
718 lost. This means that in rare situations, relatively referenced
719 resources like images or programlistings can be processed incorrectly.
720 The stylesheets attempt to compensate for this problem, but that is not always
721 possible. When an XSLT processor other than Saxon or Xalan is used, a warning
722 message is generated:
724 <screen>WARNING: cannot add @xml:base to node set root element. Relative paths may not work.
</screen>
730 <section xml:
id=
"dbxsl-ns">
731 <title>DocBook XSL-NS Stylesheets
</title>
732 <para>As you can see from reading the previous section, namespace
733 stripping has limitations that will cause trouble in some
734 situations. To overcome those limitations, Bob Stayton created a
735 build system for taking the non-namespace-aware DocBook XSL
736 stylesheets and generating namespace-aware versions from them.
738 xl:
href=
"http://docbook.sourceforge.net/release/xsl-ns/current/"
739 >XSL-NS stylesheets
</link> are the result.
</para>
741 <para>The DocBook XSL-NS stylesheets are released side-by-side
742 with the DocBook XSL stylesheets, as a separate
<link
743 xl:
href=
"https://sourceforge.net/project/showfiles.php?group_id=21935&package_id=219178"
744 ><package>docbook-xsl-ns
</package></link> package. They are the
745 recommended XSLT
1.0 stylesheets to use for transforming
746 namespaced (DocBook V5.0) documents.
</para>
749 <section xml:
id=
"dbxsl2">
750 <title>XSLT
2.0 based re-implementation
</title>
752 <para>XSLT
1.0 is missing some important features. To work around
753 these missing features, the current DocBook XSL stylesheets use some
754 implementation-specific extensions.
755 XSLT
2.0 adds many new and previously missing features into the language.
756 A new set of DocBook stylesheets is being implemented based on XSLT
2.0
757 to take advantage of these features and to fully support DocBook V5.0.
760 <para>The XSLT
2.0 based stylesheets have many new features, including:
</para>
763 <listitem><para>seamless integration of profiling (conditional
764 documents) with external bibliographies and
765 glossaries;
</para></listitem>
766 <listitem><para>no need for (most) external extensions;
</para></listitem>
767 <listitem><para>internationalized indexes;
</para></listitem>
768 <listitem><para>easy to customize titlepage templates.
</para></listitem>
771 <para>The XSLT
2.0 based stylesheets are still under development. At
772 this writing, they only support HTML and chunked HTML output. As time
773 permits, the stylesheet developers will be adding other formats. Since
774 the stylesheets are developed in the limited free time the developers
775 have, there's no specific schedule.
</para>
777 <para>There are not very many XSLT
2.0 implementations available.
778 But, if you want to try the new stylesheets, grab a snapshot of
779 the development version from
<link
780 xl:
href=
"http://docbook.sourceforge.net/snapshots/docbook-xsl2-snapshot.zip"/>
781 and unpack it somewhere. Then download and install Saxon
9 from
<link
782 xl:
href=
"http://saxon.sf.net"/>.
</para>
784 <para>To transform a DocBook V5.0 document to a single HTML page use the command:
</para>
786 <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>
788 <para>To transform a DocBook V5.0 document to a set of chunked HTML pages use the command:
</para>
790 <screen><command>java
</command> -jar
<replaceable>/path/to/
</replaceable>saxon9.jar document.xml
<replaceable>/path/to/
</replaceable>docbook-xsl2-snapshot/html/chunk.xsl
</screen>
798 <section xml:
id=
"changes">
799 <title>Markup changes
</title>
801 <para>This section describes the most common markup changes
802 between DocBook V4.x and V5.0.
803 You can find a complete list of changes in
804 <citation>DB5SPEC
</citation>.
</para>
806 <section xml:
id=
"changes-linking">
807 <title>Improved cross-referencing and linking
</title>
809 <para>In DocBook V4.x the attribute
<tag dbk:
class=
"attribute">id
</tag> is
810 used to assign a unique identifier to an element. In DocBook V5.0 this
811 attribute is renamed
<tag dbk:
class=
"attribute">xml:id
</tag> in order
812 to comply with
<citation>XMLID
</citation>.
</para>
814 <para>Now you can use almost any inline element as the source of a link,
815 not just
<tag>xref
</tag> or
<tag>link
</tag>. For example, the following
816 DocBook
4.x content:
</para>
818 <programlisting><![CDATA[
<section id=
"dir">
819 <title>DIR command
</title>
824 <title>LS command
</title>
825 <para>This command is a synonym for
<link linkend=
"dir"><command>DIR
</command></link> command.
</para>
826 </section>]]
></programlisting>
828 <para>is written in DocBook V5.0 as:
</para>
830 <programlisting><![CDATA[
<section xml:
id=
"dir">
831 <title>DIR command
</title>
835 <section xml:
id=
"ls">
836 <title>LS command
</title>
837 <para>This command is a synonym for
<command linkend=
"dir">DIR
</command> command.
</para>
838 </section>]]
></programlisting>
840 <para>The
<tag dbk:
class=
"attribute">linkend
</tag> attribute was added to all
841 inline elements together with the
<tag dbk:
class=
"attribute">href
</tag>
842 attribute from the XLink namespace. This means that you can use any inline
843 element as the source of a hypertext link. To use XLinks you have
844 to declare the XLink namespace (most often on the root element of your
847 <programlisting><![CDATA[
<article xmlns=
"http://docbook.org/ns/docbook"
848 xmlns:
xl=
"http://www.w3.org/1999/xlink" version=
"5.0">
849 <title>Test article
</title>
851 <para><application xl:
href=
"http://www.gnu.org/software/emacs/emacs.html">Emacs
</application>
852 is my favourite text editor.
</para>]]
>
855 <para>The
<tag dbk:
condition=
"v4">ulink
</tag> element was removed from DocBook V5.0
856 in favor of XLink linking. Instead of the DocBook V4.x
<tag dbk:
condition=
"v4">ulink
</tag>
859 <programlisting><![CDATA[
<ulink url=
"http://docbook.org">DocBook site
</ulink>]]
></programlisting>
861 <para>you can now use
<tag>link
</tag></para>
863 <programlisting><![CDATA[
<link xl:
href=
"http://docbook.org">DocBook site
</link>]]
></programlisting>
865 <para>XLink links may contain a fragment identifier, which you can
866 use instead of
<tag dbk:
class=
"attribute">linkend
</tag> to form
867 cross-references inside a document; for example:
</para>
869 <programlisting><![CDATA[
<command xl:
href=
"#dir">DIR
</command>]]
></programlisting>
871 <para>However XLink links are not checked during validation, while
<tag
872 dbk:
class=
"attribute">xml:id
</tag>/
<tag dbk:
class=
"attribute">linkend
</tag>
873 links are checked for ID/IDREF consistency.
874 One place where the XLink-based, fragment identifier scheme is
875 useful is when XInclude is being used, since XML ID/IDREF links
876 cannot span XInclude boundaries.
877 You can use whichever approach better suits your needs.
</para>
880 <section xml:
id=
"changes-renamed">
881 <title>Renamed elements
</title>
883 <para>Some elements were renamed to better express their meaning or to
884 reduce the total number of elements available in DocBook.
</para>
886 <table xml:
id=
"t.renamed">
887 <title>Renamed elements
</title>
888 <tgroup dbk:
cols=
"2">
891 <entry>Old name
</entry>
892 <entry>New name
</entry>
897 <entry><tag dbk:
condition=
"v4">sgmltag
</tag></entry>
898 <entry><tag>tag
</tag></entry>
901 <entry><tag dbk:
condition=
"v4">bookinfo
</tag>,
<tag dbk:
condition=
"v4">articleinfo
</tag>,
902 <tag dbk:
condition=
"v4">chapterinfo
</tag>,
<tag dbk:
condition=
"nolink">*info
</tag></entry>
903 <entry><tag>info
</tag></entry>
906 <entry><tag dbk:
condition=
"v4">authorblurb
</tag></entry>
907 <entry><tag>personblurb
</tag></entry>
910 <entry><tag dbk:
condition=
"v4">collabname
</tag>,
<tag dbk:
condition=
"v4">corpauthor
</tag>,
911 <tag dbk:
condition=
"v4">corpcredit
</tag>,
<tag dbk:
condition=
"v4">corpname
</tag></entry>
912 <entry><tag>orgname
</tag></entry>
915 <entry><tag dbk:
condition=
"v4">isbn
</tag>,
<tag dbk:
condition=
"v4">issn
</tag>,
916 <tag dbk:
condition=
"v4">pubsnumber
</tag></entry>
917 <entry><tag>biblioid
</tag></entry>
920 <entry><tag dbk:
condition=
"v4">lot
</tag>,
<tag dbk:
condition=
"v4">lotentry
</tag>,
<tag dbk:
condition=
"v4">tocback
</tag>,
921 <tag dbk:
condition=
"v4">tocchap
</tag>,
<tag dbk:
condition=
"v4">tocfront
</tag>,
<tag dbk:
condition=
"v4">toclevel1
</tag>,
922 <tag dbk:
condition=
"v4">toclevel2
</tag>,
<tag dbk:
condition=
"v4">toclevel3
</tag>,
<tag dbk:
condition=
"v4">toclevel4
</tag>,
923 <tag dbk:
condition=
"v4">toclevel5
</tag>,
<tag dbk:
condition=
"v4">tocpart
</tag></entry>
924 <entry><tag>tocdiv
</tag></entry>
927 <entry><tag dbk:
condition=
"v4">graphic
</tag>,
<tag dbk:
condition=
"v4">graphicco
</tag>,
928 <tag dbk:
condition=
"v4">inlinegraphic
</tag>,
<tag dbk:
condition=
"v4">mediaobjectco
</tag></entry>
929 <entry><tag>mediaobject
</tag> and
<tag>inlinemediaobject
</tag></entry>
932 <entry><tag dbk:
condition=
"v4">ulink
</tag></entry>
933 <entry><tag>link
</tag></entry>
936 <entry><tag dbk:
condition=
"v4">ackno
</tag></entry>
937 <entry><tag>acknowledgements
</tag></entry>
945 <section xml:
id=
"changes-removed">
946 <title>Removed elements
</title>
948 <para>The following elements were removed from DocBook V5.0 without
949 direct replacements:
<tag dbk:
condition=
"v4">action
</tag>,
<tag
950 dbk:
condition=
"v4">beginpage
</tag>,
<tag dbk:
condition=
"v4">highlights
</tag>,
951 <tag dbk:
condition=
"v4">interface
</tag>,
<tag
952 dbk:
condition=
"v4">invpartnumber
</tag>,
<tag
953 dbk:
condition=
"v4">medialabel
</tag>,
<tag dbk:
condition=
"v4">modespec
</tag>,
954 <tag dbk:
condition=
"v4">structfield
</tag>,
<tag
955 dbk:
condition=
"v4">structname
</tag>.
956 If you use one or more of these elements, here are some suggestions
957 as to how to re-code them in DocBook V5.0.
960 <table xml:
id=
"t.removed">
961 <title>Recommended mapping for removed elements
</title>
962 <tgroup dbk:
cols=
"2">
965 <entry>Old name
</entry>
966 <entry>Recommended mapping
</entry>
971 <entry><tag dbk:
condition=
"v4">action
</tag></entry>
972 <entry>Use
<computeroutput><<tag>phrase
</tag> remap=
"action"></computeroutput>.
</entry>
975 <entry><tag dbk:
condition=
"v4">beginpage
</tag></entry>
976 <entry>Remove:
<tag dbk:
condition=
"v4">beginpage
</tag> is advisory only
977 and has tended to cause confusion. A processing instruction or
978 comment should be a workable replacement if one is needed.
</entry>
981 <entry><tag dbk:
condition=
"v4">highlights
</tag></entry>
982 <entry>Use
<tag>abstract
</tag>. Note that because
<tag
983 dbk:
condition=
"v4">highlights
</tag> has a broader content model, you may
984 need to wrap contents in a
<tag>para
</tag> inside
985 <tag>abstract
</tag>.
</entry>
988 <entry><tag dbk:
condition=
"v4">interface
</tag></entry>
989 <entry>Use one of the
<quote>gui*
</quote> elements
990 (
<tag>guibutton
</tag>,
<tag>guiicon
</tag>,
<tag>guilabel
</tag>,
991 <tag>guimenu
</tag>,
<tag>guimenuitem
</tag>, or
992 <tag>guisubmenu
</tag>).
</entry>
995 <entry><tag dbk:
condition=
"v4">invpartnumber
</tag></entry>
996 <entry>Use
<computeroutput><<tag>biblioid
</tag> class=
"other"
997 otherclass=
"medialabel"></computeroutput>. The
998 <tag>productnumber
</tag> element is another alternative.
</entry>
1001 <entry><tag dbk:
condition=
"v4">medialabel
</tag></entry>
1002 <entry>Use
<computeroutput><<tag>citetitle
</tag>
1003 pubwork=
"<replaceable>mediatype</replaceable>"></computeroutput>,
1004 where
<replaceable>mediatype
</replaceable> is the type of media being
1005 labeled (e.g.,
<tag dbk:
class=
"attvalue">cdrom
</tag> or
<tag
1006 dbk:
class=
"attvalue">dvd
</tag>).
</entry>
1009 <entry><tag dbk:
condition=
"v4">modespec
</tag></entry>
1010 <entry>No longer needed. The current processing model for
1011 <tag>olink
</tag> renders
<tag dbk:
condition=
"v4">modespec
</tag>
1012 unnecessary.
</entry>
1015 <entry><tag dbk:
condition=
"v4">structfield
</tag>,
<tag dbk:
condition=
"v4">structname
</tag></entry>
1016 <entry>Use
<tag>varname
</tag>. If you need to distinguish between the
1017 two, use
<computeroutput><<tag>varname
</tag>
1018 remap=
"<replaceable>structname or
1019 structfield</replaceable>"></computeroutput>. In some contexts, it
1020 may also be appropriate to use
<tag>property
</tag> for
<tag
1021 dbk:
condition=
"v4">structfield
</tag>.
</entry>
1031 <section xml:
id=
"convert4to5">
1032 <title>Converting DocBook V4.x documents to DocBook V5.0
</title>
1034 <para>The DocBook V5.0 schema ships with an XSLT
1.0 stylesheet that
1035 is designed to transform valid DocBook V4.x documents to valid
1036 DocBook V5.0 documents.
</para>
1038 <para>To convert your document,
<filename>doc.xml
</filename> in the
1039 examples below, follow these steps:
</para>
1043 <para>Check the validity of your DocBook XML V4.x document. The
1044 conversion tool assumes that the input document is valid. If the input
1045 document contains markup errors, the results will be unpredictable at
1049 <para>Transform
<filename>doc.xml
</filename> to
1050 <filename>newdoc.xml
</filename> with the
1051 <filename>db4-upgrade.xsl
</filename> stylesheet included in the
1052 DocBook V5.0 distribution that you are using.
</para>
1055 <para>Check the validity of your DocBook XML V5.0 document against
1056 the DocBook V5.0 RELAX NG grammar.
</para>
1060 <para>In the vast majority of cases, the resulting document should
1061 be valid and your conversion process is finished.
</para>
1063 <para>If the document is not valid, please report the problem.
1064 (Over time, we'll have more experience with the sorts of things
1065 that can go wrong and we'll update this document to reflect that
1068 <section xml:
id=
"entities">
1069 <title>What About Entities?
</title>
1071 <para>Using XSLT to transform existing documents to DocBook V5.0 has
1072 one potential disadvantage: it removes all entity references from
1073 your document.
</para>
1075 <para>If preserving entities is an important aspect of your production
1076 work flow, you will have to engage in a semi-manual process to
1077 preserve them.
</para>
1081 <para>Open your existing document using your favorite editing tool.
1082 You must use a tool that
<emphasis>is not
</emphasis> XML-aware, or one
1083 that allows you to edit markup “in the raw”.
</para>
1086 <para>Replace all occurrences of the entity references that you want
1087 to preserve with some unique string. For example, if you want to preserve
1088 “
<literal>&Product;
</literal>” references, you could replace them
1089 all with “
<literal>[[[Product]]]
</literal>” (assuming that the string
1090 “
<literal>[[[Product]]]
</literal>” doesn't occur anywhere else in your document).
</para>
1093 <para>Copy the document type declaration off of your document and save
1094 it some place. The document type declaration is everything from
1095 “
<literal><!DOCTYPE
</literal>” to the closing “
<literal>]
></literal>”.
1099 <para>Perform the conversion described in
<xref dbk:
linkend=
"convert4to5"/>.
1103 <para>Open the new document using your favorite editing tool. Replace
1104 all occurrences of the unique string you used to save the entity references
1105 with the corresponding entity references.
</para>
1108 <para>Paste the document type declaration that you saved onto the top
1109 of your new document.
</para>
1112 <para>Remove the external identifier (the
<literal>PUBLIC
</literal>
1113 and/or
<literal>SYSTEM
</literal> keywords) from the document type
1114 declaration. A document that begins:
</para>
1115 <programlisting><![CDATA[
<!DOCTYPE book [
1116 <!ENTITY someEntity
"some replacement text">
1117 ]
>]]
></programlisting>
1118 <para>is perfectly well-formed. If you don't remove the references to
1119 the DTD, then your parser will likely try to validate against DocBook
1120 V4.0 and that's not going to work. Alternatively, you could refer
1121 to the DocBook V5.0 DTD.
</para>
1126 <para>Steps
2 and
5 from previous procedure can be automated using the
1127 <link xl:
href=
"http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/contrib/tools/cloak">cloak
1128 script
</link> written by Michael Smith.
</para>
1131 <section xml:
id=
"extparsedentities">
1132 <title>External Parsed Entities
</title>
1134 <para>External parsed entities, entities which load part of a document
1135 from another file, are a special case. These can often be replaced
1136 with XInclude elements.
</para>
1138 <para>The Perl script
<filename>db4-entities.pl
</filename>, also included
1139 in the DocBook V5.0 distribution attempts to perform this replacement
1140 for you. To use the script, perform the following steps:
</para>
1144 <para>Process your document with
<filename>db4-entities.pl
</filename>.
1145 The script expects a single filename and prints the XInclude version
1146 on standard output.
</para>
1149 <para>Process the XInclude version as described in
<xref
1150 dbk:
linkend=
"convert4to5"/>.
1159 <section xml:
id=
"customizations">
1160 <title>Customizing DocBook V5.0
</title>
1162 ** RNG schema organization
1163 ** Removing attributes
1164 ** Adding new attributes
1165 ** Changing permitted content of attribute
1166 ** Removing elements
1167 ** Adding new elements
1168 ** Customizing content models
1169 ** Naming and versioning of DocBook customizations
1173 It's much easier to customize DocBook V5.0 than it was to
1174 customize earlier releases. This is partly because RELAX NG
1175 provides better support for modifications than DTDs and partly
1176 because the DocBook schema is designed to take full advantage
1177 of the capabilities RELAX NG provides.
1178 This section describes the organization of the RELAX NG schema for
1179 DocBook, methods and examples for adding, removing, and modifying elements
1180 and attributes, and conventions for naming and versioning
1181 DocBook customizations.
1182 It assumes some familiarity with RELAX NG. If you are unfamiliar
1183 with RELAX NG, you can find a tutorial introduction in
1184 <citation>RNCTUT
</citation>.
1186 <section xml:
id=
"relaxngorg">
1187 <title>DocBook RELAX NG schema organization
</title>
1189 The DocBook RELAX NG schema is highly modular, using named
1190 patterns extensively. Every element, attribute, attribute
1191 list, and enumeration has its own named pattern. In addition,
1192 there are named patterns for logical combinations of elements
1193 and attributes. These named patterns provide
<quote>hooks
</quote>
1194 into the schema that allow you to do a wide range of customization
1195 by simply redefining one or more of the named patterns.
1198 An important design characteristic of the schema is that
1199 duplication is minimized. This is done through the use of
1200 named patterns for common groupings that can be re-used.
1201 For example, the
<tag>imagedata
</tag> and
<tag>videodata
</tag>
1202 elements each have an
<tag dbk:
class=
"attribute">align
</tag> attribute
1203 that takes the same set of enumerated values. Rather than
1204 repeating those values, a single pattern,
1205 <varname>db.halign.enumeration
</varname> is referenced by
1206 the
<varname>db.videodata.align.enumeration
</varname>
1207 and
<varname>db.imagedata.align.enumeration
</varname> patterns,
1208 which are in turn referenced by the
1209 <varname>db.videodata.align.attribute
</varname>
1210 and
<varname>db.imagedata.align.attribute
</varname> patterns.
1211 While this may seem like overkill, it allows a customizer to modify
1212 the allowed enumerations for these two attributes separately or together,
1213 or to completely re-define the allowed content of either or both,
1214 by redefining one or more of these named patterns.
1216 <section xml:
id=
"patternnames"><title>Pattern Names
</title>
1218 Because named patterns are used extensively, the RELAX NG schema uses
1219 several naming conventions. These are:
1220 <itemizedlist dbk:
spacing=
"compact">
1223 Names have two or more parts, separated by dots
<quote>.
</quote>
1228 The first part of each name is the prefix
<quote>db
</quote>
1233 Each element has a named pattern in the form
1234 <varname>db.
<replaceable>elementname
</replaceable></varname>.
1235 Elements that have different content models in different
1236 contexts will also have patterns in the form
1237 <varname>db.
<replaceable>context.elementname
</replaceable></varname>. For example,
<varname>db.figure.info
</varname>
1238 defines the content model for the
<tag>info
</tag> element
1239 when it appears as a child of the
<tag>figure
</tag> element.
1240 <replaceable>Context
</replaceable> may have several parts.
1241 For example,
<varname>db.cals.entrytbl.thead
</varname>.
1246 Most attributes have a named pattern in the form
1247 <varname>db.
<replaceable>attributename
</replaceable>.attribute
</varname>.
1248 Attributes that have different content models in different
1249 contexts will also have patterns in the form
1250 <varname>db.
<replaceable>context.attributename
</replaceable>.attribute
</varname>.
1252 <varname>db.olink.localinfo.attribute
</varname> defines the content
1253 model of the
<tag dbk:
class=
"attribute">localinfo
</tag> attribute when
1254 it appears in
<tag>olink
</tag>.
1255 There are a few attributes that do not have individual named
1256 patterns. For example, the effectivity attributes are grouped
1257 into
<varname>db.effectivity.attributes
</varname> and not identified
1263 Each element has a named pattern for its attribute list in
1265 <varname>db.
<replaceable>elementname
</replaceable>.attlist
</varname>
1267 that defines the list of attributes for that element.
1268 Elements that have different attribute lists in different
1269 contexts will also have patterns in the form
1270 <varname>db.
<replaceable>context.elementname
</replaceable>.attlist
</varname>
1271 For example,
<varname>db.html.table.attlist
</varname> defines
1272 the attribute list for the html
<tag dbk:
condition=
"nolink">table
</tag> element and
1273 <varname>db.cals.table.attlist
</varname> defines the attribute
1274 list for a cals
<tag dbk:
condition=
"nolink">table
</tag> element.
1279 Each attribute that has enumerated values has a
1280 named pattern in the form
1281 <varname>db.
<replaceable>[context.]attributename
</replaceable>.enumeration
</varname>.
1282 If the enumeration for a particular attribute depends on
1283 context, optional context is provided.
1285 <varname>db.verbatim.continuation.enumeration
</varname> defines
1286 the enumeration values for the
1287 <tag dbk:
class=
"attribute">continuation
</tag> attribute that is used
1288 in verbatim contexts like
<tag>screen
</tag>.
1289 Unlike elements and attributes, there is not necessarily a
1290 named pattern for enumerated attributes outside their context.
1291 For example, there is no
<varname>db.class.enumeration
</varname>
1292 because the
<tag dbk:
class=
"attribute">class
</tag> attribute has
1293 a broad and non-intersecting range of uses.
1298 There are several different groupings of elements and attributes.
1299 Here are the major ones:
1300 <variablelist dbk:
spacing=
"compact">
1302 <term>inlines
</term>
1305 Combinations of inline elements, for example,
1306 <varname>db.error.inlines
</varname>, which contains
1307 <varname>db.errorcode
</varname>,
1308 <varname>db.errortext
</varname>, etc.
1316 Combinations of block elements, for example,
1317 <varname>db.verbatim.blocks
</varname>, which contains
1318 <varname>db.programlisting
</varname>,
1319 <varname>db.screen
</varname>, etc.
1324 <term>attributes
</term>
1327 Combinations of attributes, for example,
1328 <varname>db.effectivity.attributes
</varname>,
1329 which contains the attributes
1330 <tag dbk:
class=
"attribute">arch
</tag>,
1331 <tag dbk:
class=
"attribute">condition
</tag>,
1332 <tag dbk:
class=
"attribute">conformance
</tag>, etc.
1337 <term>components
</term>
1340 High level components of the schema, for example,
1341 <varname>db.navigation.components
</varname>, which contains
1342 <varname>db.glossary
</varname>,
1343 <varname>db.bibliography
</varname>,
1344 <varname>db.index
</varname>, and
1345 <varname>db.toc
</varname>, and is used inside the
1346 content model for
<tag>chapter
</tag>,
<tag>appendix
</tag>,
1347 and
<tag>preface
</tag>.
1352 <term>contentmodel
</term>
1355 Shared content models, for example,
1356 <varname>db.admonition.contentmodel
</varname>, which contains
1357 the content model for
<tag>tip
</tag>,
<tag>warning
</tag>,
1358 <tag>note
</tag>, etc.
1365 There are a couple of other groupings designed to minimize
1366 duplication, but these are the most important.
1373 <section xml:
id=
"customconsiderations">
1374 <title>General customization considerations
</title>
1376 Creating a customized schema is similar to
1377 creating a customization layer for XSL. The schema customization
1378 layer is a new RELAX NG schema that defines your changes and
1379 includes the standard docbook schema. You then validate using
1380 the schema customization as your schema.
1383 <xref dbk:
linkend=
"ex-empty" dbk:
xrefstyle=
"select: label"/> is an empty
1384 RELAX NG customization that does nothing
1385 except define the name spaces and include the standard DocBook schema.
1386 The
<tag dbk:
class=
"attribute">href
</tag> attribute of the
1387 <tag dbk:
condition=
"nolink">include
</tag> element points to
1388 the location of the standard DocBook V5.0
1389 schema.
<footnote><para>The examples in this section use
1390 <filename>docbook.rng
</filename> as the schema location. If you want
1391 to create a portable schema customization you should use a standard
1392 web-accessible location like
1393 <uri>http://docbook.org/xml/
&version;/rng/docbook.rng
</uri> and
1395 xl:
href=
"http://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html">XML
1396 catalogs
</link> to resolve this location to your local copy of the
1397 schema for improved performance. Unfortunately, at the time of
1398 this writing not all RELAX NG validators support XML catalogs.
</para></footnote>
1399 All of the examples are given in both RNG and RNC form.
1400 <example xml:
id=
"ex-empty"><title>Empty customization file
</title>
1401 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1402 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1403 ns=
"http://docbook.org/ns/docbook"
1404 xmlns=
"http://relaxng.org/ns/structure/1.0">
1405 <include href=
"docbook.rng"/>
1407 <!-- redefinitions of named patterns -->
1409 </grammar>]]
></programlisting>
1410 <programlisting dbk:
language=
"rnc"><![CDATA[namespace db =
"http://docbook.org/ns/docbook"
1412 include
"docbook.rnc" inherit = db
1413 # redefinitions of named patterns]]
></programlisting>
1417 <section xml:
id=
"cust-elements">
1418 <title>Elements
</title>
1419 <section xml:
id=
"cust-add-elements">
1420 <title>Adding elements
</title>
1422 Adding an element typically takes two definitions.
1423 The first defines the new element and
1424 its content model, and the second adds the
1425 new element into the schema. We'll show two examples.
1428 <xref dbk:
linkend=
"ex-add-element-1" dbk:
xrefstyle=
"select: label"/>
1430 <tag dbk:
condition=
"nolink">person
</tag>, with the same
1431 content model as
<tag>author
</tag>. The new element will be
1432 allowed to appear wherever
<tag>author
</tag> can appear.
1435 The
<varname>db.author
</varname> pattern is copied
1436 and renamed
<varname>dbx.person
</varname>, defining
1437 a new element called
<tag dbk:
condition=
"nolink">person
</tag>.
1438 Then, the
<varname>db.author
</varname> pattern is redefined
1439 to be a choice of the current value or
<varname>dbx.person
</varname>.
1440 The
<tag dbk:
class=
"attribute">combine
</tag> attribute tells
1441 RELAX NG to combine this pattern with the existing named
1442 pattern. In this case, the value
1443 of the
<tag dbk:
class=
"attribute">combine
</tag> attribute is
1444 <quote>choice
</quote>, which tells the parser that either
1445 the original pattern or this new pattern is a valid match.
1447 <example xml:
id=
"ex-add-element-1"><title>Adding a new element by duplicating an existing one
</title>
1448 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1449 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1450 ns=
"http://docbook.org/ns/docbook"
1451 xmlns=
"http://relaxng.org/ns/structure/1.0">
1452 <include href=
"docbook.rng"/>
1453 <!-- define the new element -->
1454 <define name=
"dbx.person">
1455 <element name=
"person">
1456 <ref name=
"db.author.attlist"/>
1457 <ref name=
"db.credit.contentmodel"/>
1460 <!-- redefine the db.author pattern to allow db.person in
1461 the same places as db.author -->
1462 <define name=
"db.author" combine=
"choice">
1463 <ref name=
"dbx.person"/>
1465 </grammar>]]
></programlisting>
1466 <programlisting dbk:
language=
"rnc"><![CDATA[default namespace db =
"http://docbook.org/ns/docbook"
1468 include
"docbook.rnc"
1469 # define the new element
1471 element person { db.author.attlist, db.credit.contentmodel }
1472 # redefine the db.author pattern to allow db.person in
1473 # the same places as db.author
1474 db.author |= dbx.person]]
></programlisting>
1477 The preceding method works well when you'd like a new element
1478 to be a clone or near-clone of an existing element. It gives
1479 you complete control over the content model, but
1480 only limited control over where the element is allowed. It
1481 works well when you want to allow the element in the same places
1482 as an existing element, and for this example that works
1483 nicely, since
<tag>author
</tag> is allowed in four different
1484 named patterns, each of which would have had to be redefined to
1485 allow
<tag dbk:
condition=
"nolink">person
</tag>.
1486 But, if you can't find an existing element that is allowed in
1487 exactly the places you need, this method doesn't work as well.
1490 <xref dbk:
linkend=
"ex-add-element-2" dbk:
xrefstyle=
"select: label"/>
1491 adds two new elements by combining them into
1492 a higher level pattern. In this example, we'll add
1493 two new inline elements for writing about assembly language,
1494 <tag dbk:
condition=
"nolink">register
</tag> and
1495 <tag dbk:
condition=
"nolink">instruction
</tag>.
1496 We will allow them wherever programming inlines
1497 or operating system inlines are allowed.
1498 <xref dbk:
linkend=
"ex-add-element-2" dbk:
xrefstyle=
"select: label"/>
1499 defines the two elements, creates a new named pattern
1500 (
<varname>dbx.asm.inlines
</varname>) that contains them, and adds
1501 that pattern to
<varname>db.programming.inlines
</varname> and
1502 <varname>db.os.inlines
</varname>. Since these two patterns
1503 don't have any elements in common, the strategy used in
1504 <xref dbk:
linkend=
"ex-add-element-1" dbk:
xrefstyle=
"select: label"/>
1505 would require selecting two different elements to
<quote>clone
</quote>,
1506 which would be messy.
1508 <example xml:
id=
"ex-add-element-2"><title>Adding new inline elements
</title>
1509 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1510 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1511 ns=
"http://docbook.org/ns/docbook"
1512 xmlns=
"http://relaxng.org/ns/structure/1.0">
1513 <include href=
"docbook.rng"/>
1514 <!-- define the new elements -->
1515 <define name=
"dbx.register">
1516 <element name=
"register">
1520 <define name=
"dbx.instruction">
1521 <element name=
"instruction">
1525 <!-- create a new pattern that contains the new inlines -->
1526 <define name=
"dbx.asm.inlines">
1528 <ref name=
"dbx.register"/>
1529 <ref name=
"dbx.instruction"/>
1532 <!-- add the new inlines to programming and os inlines -->
1533 <define name=
"db.programming.inlines" combine=
"choice">
1534 <ref name=
"dbx.asm.inlines"/>
1536 <define name=
"db.os.inlines" combine=
"choice">
1537 <ref name=
"dbx.asm.inlines"/>
1539 </grammar>]]
></programlisting>
1540 <programlisting dbk:
language=
"rnc"><![CDATA[default namespace db =
"http://docbook.org/ns/docbook"
1542 include
"docbook.rnc"
1543 # define the new elements
1544 dbx.register = element register { text }
1545 dbx.instruction = element instruction { text }
1546 # create a new pattern that contains the new inlines
1547 dbx.asm.inlines = dbx.register | dbx.instruction
1548 # add the new inlines to programming and os inlines
1549 db.programming.inlines |= dbx.asm.inlines
1550 db.os.inlines |= dbx.asm.inlines]]
></programlisting>
1553 <section xml:
id=
"cust-delete-elements">
1554 <title>Deleting elements
</title>
1556 Deleting elements is straightforward, but takes some
1557 care and planning.
<xref dbk:
linkend=
"ex-delete-element"
1558 dbk:
xrefstyle=
"select: label"/> deletes
1559 the
<tag>important
</tag> admonition element by redefining
1560 it with a content model of
<varname>notAllowed
</varname>.
1561 Note that in this example, the redefinition is inside
1562 the
<tag dbk:
condition=
"nolink">include
</tag> element.
1563 This is required for
1564 redefinitions that completely replace an existing pattern.
1567 Be careful; If you delete an element that is a required part
1568 of another element's content model, you can make it
1569 impossible to create a valid document.
1570 For example, if you delete the
<tag>title
</tag>
1571 element, you won't be able to validate a
<tag>book
</tag>
1572 because a
<tag>book
</tag> requires a
<tag>title
</tag>.
1574 <example xml:
id=
"ex-delete-element"><title>Deleting an element
</title>
1575 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1576 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1577 ns=
"http://docbook.org/ns/docbook"
1578 xmlns=
"http://relaxng.org/ns/structure/1.0">
1579 <include href=
"docbook.rng">
1580 <!-- redefine important element as notAllowed -->
1581 <define name=
"db.important">
1585 </grammar>]]
></programlisting>
1586 <programlisting dbk:
language=
"rnc"><![CDATA[namespace db =
"http://docbook.org/ns/docbook"
1588 include
"docbook.rnc" inherit = db {
1589 # redefine important element as notAllowed
1590 db.important = notAllowed
1591 }]]
></programlisting>
1594 <section xml:
id=
"cust-modify-elements">
1595 <title>Customizing the content model of existing elements
</title>
1597 <xref dbk:
linkend=
"ex-modify-element" dbk:
xrefstyle=
"select: label"/>
1598 expands the definition of
<tag>author
</tag> to include two
1599 new elements,
<tag dbk:
condition=
"nolink">born
</tag> and
1600 <tag dbk:
condition=
"nolink">died
</tag>.
1601 The
<tag>author
</tag> element allows two content models,
1602 <varname>db.person.author.contentmodel
</varname>, which
1603 defines an author who is a person, and
1604 <varname>db.org.author.contentmodel
</varname>, which
1605 defines an author that is an organization. We will modify
1606 <varname>db.person.author.contentmodel
</varname> so that
1607 only authors who are persons can have the new elements.
1608 <example xml:
id=
"ex-modify-element"><title>Modifying the content model of an element
</title>
1609 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1610 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1611 ns=
"http://docbook.org/ns/docbook"
1612 xmlns=
"http://relaxng.org/ns/structure/1.0">
1613 <include href=
"docbook.rng"/>
1615 <define name=
"db.person.author.contentmodel" combine=
"interleave">
1618 <element name=
"born">
1619 <ref name=
"db.date.contentmodel"/>
1623 <element name=
"died">
1624 <ref name=
"db.date.contentmodel"/>
1629 </grammar>]]
></programlisting>
1630 <programlisting dbk:
language=
"rnc"><![CDATA[default namespace =
"http://docbook.org/ns/docbook"
1631 namespace db =
"http://docbook.org/ns/docbook"
1633 include
"docbook.rnc"
1635 db.person.author.contentmodel &=
1636 element born { db.date.contentmodel }?
1637 & element died { db.date.contentmodel }?]]
></programlisting>
1641 This modification will allow instances like this:
1642 <programlisting><![CDATA[
<author>
1643 <personname>Babe Ruth
</personname>
1644 <born>02/
06/
1895</born>
1645 <died>08/
16/
1948</died>
1646 </author>]]
></programlisting>
1647 but because we only modified the content model for authors
1648 who are human, it won't allow an instance like this, which
1649 uses
<varname>db.org.author.contentmodel
</varname>:
1650 <programlisting><![CDATA[
<!-- INVALID -->
1652 <orgname>Boston Red Sox
</orgname>
1655 </author>]]
></programlisting>
1659 <section xml:
id=
"cust-attributes">
1660 <title>Attributes
</title>
1661 <section xml:
id=
"cust-add-attributes">
1662 <title>Adding attributes
</title>
1664 The simplest way to add an attribute to a single element
1665 is to add it to the attlist pattern for that element.
1666 <xref dbk:
linkend=
"ex-add-attr" dbk:
xrefstyle=
"select: label"/>
1667 adds the optional attributes
<tag dbk:
class=
"attribute">born
</tag>
1668 and
<tag dbk:
class=
"attribute">died
</tag> to the attribute
1669 list for
<tag>author
</tag>.
1670 The
<varname>db.author.attlist
</varname>
1671 named pattern is redefined with the
1672 <tag dbk:
class=
"attribute">combine
</tag> attribute set to
1673 <quote>interleave
</quote>, which interleaves the two new
1674 optional attributes with the existing attributes on the list.
1676 <example xml:
id=
"ex-add-attr"><title>Adding attributes
</title>
1677 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1678 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1679 ns=
"http://docbook.org/ns/docbook"
1680 xmlns=
"http://relaxng.org/ns/structure/1.0">
1681 <include href=
"docbook.rng"/>
1683 <define name=
"db.author.attlist" combine=
"interleave">
1686 <attribute name=
"born">
1687 <ref name=
"db.date.contentmodel"/>
1691 <attribute name=
"died">
1692 <ref name=
"db.date.contentmodel"/>
1697 </grammar>]]
></programlisting>
1698 <programlisting dbk:
language=
"rnc"><![CDATA[namespace db =
"http://docbook.org/ns/docbook"
1700 include
"docbook.rnc" inherit = db
1702 db.author.attlist &=
1703 attribute born { db.date.contentmodel }?
1704 & attribute died { db.date.contentmodel }?]]
></programlisting>
1708 <xref dbk:
linkend=
"ex-modify-element" dbk:
xrefstyle=
"select: label"/>,
1709 <xref dbk:
linkend=
"ex-add-attr" dbk:
xrefstyle=
"select: label"/> allows
1710 the new attributes to appear on any
<tag>author
</tag>
1711 element, not just those using the person content model.
1714 <xref dbk:
linkend=
"ex-add-attr-2" dbk:
xrefstyle=
"select: label"/> shows
1715 how you could limit the use of these attributes to authors who
1716 are persons. In this example, the new attributes are interleaved
1717 with the
<varname>db.person.author.contentmodel
</varname>.
1718 The only difference between this example and
1719 <xref dbk:
linkend=
"ex-modify-element" dbk:
xrefstyle=
"select: label"/> is
1720 that the added patterns are identified as attributes rather than
1721 elements. This shows some of the flexibility of RELAX NG, which
1722 treats attributes and elements very consistently.
1723 <example xml:
id=
"ex-add-attr-2"><title>Adding attributes; alternate method
</title>
1724 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1725 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1726 ns=
"http://docbook.org/ns/docbook"
1727 xmlns=
"http://relaxng.org/ns/structure/1.0">
1728 <include href=
"docbook.rng"/>
1729 <!-- redefinitions of named patterns -->
1730 <define name=
"db.person.author.contentmodel" combine=
"interleave">
1733 <attribute name=
"born">
1734 <ref name=
"db.date.contentmodel"/>
1738 <attribute name=
"died">
1739 <ref name=
"db.date.contentmodel"/>
1744 </grammar>]]
></programlisting>
1745 <programlisting dbk:
language=
"rnc"><![CDATA[namespace db =
"http://docbook.org/ns/docbook"
1747 include
"docbook.rnc" inherit = db
1748 # redefinitions of named patterns
1749 db.person.author.contentmodel &=
1750 attribute born { db.date.contentmodel }?
1751 & attribute died { db.date.contentmodel }?]]
></programlisting>
1753 There is one difference in the treatment of attributes and elements
1754 that is worth noting. By the XML
1.0 definition, the relative order
1755 of attributes is not significant. Therefore, the
1756 <tag dbk:
condition=
"nolink">interleave
</tag> block is not required for
1757 attributes, though it does no harm.
1760 <section xml:
id=
"cust-delete-attributes">
1761 <title>Deleting attributes
</title>
1763 Deleting an attribute is similar to deleting an element,
1764 except that you use the RELAX NG
<varname>empty
</varname>
1765 pattern rather than
<varname>notAllowed
</varname>.
1766 <xref dbk:
linkend=
"ex-delete-attr" dbk:
xrefstyle=
"select: label"/>
1767 deletes the linking attributes, which are collected in the
1768 <varname>db.common.linking.attributes
</varname> pattern,
1769 by defining that pattern as
<varname>empty
</varname>.
1771 <example xml:
id=
"ex-delete-attr"><title>Deleting an attribute
</title>
1772 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1773 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1774 ns=
"http://docbook.org/ns/docbook"
1775 xmlns=
"http://relaxng.org/ns/structure/1.0">
1776 <include href=
"docbook.rng">
1777 <define name=
"db.common.linking.attributes">
1781 </grammar>]]
></programlisting>
1782 <programlisting dbk:
language=
"rnc"><![CDATA[namespace db =
"http://docbook.org/ns/docbook"
1784 include
"docbook.rnc" inherit = db {
1785 db.common.linking.attributes = empty
1786 }]]
></programlisting>
1789 Generally,
<varname>empty
</varname> is used when deleting
1790 attributes and
<varname>notAllowed
</varname> is used when
1794 <section xml:
id=
"cust-modify-attributes">
1795 <title>Changing permitted content of attributes
</title>
1797 <xref dbk:
linkend=
"ex-modify-attr" dbk:
xrefstyle=
"select: label"/>
1798 modifies
<varname>db.spacing.enumeration
</varname> to
1799 add the additional value
<quote>large
</quote>. Note
1800 that to remove a value from an enumeration, you need
1801 to redefine the entire enumeration, minus the values
1804 <example xml:
id=
"ex-modify-attr"><title>Deleting an attribute
</title>
1805 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
1806 <grammar xmlns:
db=
"http://docbook.org/ns/docbook"
1807 ns=
"http://docbook.org/ns/docbook"
1808 xmlns=
"http://relaxng.org/ns/structure/1.0">
1809 <include href=
"docbook.rng"/>
1810 <!-- add value to an enumeration -->
1811 <define name=
"db.spacing.enumeration" combine=
"choice">
1812 <value>large
</value>
1814 </grammar>]]
></programlisting>
1815 <programlisting dbk:
language=
"rnc"><![CDATA[namespace db =
"http://docbook.org/ns/docbook"
1817 include
"docbook.rnc" inherit = db
1818 # add value to an enumeration
1819 db.spacing.enumeration |=
"large"]]
></programlisting>
1824 <section xml:
id=
"cust-naming">
1825 <title>Naming and versioning DocBook customizations
</title>
1827 <para>DocBook V5.0 is not tightly coupled with some particular
1828 validation technology like DTDs. This also means that DocBook V5.0
1829 documents don't have to (and usually don't) start with a
1830 document type declaration (
<!DOCTYPE…
>) to specify the schema
1831 (DTD) to use. Instead, DocBook V5.0 instances can be easily
1832 distinguished from other XML vocabularies by using elements in the
1833 <uri>http://docbook.org/ns/docbook
</uri> namespace. This namespace is
1834 enough to distinguish DocBook from other XML based formats. But the
1835 DocBook schema evolves over time and there are several versions of
1836 DocBook (e.g.
3.1,
4.2,
4.5 and
5.0). Since DocBook version
5.0, the
1837 actual version used is indicated in the
<tag
1838 dbk:
class=
"attribute">version
</tag> attribute on a root element.
</para>
1840 <programlisting><![CDATA[
<book xmlns=
"http://docbook.org/ns/docbook"
1843 </book>]]
></programlisting>
1845 <para>Future versions of DocBook documents will start with the same
1846 markup, except the version number will be raised, for example to
5.1
1848 The namespace will remain the same until the semantics of the elements
1849 change in a backward incompatible way, which is very unlikely to happen.
</para>
1851 <para>If you create a DocBook schema customization you must change the
<tag
1852 dbk:
class=
"attribute">version
</tag> attribute to distinguish your
1853 customization from the
<quote>official
</quote> DocBook. Changing the
1854 namespace is not recommended because that would break the processing
1855 tools. Remember that changing namespaces is the same as renaming all
1856 elements in the namespace.
</para>
1858 <para>When you customize the schema, use the following syntax to
1859 identify your DocBook derivation:
</para>
1861 <programlisting><replaceable>base_version
</replaceable>-[subset|extension|variant] [
<replaceable>name
</replaceable>[-
<replaceable>version
</replaceable>]?]+
</programlisting>
1863 <para>For example:
</para>
1865 <programlisting>5.0-subset simplified-
1.0
1867 5.0-variant ASMBook-
2006
1868 5.0-extension MathML-
2.0 SVG-
1.1</programlisting>
1870 <para>The first part of the version identifier is the version number of the
1871 DocBook schema from which you derived your customization.
</para>
1873 <para>If your schema is a proper subset, you can advertise this status
1874 by using the
<literal>subset
</literal> keyword in the description. If
1875 your schema contains any markup model extensions, you can advertise
1876 this status by using the
<literal>extension
</literal> keyword. If
1877 you'd rather not characterize your variant specifically as a subset or
1878 an extension, use the
<literal>variant
</literal> keyword.
</para>
1880 <para>After these keywords you may add a whitespace separated list of
1881 customization identifiers. Each name may be optionally followed by its
1882 version number.
</para>
1888 <section xml:
id=
"faq">
1893 <title>Authoring
</title>
1895 <qandaentry xml:
id=
"faq-authoring-schema-association">
1897 <para>How do I attach a schema to a DocBook V5.0 document when I do not
1898 want to use DTDs and !DOCTYPE?
</para>
1901 <para>There is no standard way of associating a RELAX NG schema with a
1902 document. Most tools provide some mechanism for performing this
1903 association, consult the documentation for your application. In some
1904 tools you must specify schema manually each time you want to
1905 edit/process your document.
</para>
1909 <qandaentry xml:
id=
"faq-authoring-general-entities">
1911 <para>How do I use entities like
<tag dbk:
class=
"genentity">ndash
</tag> in
1912 DocBook V5.0?
</para>
1915 <para>Modern schema languages (including RELAX NG and W3X XML Schema)
1916 do not provide any means to define entities that can be used for easier
1917 typing of special characters. Some editors provide functions or
1918 special toolbars that allow you to easily pick necessary character
1919 and insert it into document as a raw Unicode character or a numeric
1920 character reference.
</para>
1921 <para>Another possibility is to include entity definitions in the
1922 prolog of your document.
<link
1923 xl:
href=
"http://www.w3.org/2003/entities/">Entity definition
1924 files
</link> are now maintained by W3C. You can reference definition
1925 files with entity definitions you are interested in and then reference
1926 imported entities. For example:
</para>
1927 <programlisting><![CDATA[
<?xml version=
"1.0" encoding=
"utf-8"?>
1929 <!ENTITY % isopub SYSTEM
"http://www.w3.org/2003/entities/iso8879/isopub.ent">
1932 <article xmlns=
"http://docbook.org/ns/docbook" version=
"5.0">
1933 <title>DocBook V5.0
– the superb documentation format
</title>]]
>
1935 <para>For your convenience there is also flattened entity definition
1936 file which contains all entity definitions.
</para>
1937 <programlisting><![CDATA[
<?xml version=
"1.0" encoding=
"utf-8"?>
1939 <!ENTITY % allent SYSTEM
"http://www.w3.org/2003/entities/2007/w3centities-f.ent">
1942 <article xmlns=
"http://docbook.org/ns/docbook" version=
"5.0">
1943 <title>DocBook V5.0
– the superb documentation format
</title>]]
>
1948 <qandaentry xml:
id=
"faq-authoring-modularization">
1950 <para>How to modularize documents?
</para>
1953 <para>You can use
<link
1954 xl:
href=
"http://www.w3.org/TR/xinclude/">XInclude
</link> for this
1955 task. There is an alternative schema for DocBook V5.0 that
1956 contains XInclude elements. This is necessary to make some XML editors
1957 happy. This schema can be found in files that end with letters
<quote>xi
</quote>, e.g.
1958 <filename>docbookxi.rnc
</filename> instead of
1959 <filename>docbook.rnc
</filename>.
</para>
1963 <qandaentry xml:
id=
"faq-authoring-validating-xincludes">
1965 <para>How to validate documents which are composed by XInclude?
</para>
1968 <para>If you are using XIncludes you should make sure that the final
1969 document after resolving all inclusions is valid DocBook V5.0
1970 instance. This means that all XIncludes should be processed before
1971 validation takes place. The following command can be used to enable
1972 XInclude processing in oNVDL.
</para>
1973 <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>
1974 <para>For JNVDL you can use switch
<option>-xi
</option> to enable XInclude processing.
</para>
1981 <title>Stylesheets
</title>
1983 <qandaentry xml:
id=
"faq-stylesheets-future">
1985 <para>Will the current DocBook XSL stylesheets (XSLT
1.0 based
1986 implementation) be maintained and improved in the future since work on
1987 a new XSLT
2.0 based implementation has started?
</para>
1990 <para>Yes, the current stylesheets (like
1.73.x) will be supported and
1991 improved further because they are very widely deployed and work with
1992 many existing XSLT processors.
</para>
1993 <para>Surely there will be a point in a future when all new development
1994 will be switched to the XSLT
2.0 based implementation. But this
1995 will not happen until all features of the current stylesheets are
1996 implemented in the new stylesheets, and until there is more than
1997 one usable XSLT
2.0 processor available.
</para>
2004 <title>Schema customizations
</title>
2006 <qandaentry xml:
id=
"faq-customization-mathml">
2008 <para>How can I extend the DocBook schema with MathML elements?
</para>
2011 <para>The basic DocBook schema allows elements from the MathML namespace
2012 to appear inside the
<tag>equation
</tag> element. This means that you can
2013 validate a DocBook+MathML document, but MathML content will be ignored
2014 during the validation. You will also not be able to use guided editing
2015 for the MathML content.
</para>
2016 <para>If you need strict validation of MathML content or guided
2017 editing for MathML, you can easily extend the base DocBook schema with
2018 the MathML schema.
</para>
2020 <title>Extending the DocBook schema with the MathML schema
</title>
2022 <para>Download the MathML RELAX NG schema from
<link
2023 xl:
href=
"http://yupotan.sppd.ne.jp/relax-ng/mml2.html"/> and unpack it
2024 somewhere (e.g. into a
<filename>mathml
</filename> subdirectory).
</para>
2027 <para>Create a schema customization in compact syntax—
<filename>dbmathml.rnc
</filename>:
</para>
2028 <programlisting dbk:
language=
"rnc">namespace html =
"http://www.w3.org/1999/xhtml"
2029 namespace mml =
"http://www.w3.org/1998/Math/MathML"
2030 namespace db =
"http://docbook.org/ns/docbook"
2032 include
"/path/to/docbook.rnc" {
2033 db._any.mml = external
"mathml/mathml2.rnc"
2035 element * - (db:* | html:* | mml:*) {
2036 (attribute * { text }
2041 <para>Or, alternatively, you can use the XML syntax of RELAX NG—
<filename>dbmathml.rng
</filename>:
</para>
2042 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
2043 <grammar xmlns=
"http://relaxng.org/ns/structure/1.0">
2045 <include href=
"/path/to/docbook.rng">
2046 <define name=
"db._any.mml">
2047 <externalRef href=
"mathml/mathml2.rng"/>
2050 <define name=
"db._any">
2054 <nsName ns=
"http://docbook.org/ns/docbook"/>
2055 <nsName ns=
"http://www.w3.org/1999/xhtml"/>
2056 <nsName ns=
"http://www.w3.org/1998/Math/MathML"/>
2065 <ref name=
"db._any"/>
2072 </grammar>]]
></programlisting>
2075 <para>Now use the customized schema (
<filename>dbmathml.rnc
</filename>
2076 or
<filename>dbmathml.rng
</filename>) instead of the original
2077 DocBook schema.
</para>
2083 <qandaentry xml:
id=
"faq-customization-svg">
2085 <para>How can I extend the DocBook schema with SVG elements?
</para>
2088 <para>The situation is the same as with MathML support. You can use
2089 elements from the SVG namespace inside the
<tag>imageobject
</tag>
2092 <title>Extending the DocBook schema with the SVG schema
</title>
2094 <para>Download the SVG RELAX NG schema from
<link
2095 xl:
href=
"http://www.w3.org/Graphics/SVG/1.1/rng/rng.zip"/> and unpack it
2096 somewhere (e.g. into an
<filename>svg
</filename> subdirectory).
</para>
2099 <para>Create a schema customization in compact syntax—
<filename>dbsvg.rnc
</filename>:
</para>
2100 <programlisting dbk:
language=
"rnc">namespace html =
"http://www.w3.org/1999/xhtml"
2101 namespace db =
"http://docbook.org/ns/docbook"
2102 namespace svg =
"http://www.w3.org/2000/svg"
2104 include
"/path/to/docbook.rnc" {
2105 db._any.svg = external
"svg/svg11.rnc"
2107 element * - (db:* | html:* | svg:*) {
2108 (attribute * { text }
2113 <para>Or, alternatively, you can use the XML syntax of RELAX NG—
<filename>dbsvg.rng
</filename>:
</para>
2114 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
2115 <grammar xmlns=
"http://relaxng.org/ns/structure/1.0">
2117 <include href=
"/path/to/docbook.rng">
2118 <define name=
"db._any.svg">
2119 <externalRef href=
"svg/svg11.rng"/>
2122 <define name=
"db._any">
2126 <nsName ns=
"http://docbook.org/ns/docbook"/>
2127 <nsName ns=
"http://www.w3.org/1999/xhtml"/>
2128 <nsName ns=
"http://www.w3.org/2000/svg"/>
2137 <ref name=
"db._any"/>
2144 </grammar>]]
></programlisting>
2147 <para>Now use the customized schema (
<filename>dbsvg.rnc
</filename>
2148 or
<filename>dbsvg.rng
</filename>) instead of the original
2149 DocBook schema.
</para>
2155 <qandaentry xml:
id=
"faq-customization-mathml-svg">
2157 <para>Is it possible to use the previous two customizations for MathML
2158 and SVG together?
</para>
2161 <para>Yes, you can create a special schema customization that combines
2162 both MathML and SVG with the DocBook schema. In compact syntax, the merged
2164 <programlisting dbk:
language=
"rnc">namespace html =
"http://www.w3.org/1999/xhtml"
2165 namespace mml =
"http://www.w3.org/1998/Math/MathML"
2166 namespace db =
"http://docbook.org/ns/docbook"
2167 namespace svg =
"http://www.w3.org/2000/svg"
2169 include
"/path/to/docbook.rnc" {
2170 db._any.mml = external
"mahtml/mathml2.rnc"
2171 db._any.svg = external
"svg/svg11.rnc"
2173 element * - (db:* | html:* | mml:* | svg:*) {
2174 (attribute * { text }
2179 <para>Or alternatively in the full RELAX NG syntax:
</para>
2180 <programlisting dbk:
language=
"rng"><![CDATA[
<?xml version=
"1.0" encoding=
"UTF-8"?>
2181 <grammar xmlns=
"http://relaxng.org/ns/structure/1.0">
2183 <include href=
"/path/to/docbook.rng">
2184 <define name=
"db._any.mml">
2185 <externalRef href=
"mathml/mathml2.rng"/>
2188 <define name=
"db._any.svg">
2189 <externalRef href=
"svg/svg11.rng"/>
2192 <define name=
"db._any">
2196 <nsName ns=
"http://docbook.org/ns/docbook"/>
2197 <nsName ns=
"http://www.w3.org/1999/xhtml"/>
2198 <nsName ns=
"http://www.w3.org/1998/Math/MathML"/>
2199 <nsName ns=
"http://www.w3.org/2000/svg"/>
2208 <ref name=
"db._any"/>
2215 </grammar>]]
></programlisting>
2219 <qandaentry xml:
id=
"faq-customization-links">
2221 <para>Are there any other examples of schema customization
2225 <para>Sure. Some of the are listed bellow:
</para>
2227 <listitem><para><link
2228 xl:
href=
"http://www.w3.org/TR/xml-i18n-bp/#docbook-plus-its">Sample
2229 customization of ITS and DocBook
</link></para></listitem>
2230 <listitem><para><link
2231 xl:
href=
"http://wiki.docbook.org/topic/DocbookSchemas">Examples on
2232 DocBook WiKi
</link></para></listitem>
2240 <title>Tool specific problems
</title>
2242 <qandaentry xml:
id=
"faq-tools-xmlspy-xmlid">
2244 <para>I'm using Altova XMLSpy to validate DocBook V5.0 instances
2245 against the W3C XML Schema (
<filename>docbook.xsd
</filename>). XMLSpy
2246 complains about undefined
<tag dbk:
class=
"attribute">xml:id
</tag>
2250 <para>XMLSpy always uses its own bundled version of
2251 <filename>xml.xsd
</filename> which unfortunately doesn't define the
<tag
2252 dbk:
class=
"attribute">xml:id
</tag> attribute. The bundled version of
2253 <filename>xml.xsd
</filename> is hardwired into the program and cannot
2254 be replaced by a newer version. To solve this problem you must upgrade
2255 to version
2006 SP1.
</para>
2264 <bibliography xml:
id=
"references">
2267 <abbrev>RNCTUT
</abbrev>
2268 Clark, James – Cowan, John – MURATA, Makoto:
<title>RELAX NG Compact Syntax Tutorial
</title>.
2269 Working Draft,
26 March
2003. OASIS.
<bibliomisc><link xl:
href=
"http://relaxng.org/compact-tutorial-20030326.html"/></bibliomisc>
2273 <abbrev>NVDLTUT
</abbrev>
2275 <title>NVDL Tutorial
</title>.
2276 <bibliomisc><link xl:
href=
"http://jnvdl.sourceforge.net/tutorial.html"/></bibliomisc>
2280 <abbrev>XMLID
</abbrev>
2283 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>
2287 <abbrev>DB5SPEC
</abbrev>
2288 Norman, Walsh:
<title>The DocBook Schema
</title>.
2289 Working Draft
5.0a1, OASIS,
29 June
2005.
2290 <bibliomisc><link xl:
href=
"http://www.docbook.org/specs/wd-docbook-docbook-5.0a1.html"/></bibliomisc>
projects / lgpl / argeo-commons.git / blob