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 section devoted to conversion of legacy documents from DocBook
+also a section devoted to conversion of legacy documents from DocBook
4.x to DocBook V5.0.</para>
-<para>At the time of this writing the current version of DocBook V5.0
-was &version;. However, almost all information in this document is
-general and it is applicable to any newer version in DocBook V5.0
-series.</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
+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
<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
+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
<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
+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
'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
<article lang="en">
<title>Sample article</title>
- <para>This is really very short article.</para>
+ <para>This is a very short article.</para>
</article>]]></programlisting>
</example>
<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 really very short article.</para>
+ <para>This is a very short article.</para>
</article>]]></programlisting>
</example>
<itemizedlist>
<listitem>
-<para><emphasis>DocBook V4.x is feature frozen.</emphasis> At the time
-of this writing 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>
+<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> Even
-the current version of 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>
+<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
+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.</para>
+than it would be using a DTD (see <xref linkend="customizations"/>).</para>
</listitem>
</itemizedlist>
<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
+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 DTDs nor XML schemas are able to
+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
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 constrainst can't be expressed in schema languages
+<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. It is recommended to
-validate your document not only against RELAX NG schema but also
-against Schematron schema.</para>
+constraints DocBook V5.0 uses Schematron. We recommend that you
+validate your document against both the RELAX NG and
+Schematron schemas.</para>
<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 of this
-writing the latest version is &version; and individual schemas are
+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>
of <citetitle>DocBook: The Definitive Guide</citetitle></link>.</para>
<note>
-<para>Other parts of the book have not yet been updated to reflect the
-changes made in DocBook V5.0. Please do not be confused by
-this.</para>
+<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 xml:id="editors">
<title>Editing DocBook V5.0</title>
-<para>Because DocBook is an XML based format and XML is a text based
+<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
</note>
<para>If you can't edit the global <filename>schemas.xml</filename> file,
-you can create this file in a directory with your document. nXML will
+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>
</figure>
<para>Now you can close the preference box by clicking on the
-<guibutton>OK</guibutton> button. From this time oXygen will assist
-you with writing DocBook V5.0 content and you will be able to validate
+<guibutton>OK</guibutton> button. 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">
</figure>
<para>In order to use DocBook V5.0 in XXE you have to install
-correspoding add-on. Go to
+an add-on. Go to
<menuchoice><guimenu>Options</guimenu><guimenuitem>Install
Add-ons…</guimenuitem></menuchoice>. Then choose <guilabel>DocBook
-5 configuration</guilabel> and press <guibutton>OK</guibutton>
-button. After restart XXE is ready to work with DocBook V5.0
+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 xml:id="validators">
<title>Validating DocBook V5.0</title>
-<para>If you are not using a RELAX NG based validating editor when you
+<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 you can be sure that your
+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
-those two schemas.</para>
+the two schemas.</para>
<section xml:id="validators-rng-sch">
<title>Using RELAX NG and Schematron</title>
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 other error
+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
<section>
<title>Using NVDL</title>
-<para>NVDL is a metaschema language which can send a document to
-validation against several schemas. DocBook V5.0 comes with a NVDL
-schema which defines that DocBook documents should be validated
+<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 <application
+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>
with some limitations.</para>
<para>You can process DocBook V5.0 documents with the DocBook XSL
-stylesheets in exactly the same way as you process DocBook V4.x documents.
-You do not need special software, you can stick to your preferred
+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>
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 5) documents.</para>
+namespaced (DocBook V5.0) documents.</para>
</section>
<section xml:id="dbxsl2">
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>
+<listitem><para>easy to customize titlepage templates.</para></listitem>
</itemizedlist>
<para>The XSLT 2.0 based stylesheets are still under development. At
<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"/>
+xl:href="http://docbook.sourceforge.net/snapshots/docbook-xsl2-snapshot.tar.bz2"/>
and unpack it somewhere. Then download and install Saxon 9 from <link
xl:href="http://saxon.sf.net"/>.</para>
two new inline elements for writing about assembly language,
<tag condition="nolink">register</tag> and
<tag condition="nolink">instruction</tag>.
- We will allow them whereever programming inlines
+ We will allow them wherever programming inlines
or operating system inlines are allowed.
<xref linkend="ex-add-element-2" xrefstyle="select: label"/>
defines the two elements, creates a new named pattern
a new XSLT 2.0 based implementation has started?</para>
</question>
<answer>
-<para>Yes, the current stylesheets (like 1.69.1) will be supported and
+<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
+implemented in the new stylesheets, and until there is more than
one usable XSLT 2.0 processor available.</para>
</answer>
</qandaentry>
projects / docbook-dsssl / commitdiff