[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: The first draft of DB5 how-to
Hi,
attached is the first draft of transition guide for DocBook V5.0. If you
would like to see rendered (albeit not yet very fancy) version go to:
http://kosek.cz/temp/dbng-howto.html
http://kosek.cz/temp/dbng-howto.pdf
Comments are more then welcome. I'm CC'ing Mike Smith because he has
been using DocBook NG for a long period and can provide useful feedback
and ideas.
I will really appreciate if some native speaker can do proofreading. Any
volunteers?
Extensive section about customizations is missing, I might have time for
finishing it during the next month.
During writing of this text I found two things that should be sorted out
before we release the first alpha of DocBook V5.0.
* Draft of DocBook V5.0 specification points to address
http://docbook.org/rng/ where schemas should be, but aren't.
* We should decide on locations where particular schemas (DTD, RNG, WXS)
will be available and mention these locations in how-to.
I also started thinking about the best way to publish this how-to.
Should we publish it as an TC outcome on OASIS site? Or on
docbook.sf.net or docbook.org? Actually I would like to publish it
somewhere where can I easily update it. Of course I can always publish
it on my site, where I can easily modify it. I just like to know your
opinions.
Jirka
--
------------------------------------------------------------------
Jirka Kosek e-mail: jirka@kosek.cz http://www.kosek.cz
------------------------------------------------------------------
Profesionální školení a poradenství v oblasti technologií XML.
Podívejte se na náš nově spuštěný web http://DocBook.cz
Podrobný přehled školení http://xmlguru.cz/skoleni/
------------------------------------------------------------------
Nejbližší termíny školení: DocBook 5.-7.12. * XSL-FO 19.-20.12.
XSLT 17.-20.10. * XML schémata (včetně RELAX NG) 7.-9.11.
------------------------------------------------------------------
<?xml version="1.0" encoding="utf-8"?>
<article xmlns="http://docbook.org/ns/docbook"; xmlns:xl="http://www.w3.org/1999/xlink"; version="pto" xml:lang="en">
<info>
<title>DocBook V5.0</title>
<subtitle>The Transition Guide</subtitle>
<authorgroup>
<author><personname>Jirka Kosek</personname><email>jirka@kosek.cz</email></author>
<author><personname>Norman Walsh</personname><email>ndw@nwalsh.com</email></author>
</authorgroup>
</info>
<para>This document is targeted at DocBook users who are considering
switch from DocBook V4.x to a new DocBook version 5.0. You will find
here information about differences between DocBook V4.x and V5.0, you
will learn how to edit and process DocBook V5.0 documents. There is
also section devoted to conversion of legacy documents from DocBook
4.x to DocBook V5.0.</para>
<section xml:id="introduction">
<title>Introduction</title>
<para>Differences between DocBook V5.0 and V4.x are quite radical in
some aspects, but basic idea behind DocBook is still the same and
almost all element names are unchanged. Because of this it is very
easy to get familiar with DocBook V5.0 if you know previous version of
DocBook. You can find complete list of changes in
<citation>DB5SPEC</citation> here we will discuss only the most
fundamental changes.</para>
<section xml:id="introduction-ns">
<title>Finally in namespace</title>
<para>All DocBook V5.0 elements are in namespace
<uri>http://docbook.org/ns/docbook</uri>. <acronym>XML<alt>eXtensible
Markup Language</alt></acronym> namespaces allow to distinguish
between different element sets. In the last few years almost all new
XML grammars are using its own namespace. Thanks to this it is easy to
create compound documents that contain elements from different XML
vocabularies. DocBook V5.0 is following this design rule. Using
namespaces in your documents is very easy. Consider that you have
simple article marked up in DocBook V4.5:</para>
<programlisting><![CDATA[<article>
<title>Sample article</title>
<para>This is really very short article.</para>
</article>]]></programlisting>
<para>Corresponding DocBook V5.0 article will look very similarly:</para>
<programlisting><![CDATA[<article xmlns="http://docbook.org/ns/docbook"; …>
<title>Sample article</title>
<para>This is really very short article.</para>
</article>]]></programlisting>
<para>Only change is added default namespace declaration
(<code>xmlns="http://docbook.org/ns/docbook";</code>) on the root
element. This declaration is propagated to all nested elements. Each
element is now uniquely identified by its name and namespace.</para>
<note>
<para>Namespace name <uri>http://docbook.org/ns/docbook</uri> serves
only as an identifier. This resource is not fetched during processing
of DocBook document and your are not required to have Internet
connection during processing. Because people are curious and are
trying to access this URL using browser, there is a short explanatory
document published.</para>
</note>
</section>
<section xml:id="introduction-rng">
<title>Relaxing with DocBook</title>
<para>For more then decade DocBook schema was defined using
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 more cleaner and
precise.</para>
<para>Use of RELAX NG has impact on document prolog. The following
example shows typical prolog of DocBook V4.x document. Version of
DocBook DTD (in this case 4.5) is indicated in the document type
declaration (!DOCTYPE) which is pointing to a particular version of
DTD.</para>
<example>
<title>DocBook V4.5 document</title>
<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
<article lang="en">
<title>Sample article</title>
<para>This is really very short article.</para>
</article>]]></programlisting>
</example>
<para>In contrast, DocBook V5.0 is not depending on DTDs anymore. This
mean that there is no document type declaration and version of DocBook
used is indicated by <tag class="attribute">version</tag>
attribute instead.</para>
<example>
<title>DocBook V5.0 document</title>
<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<article xmlns="http://docbook.org/ns/docbook"; version="5.0" xml:lang="en">
<title>Sample article</title>
<para>This is really very short article.</para>
</article>]]></programlisting>
</example>
<para>As you can see DocBook V5.0 is built on top of existing XML
standards as much as possible and <tag class="attribute">lang</tag>
attribute is superseded by standardized <tag
class="attribute">xml:lang</tag> attribute.</para>
<para>Another fundamental change here is that there is no direct indication
of schema used. Later in this document you will learn how you can
specify schema used for document validation.</para>
<note>
<para>Although it is recommended to use RELAX NG schema with DocBook V5.0, there are
also DTD and W3C XML Schema available (see <xref linkend="schemas"/>) to
satisfy tools that are not yet supporting RELAX NG.</para>
</note>
</section>
<section xml:id="introduction-why-to-switch">
<title>Why to switch to DocBook V5.0</title>
<para>The simple answer is <quote>Because DocBook V5.0 is the
future.</quote> Apart from this marketing blurb there are also more
technical reasons:</para>
<itemizedlist>
<listitem>
<para><emphasis>DocBook V4.x was feature frozen.</emphasis> At the time
of this writing DocBook V4.5 was the last version of DocBook in V4.x
series. Any new DocBook development like addition of new elements is
done only on DocBook V5.0. It is only matter of time when new useful
element will be added into DocBook V5.0 but will not be back ported
into DocBook V4.x. However DocBook V4.x will be in a maintainance 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,
new and flexible system for linking, …</para>
</listitem>
<listitem>
<para><emphasis>DocBook V5.0 is more extensible.</emphasis> Having
DocBook V5.0 in a separate namespace allows you to easily mix DocBook
markup with other XML based languages like SVG, MathML, XHTML or even
FooBarML.</para>
</listitem>
<listitem>
<para><emphasis>DocBook V5.0 is easier to customize.</emphasis> RELAX
NG offers bunch of very powerful constructs that make customizing
existing DocBook schema very easy. Now it is much easier to create
customized DocBook version then before with DTDs.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="introduction-schemas">
<title>Schema jungle</title>
<para>Schemas for DocBook V5.0 are available in several formats at
<link xl:href="FIXME: add link"/>. Only RELAX NG schema is normative
and it is preferred over other schema languages. However for your
convenience there are also DTD and W3C XML Schema provided for DocBook
5.0. But please note that neither DTDs, nor XML schemas are able to
capture all restrictions expressed in RELAX NG. This mean that
document that validates against DTD or XML schema is not necessarily
valid against RELAX NG schema and thus can't be considered valid
DocBook V5.0 document.</para>
<para>DTD and XML schema versions of DocBook V5.0 grammar are provided
as convenience for users who want to use DocBook V5.0 with legacy tools
that don't support RELAX NG. It is very recommended to switch to RELAX
NG based tools as soon as possible or at least to validate documents
against RELAX NG schema before further processing.</para>
<section xml:id="schemas">
<title>Where to get schemas</title>
<para>The latest versions of schemas can be obtained from the
following locations:</para>
<variablelist>
<varlistentry>
<term>RELAX NG schema</term>
<listitem><para><link xl:href="FIXME:"/></para></listitem>
</varlistentry>
<varlistentry>
<term>RELAX NG schema in compact syntax</term>
<listitem><para><link xl:href="FIXME:"/></para></listitem>
</varlistentry>
<varlistentry>
<term>DTD</term>
<listitem><para><link xl:href="FIXME:"/></para></listitem>
</varlistentry>
<varlistentry>
<term>W3C XML Schema</term>
<listitem><para><link xl:href="FIXME:"/></para></listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>DocBook documentation</title>
<para>Detailed documentation about each DocBook V5.0 element is
presented in <link
xl:href="http://docbook.org/tdg5/en/html/pt02.html";>the reference part
of <citetitle>DocBook: The Definitive Guide</citetitle></link>.</para>
<note>
<para>Other parts of book then reference are not reflecting changes
made in DocBook V5.0. Please do not get confused by this.</para>
</note>
</section>
</section>
</section>
<section xml:id="tools">
<title>Toolchain</title>
<para>There are a lot of questions concerning tools that are able to
work with DocBook V5.0 documents. The aim of this sections is to
shortly describe tools and procedures that should be used to edit and
process content stored in DocBook V5.0.</para>
<section xml:id="editors">
<title>Editing DocBook V5.0</title>
<para>Because DocBook is XML based format and XML is 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 much more better if you use editor
that comes with some XML support. As there are DTD and W3C XML Schemas
available for DocBook V5.0 you can configure your favorite editor to
use these schemas. But as we said already it is recommended to use
RELAX NG grammar with DocBook V5.0. The rest of this section contains
an overview of XML editors (listed in alphabetical order) that support
guided editing based on RELAX NG schema.</para>
<section xml:id="editors-nxml">
<title>Emacs and nXML</title>
<para><link xl:href="http://www.thaiopensource.com/nxml-mode/";>nXML
mode</link> is an addon for <application
xl:href="http://www.gnu.org/software/emacs/emacs.html";>GNU
Emacs</application> text editor. By installing nXML you can turn Emacs
into a very powerful XML editor which will offer guided editing and
validation of XML documents.</para>
<figure>
<title>Emacs with nXML mode is providing guided editing and validation</title>
<mediaobject>
<imageobject>
<imagedata fileref='emacs.png' width="100%"/>
</imageobject>
</mediaobject>
</figure>
<para>nXML uses special configuration file named
<filename>schemas.xml</filename> to associate schemas with XML
documents. Often you will find this file in directory
<filename>site-lisp/nxml/schema</filename> inside Emacs installation
directory. By adding the following line into the configuration file
you will associate DocBook V5.0 elements with appropriate
schema:</para>
<programlisting><namespace ns="http://docbook.org/docbook-ng"; uri="<replaceable>/path/to/</replaceable>docbook.rnc"/></programlisting>
<note>
<para>Please note that nXML is already shipped with file
<filename>docbook.rnc</filename>. This file contains RELAX NG grammar
of DocBook V4.x. So be sure that you associate DocBook V5.0 namespace
with corresponding DocBook V5.0 grammar.</para>
</note>
<para>If you can't edit global <filename>schemas.xml</filename> file,
you can create this file in a directory with your document. nXML will
find associations placed here also. In this case you must create
complete configuration file like:</para>
<programlisting><locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0";>
<namespace ns="http://docbook.org/docbook-ng"; uri="<replaceable>/path/to/</replaceable>docbook.rnc"/>
</locatingRules></programlisting>
</section>
<section xml:id="editors-oxygen">
<title>oXygen</title>
<para><application
xl:href="http://www.oxygenxml.com/";>oXygen</application> is a feature
rich XML editor. It has built in support for many schema languages
including RELAX NG. If you want to smoothly edit and validate DocBook
5.0 documents you should associate DocBook namespace with the
corresponding schema. Go to
<menuchoice><guimenu>Options</guimenu><guisubmenu>Preferences…</guisubmenu><guisubmenu>Editor</guisubmenu><guimenuitem>Default
Schema Associations</guimenuitem></menuchoice>. Then click
<guibutton>New</guibutton> button to add new association. Type in the
DocBook namespace, RELAX NG compact syntax schema location and choose
appropriate type of schema and confirm it by pressing
<guibutton>OK</guibutton>.</para>
<figure>
<title>Adding new schema association in oXygen</title>
<mediaobject>
<imageobject>
<imagedata fileref='oxygen1.png'/>
</imageobject>
</mediaobject>
</figure>
<para>Because oXygen comes with some preconfigured associations for
DocBook V4.x you must move (using <guibutton>Up</guibutton> button)
newly added one to the top of the list. That way you will be able to use
oXygen with both DocBook V4.x and DocBook V5.0.</para>
<figure>
<title>DocBook V5.0 association must precede associations for DocBook V4.x</title>
<mediaobject>
<imageobject>
<imagedata fileref='oxygen2.png'/>
</imageobject>
</mediaobject>
</figure>
<para>Now you can close preference by clicking on
<guibutton>OK</guibutton> button.</para>
<figure>
<title>DocBook V5.0 document opened in oXygen</title>
<mediaobject>
<imageobject>
<imagedata fileref='oxygen3.png' width="100%"/>
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="editors-xxe">
<title>XML Mind XML editor</title>
<para><application xl:href="http://www.xmlmind.com/xmleditor/";>XML
Mind XML editor</application> (XXE) is a visual validating XML editor that is
providing word-processor like interface to users. It is available in
two versions – Standard and Professional. Standard version is free and
provides everything you need to edit DocBook V5.0 documents.</para>
<figure>
<title>XML Mind XML Editor – feels almost like MS Word but real DocBook V5.0 markup is created</title>
<mediaobject>
<imageobject>
<imagedata fileref='xxe.png' width="100%"/>
</imageobject>
</mediaobject>
</figure>
<para>Since version 2.11 XXE comes with bundled DocBook V5.0
configuration. Unfortunately this configuration is not enabled by
default. You must copy content of the directory
<filename><replaceable>XXE_install_dir</replaceable>/doc/rnsupport/config/docbook5/</filename>
into
<filename><replaceable>XXE_install_dir</replaceable>/addon/config/docbook5/</filename>
in order to activate it. After restart of XXE you will be able to
create (template for article is provided) and edit DocBook V5.0
documents.</para>
<para>RELAX NG schema provided with XXE can be outdated. If you want
to use XXE with the latest schema just grab fresh copy of the
<filename>docbook.rng</filename> and copy it over
<filename><replaceable>XXE_install_dir</replaceable>/addon/config/docbook5/docbook.rng</filename>.</para>
</section>
</section>
<section xml:id="validators">
<title>Validating DocBook V5.0</title>
<para>If you are not using RELAX NG based validating editor when you
are creating documents it is highly recommended to validate your
documents before processing. Only after successful validation you can be
sure that your document is really DocBook V5.0 and that processing
tools will be able to process it correctly.</para>
<para>You can find list of RELAX NG validators at <link
xl:href="http://relaxng.org/#validators"/>. For example to validate
your document using <link
xl:href="http://www.davidashen.net/rnv.html";>RNV validator</link> you
must type the following command:</para>
<screen><command>rnv</command> <replaceable>/path/to/</replaceable>docbook.rnc document.xml</screen>
</section>
<section xml:id="processing">
<title>Processing DocBook V5.0</title>
<para>The great success of DocBook is caused by availability of free
tools that can be used to transform DocBook content into various
target formats including HTML and PDF. DocBook XSL Stylesheets are
the number one between such tools.</para>
<section xml:id="dbxsl">
<title>DocBook XSL Stylesheets</title>
<para>The DocBook stylesheets are written in a quite general way so
they always been able to process content written in different versions of
DocBook (for example 3.1 and 4.2). Recent versions of the stylesheets
are also able to process DocBook V5.0 albeit with some
limitations.</para>
<para>You can process DocBook V5.0 document with DocBook XSL
stylesheets in the exactly same way as DocBook V4.x document. There is
no need for a new special software, you can stick to you preferred
XSLT processor be it Saxon, xsltproc, Xalan or whatever else.</para>
<para>During document processing the stylesheets are striping
namespaces from DocBook V5.0 in order to get document which will be
very similar to DocBook V4.x. This is necessary because from the XSLT
point of view elements from different namespaces are distinct and can
not be easily processed by the same set of templates. This process is
completely transparent to user. If you are processing DocBook V5.0
document with the stylesheets you will only see the following
additional message:</para>
<screen>Stripping NS from DocBook 5/NG document.
Processing stripped document.</screen>
<para>Although you can successfully use existing stylesheets to
process DocBook V5.0 there are some limitations. Some new features of
DocBook V5.0 would require very complex rewrite of the stylesheets in
order to support them. This is unlikely to happen because completely
new version of stylesheets is currently being written from
scratch. Examples of such unsupported features are:</para>
<itemizedlist>
<listitem><para>general annotations;</para></listitem>
<listitem><para>general XLink links on all elements;</para></listitem>
<listitem><para>FIXME: what more?</para></listitem>
</itemizedlist>
<para>During namespace stripping base URI of document is lost. This
means that in rare situations relatively referenced resources like
images or programlistings can be processed incorrectly.</para>
</section>
<section xml:id="dbxsl2">
<title>XSLT 2.0 based reimplementation</title>
<para>XSLT 1.0 is missing some important features and to overcome this
limitation current the DocBook XSL stylesheets use several implementation
specific extensions. Fortunately authors of new XSLT version 2.0 were
listening to these limitations and XSLT 2.0 adds many new and
previously missing features into language. Because there was time
correlation between designing DocBook V5.0 and finalizing XSLT 2.0
language, DocBook stylesheets developers decided to completely rewrite
existing XSLT 1.0 based stylesheets using XSLT 2.0. New stylesheets
are designed to process DocBook V5.0 documents with all new
features.</para>
<para>New design of stylesheets and new functionalities of XSLT 2.0
allowed developers to integrate many new features into
the stylesheets. Some of them are:</para>
<itemizedlist>
<listitem><para>seamless integration of profiling (conditional
documents) with external bibliographies and
glossaries;</para></listitem>
<listitem><para>no need for external extensions;</para></listitem>
<listitem><para>internationalized indexes;</para></listitem>
<listitem><para>easy to customize titlepage templates;</para></listitem>
<listitem><para>FIXME: more?</para></listitem>
</itemizedlist>
<para>The back side of XSLT 2.0 based stylesheets reimplementation is
that it is not finished yet and that there are not so many XSLT 2.0
implementations on the market. Currently the stylesheets are
supporting only HTML and chunked HTML output. Other output formats are
planned but do not expect them very soon because of limited free time
of stylesheets developers.</para>
<para>But if you want to taste new stylesheets you of course can. Just
grab snapshot of development version of the stylesheets from <link
xl:href="http://docbook.sourceforge.net/snapshots/docbook-xsl2-snapshot.zip"/>
and unpack it somewhere. Then download and install Saxon 8 from <link
xl:href="http://saxon.sf.net"/>.</para>
<para>To transform DocBook V5.0 document to a single HTML page you can
then use command:</para>
<screen><command>java</command> -jar <replaceable>/path/to/</replaceable>saxon8.jar -o output.html document.xml <replaceable>/path/to/</replaceable>docbook-xsl2-snapshot/html/docbook.xsl</screen>
<para>To transform DocBook V5.0 document to a set of chunked HTML pages you can
then use command:</para>
<screen><command>java</command> -jar <replaceable>/path/to/</replaceable>saxon8.jar document.xml <replaceable>/path/to/</replaceable>docbook-xsl2-snapshot/html/chunk.xsl</screen>
</section>
</section>
</section>
<section xml:id="changes">
<title>Markup changes</title>
<para>You can find complete list of changes in
<citation>DB5SPEC</citation>. This section shows the most common
markup changes between DocBook V4.x a V5.0 on several examples.</para>
<section xml:id="changes-linking">
<title>Improved cross-referencing and linking</title>
<para>In DocBook V4.x attribute <tag class="attribute">id</tag> was
used to assign unique identifier to element. In DocBook V5.0 this
attribute is renamed to <tag class="attribute">xml:id</tag> in order
to comply to <citation>XMLID</citation>.</para>
<para>Now you can use almost any inline element as a source of link,
not only <tag>xref</tag> or <tag>link</tag>. So the following DocBook
4.x content:</para>
<programlisting><![CDATA[<section id="dir">
<title>DIR command</title>
<para>...</para>
</section>
<section id="ls">
<title>LS command</title>
<para>This command is synonymum for <link linkend="dir"><command>DIR</command></link> command.</para>
</section>]]></programlisting>
<para>will be in DocBook V5.0 written as:</para>
<programlisting><![CDATA[<section xml:id="dir">
<title>DIR command</title>
<para>...</para>
</section>
<section xml:id="ls">
<title>LS command</title>
<para>This command is synonymum for <command linkend="dir">DIR</command> command.</para>
</section>]]></programlisting>
<para>Attribute <tag class="attribute">linkend</tag> was added to all
inline elements together with <tag class="attribute">href</tag>
attribute from XLink namespace. This means that you can use any inline
element as a source of hypertext link. In order to use XLinks you have
to declare XLink namespace on the root element of your
document:</para>
<programlisting><![CDATA[<article xmlns="http://docbook.org/ns/docbook";
xmlns:xl="http://www.w3.org/1999/xlink"; version="5.0">
<title>Test article</title>
<para><application xl:href="http://www.gnu.org/software/emacs/emacs.html";>Emacs</application>
is my favourite text editor.</para>]]>
…</programlisting>
<para>Element <tag condition="v4">ulink</tag> was completely removed from DocBook V5.0
in favor of XLink linking. Instead of DocBook V4.x <tag condition="v4">ulink</tag>
element:</para>
<programlisting><![CDATA[<ulink url="http://docbook.org";>DocBook site</ulink>]]></programlisting>
<para>you can now use</para>
<programlisting><![CDATA[<link xl:href="http://docbook.org";>DocBook site</link>]]></programlisting>
<para>XLink links can contain fragment identifier and you can even
use them instead of <tag class="attribute">linkend</tag> attributes to form
cross-references inside document:</para>
<programlisting><![CDATA[<command xl:href="#dir">DIR</command>]]></programlisting>
<para>However XLink links are not checked during validation while <tag
class="attribute">xml:id</tag>/<tag class="attribute">linkend</tag>
links are checked for ID/IDREF consistency. It depends on your needs
what approach to internal linking is more suitable for you.</para>
</section>
<section xml:id="changes-renamed">
<title>Renamed elements</title>
<para>Some elements were renamed to better express their meaning or to
reduce total number of elements available in DocBook.</para>
<table>
<title>Renamed elements</title>
<tgroup cols="2">
<thead>
<row>
<entry>Old name</entry>
<entry>New name</entry>
</row>
</thead>
<tbody>
<row>
<entry><tag condition="v4">sgmltag</tag></entry>
<entry><tag>tag</tag></entry>
</row>
<row>
<entry><tag condition="v4">bookinfo</tag>, <tag condition="v4">articleinfo</tag>,
<tag condition="v4">chapterinfo</tag>, <tag condition="nolink">*info</tag></entry>
<entry><tag>info</tag></entry>
</row>
<row>
<entry><tag condition="v4">authorblurb</tag></entry>
<entry><tag>personblurb</tag></entry>
</row>
<row>
<entry><tag condition="v4">collabname</tag>, <tag condition="v4">corpauthor</tag>,
<tag condition="v4">corpcredit</tag>, <tag condition="v4">corpname</tag></entry>
<entry><tag>orgname</tag></entry>
</row>
<row>
<entry><tag condition="v4">isbn</tag>, <tag condition="v4">issn</tag>,
<tag condition="v4">pubsnumber</tag></entry>
<entry><tag>biblioid</tag></entry>
</row>
<row>
<entry><tag condition="v4">lot</tag>, <tag condition="v4">lotentry</tag>, <tag condition="v4">tocback</tag>,
<tag condition="v4">tocchap</tag>, <tag condition="v4">tocfront</tag>, <tag condition="v4">toclevel1</tag>,
<tag condition="v4">toclevel2</tag>, <tag condition="v4">toclevel3</tag>, <tag condition="v4">toclevel4</tag>,
<tag condition="v4">toclevel5</tag>, <tag condition="v4">tocpart</tag></entry>
<entry><tag>tocdiv</tag></entry>
</row>
<row>
<entry><tag condition="v4">graphic</tag>, <tag condition="v4">graphicco</tag>,
<tag condition="v4">inlinegraphic</tag>, <tag condition="v4">mediaobjectco</tag></entry>
<entry><tag>mediaobject</tag> and <tag>inlinemediaobject</tag></entry>
</row>
<row>
<entry><tag condition="v4">ulink</tag></entry>
<entry><tag>link</tag></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="changes-removed">
<title>Removed elements</title>
<para>The following elements were removed from DocBook V5.0 without any
suitable replacement: <tag condition="v4">action</tag>, <tag
condition="v4">beginpage</tag>, <tag condition="v4">highlights</tag>,
<tag condition="v4">interface</tag>, <tag
condition="v4">invpartnumber</tag>, <tag
condition="v4">medialabel</tag>, <tag condition="v4">modespec</tag>,
<tag condition="v4">structfield</tag>, <tag
condition="v4">structname</tag>.</para>
</section>
</section>
<section xml:id="convert4to5">
<title>Converting DocBook V4.x documents to DocBook V5.0</title>
<para>The DocBook V5.0 schema ships with an XSLT 1.0 stylesheet that
is designed to transform valid DocBook V4.x documents to valid
DocBook V5.0 documents.</para>
<para>To convert your document, <filename>doc.xml</filename> in the
examples below, follow these steps:</para>
<procedure>
<step>
<para>Check the validity of your DocBook XML V4.x document. The
conversion tool assumes that the input document is valid. If the input
document contains markup errors, the results will be unpredictable at
best.</para>
</step>
<step>
<para>Transform <filename>doc.xml</filename> to
<filename>newdoc.xml</filename> with the
<filename>db4-upgrade.xsl</filename> stylesheet included in the
DocBook V5.0 distribution that you are using.</para>
</step>
<step>
<para>Check the validity of your DocBook XML V5.0 document against
the DocBook V5.0 RELAX NG grammar.</para>
</step>
</procedure>
<para>In the vast majority of cases, the resulting document should
be valid and your conversion process is finished.</para>
<para>If the document is not valid, please report the problem.
(Over time, we'll have more experience with the sorts of things
that can go wrong and we'll update this document to reflect that
experience.)</para>
<section>
<title>What About Entities?</title>
<para>Using XSLT to transform existing documents to DocBook V5.0 has
one potential disadvantage: it removes all entity references from
your document.</para>
<para>If preserving entities is an important aspect of your production
work flow, you will have to engage in a semi-manual process to
preserve them.</para>
<procedure>
<step>
<para>Open your existing document using your favorite editing tool.
You must use a tool that <emphasis>is not</emphasis> XML-aware, or one
that allows you to edit markup “in the raw”.</para>
</step>
<step>
<para>Replace all occurrences of the entity references that you want
to preserve with some unique string. For example, if you want to preserve
“<literal>&Product;</literal>” references, you could replace them
all with “<literal>[[[Product]]]</literal>” (assuming that the string
“[[[Product]]]” doesn't occur anywhere else in your document).</para>
</step>
<step>
<para>Copy the document type declaration off of your document and save
it some place. The document type declaration is everything from
“<literal><!DOCTYPE</literal>” to the closing “<literal>]></literal>”.
</para>
</step>
<step>
<para>Perform the conversion described in <xref linkend="convert4to5"/>.
</para>
</step>
<step>
<para>Open the new document using your favorite editing tool. Replace
all occurrences of the unique string you used to save the entity references
with the corresponding entity references.</para>
</step>
<step>
<para>Paste the document type declaration that you saved onto the top
of your new document.</para>
</step>
<step>
<para>Remove the external identifier (the <literal>PUBLIC</literal>
and/or <literal>SYSTEM</literal> keywords) from the document type
declaration. A document that begins:</para>
<programlisting><![CDATA[<!DOCTYPE book [
<!ENTITY someEntity "some replacement text">
]>]]></programlisting>
<para>is perfectly well-formed. If you don't remove the references to
the DTD, then your parser will likely try to validate against DocBook
V4.0 and that's not going to work. Alternatively, you could refer
to the DocBook V5.0 DTD.</para>
</step>
</procedure>
<section>
<title>External Parsed Entities</title>
<para>External parsed entities, entities which load part of a document
from another file, are a special case. These can often be replaced
with XInclude elements.</para>
<para>The Perl script <filename>db4-entities.pl</filename>, also included
in the DocBook V5.0 distribution attempts to perform this replacement
for you. To use the script, perform the following steps:</para>
<procedure>
<step>
<para>Process your document with <filename>db4-entities.pl</filename>.
The script expects a single filename and prints the XInclude version
on standard output.</para>
</step>
<step>
<para>Process the XInclude version as described in <xref
linkend="convert4to5"/>.
</para>
</step>
</procedure>
</section>
</section>
</section>
<section xml:id="customizations">
<title>Customizing DocBook V5.0</title>
<para>TBD</para>
<!--
** RNG schema organization
** Removing attributes
** Adding new attributes
** Changing permitted content of attribute
** Removing elements
** Adding new elements
** Customizing content models
** Naming and versioning of DocBook customizations
-->
</section>
<section xml:id="faq">
<title>FAQ</title>
<qandaset>
<qandadiv>
<title>Authoring</title>
<qandaentry>
<question>
<para>How do I attach schema to DocBook V5.0 document when I do not
want to use DTDs and !DOCTYPE?</para>
</question>
<answer>
<para>There is no standard way of associating schema with document in
RELAX NG. You must learn this in documentation of your software tool.
Usually tools provide some configuration option that allow you to map
namespaces to schemas. This is the best option usually. Some tools
also offer proprietary PI for attaching schema. In some tools you
must specify schema manually each time your want to edit/process your
document.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How to use entities like <tag class="genentity">ndash</tag> in
DocBook V5.0?</para>
</question>
<answer>
<para>Modern schema languages (including RELAX NG and W3X XML Schema)
do not provide any means to define entities that can be used for easier
typing of special characters. Some editors provide functions or
special toolbars that allow you to easily pick necessary character
and insert it into document as a raw Unicode character or a numeric
character reference.</para>
<para>Another possibility is to include entity definitions in the
prolog of your document. <link
xl:href="http://www.w3.org/2003/entities/";>Entity definition
files</link> are now maintained by W3C. You can reference definition
files with entity definitions you are interested in and then reference
imported entities. For example:</para>
<programlisting><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article [
<!ENTITY % isopub SYSTEM "http://www.w3.org/2003/entities/iso8879/isopub.ent";>
%isopub;
]>
<article xmlns="http://docbook.org/ns/docbook"; version="5.0">
<title>DocBook V5.0 – the superb documentation format</title>]]>
…</programlisting>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How to modularize documents?</para>
</question>
<answer>
<para>You can use <link
xl:href="http://www.w3.org/TR/xinclude/";>XIncludes</link> for this
task. There are available alternative schemas for DocBook V5.0 that
contain XInclude elements. This is necessary to make some XML editors
happy. Name of these schemas ends with letters <quote>xi</quote>, e.g.
<filename>docbookxi.rnc</filename> instead of
<filename>docbook.rnc</filename>.</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv>
<title>Stylesheets</title>
<qandaentry>
<question>
<para>Will be the current DocBook XSL stylesheets (XSLT 1.0 based
implementation) maintained and improved in the future if a new work on
a new XSLT 2.0 based implementation started already?</para>
</question>
<answer>
<para>Yes, the current stylesheets (like 1.69.1) 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 point in a future when all new development
will be switched to XSLT 2.0 based implementation only. But this will
not happen before all features of the current stylesheets are
implemented in the new stylesheets and before there will be more than
one usable XSLT 2.0 processor.</para>
</answer>
</qandaentry>
</qandadiv>
</qandaset>
</section>
<bibliography>
<bibliomixed>
<abbrev>RNCTUT</abbrev>
Clark, James – Cowan, John – MURATA, Makoto: <title>RELAX NG Compact Syntax Tutorial</title>.
Working Draft, 26 March 2003. OASIS. <bibliomisc><link xl:href="http://relaxng.org/compact-tutorial-20030326.html"/></bibliomisc>
</bibliomixed>
<bibliomixed>
<abbrev>XMLID</abbrev>
Marsh, Jonathan –
Veillard, Daniel –
Walsh, Norman: <title>xml:id Version 1.0</title>. W3C Recommendation, 9 September 2005. <bibliomisc><link xl:href="http://www.w3.org/TR/xml-id/"/></bibliomisc>
</bibliomixed>
<bibliomixed>
<abbrev>DB5SPEC</abbrev>
Norman, Walsh: <title>The DocBook Schema</title>.
Working Draft 5.0a1, OASIS, 29 June 2005.
<bibliomisc><link xl:href="http://www.docbook.org/specs/wd-docbook-docbook-5.0a1.html"/></bibliomisc>
</bibliomixed>
</bibliography>
</article>
S/MIME Cryptographic Signature
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]