Examples
This appendix contains example XML files and the commands
to convert them from one output format to another. After
installing the Documentation Project tools (see ),
these examples can be used directly.
These examples are not exhaustive—they do not contain
all the elements that might be desirable to use, particularly in a
document's front matter. For more examples of DocBook markup,
examine the XML source for this and other documents
available in the svn
doc repository, or available online starting at
.
To avoid confusion, these examples use the standard DocBook
4.1 DTD rather than the &os; extension. They also use the
stock stylesheets distributed by Norm Walsh, rather than any
customizations made to those stylesheets by the &os;
Documentation Project. This makes them more useful as generic
DocBook examples.
DocBook book
DocBook book
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
book lang='en'
bookinfo
titleAn Example Booktitle
author
firstnameYour first namefirstname
surnameYour surnamesurname
affiliation
addressemailfoo@example.comemailaddress
affiliation
author
copyright
year2000year
holderCopyright string hereholder
copyright
abstract
paraIf your book has an abstract then it should go here.para
abstract
bookinfo
preface
titlePrefacetitle
paraYour book may have a preface, in which case it should be placed
here.para
preface
chapter
titleMy First Chaptertitle
paraThis is the first chapter in my book.para
sect1
titleMy First Sectiontitle
paraThis is the first section in my book.para
sect1
chapter
book
DocBook article
DocBook article
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
article lang='en'
articleinfo
titleAn Example Articletitle
author
firstnameYour first namefirstname
surnameYour surnamesurname
affiliation
addressemailfoo@example.comemailaddress
affiliation
author
copyright
year2000year
holderCopyright string hereholder
copyright
abstract
paraIf your article has an abstract then it should go here.para
abstract
articleinfo
sect1
titleMy First Sectiontitle
paraThis is the first section in my article.para
sect2
titleMy First Sub-Sectiontitle
paraThis is the first sub-section in my article.para
sect2
sect1
article
Producing Formatted Output
Before using this examples, install the required tools as shown in .
Using Jade
Converting DocBook to XHTML (One Large File)
&prompt.user; jade -V nochunks \
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \
-t sgml file.xml > file.html
Specifies the nochunks parameter
to the stylesheets, forcing all output to be written to
the standard output (using Norm Walsh's
stylesheets).
Specifies the catalogs that
Jade will need to process.
Three catalogs are required. The first is a catalog
that contains information about the DSSSL stylesheets.
The second contains information about the DocBook DTD.
The third contains information specific to
Jade.
Specifies the full path to the DSSSL stylesheet that
Jade will use when processing
the document.
Instructs Jade to perform
a transformation from one DTD to
another. In this case, the input is being transformed
from the DocBook DTD to the XHTML DTD.
Specifies the file that
Jade should process, and
redirects output to the specified
.html file.
Converting DocBook to XHTML (Several Small
Files)
&prompt.user; jade \
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \
-t sgml file.xml
Specifies the catalogs that
Jade will need to process.
Three catalogs are required. The first is a catalog
that contains information about the DSSSL stylesheets.
The second contains information about the DocBook DTD.
The third contains information specific to Jade.
Specifies the full path to the DSSSL stylesheet that
Jade will use when processing
the document.
Instructs Jade to perform
a transformation from one DTD to
another. In this case, the input is being transformed
from the DocBook DTD to the XHTML DTD.
Specifies the file that
Jade should process. The
stylesheets determine how the individual XHTML files will
be named, and the name of the root
file,
the one that contains the start of the
document.
This example may still only generate one XHTML file,
depending on the structure of the document you are
processing, and the stylesheet's rules for splitting
output.
Converting DocBook to &postscript;
The source XML file must be converted to a &tex;
file.
&prompt.user; jade -V tex-backend \
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \
-c /usr/local/share/xml/docbook/catalog \
-c /usr/local/share/xml/jade/catalog \
-d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \
-t tex file.xml
Customizes the stylesheets to use various options
specific to producing output for &tex;.
Specifies the catalogs that
Jade will need to process.
Three catalogs are required. The first is a catalog
that contains information about the DSSSL stylesheets.
The second contains information about the DocBook DTD.
The third contains information specific to Jade.
Specifies the full path to the DSSSL stylesheet that
Jade will use when processing
the document.
Instructs Jade to convert
the output to &tex;.
The generated .tex file must now be
run through tex, specifying the
&jadetex macro package.
&prompt.user; tex "&jadetex" file.tex
tex commands must be run at
least three times. The first run processes the
document, and determines areas of the document which are
referenced from other parts of the document, for use in
indexing, and so on.
Do not be alarmed if you see warning messages such as
LaTeX Warning: Reference `136' on page 5
undefined on input line 728. at this
point.
The second run reprocesses the document now that certain
pieces of information are known (such as the document's page
length). This allows index entries and other
cross-references to be fixed up.
The third pass performs any final cleanup
necessary.
The output from this stage will be
file.dvi.
Finally, run dvips to convert the
.dvi file to &postscript;.
&prompt.user; dvips -o file.ps file.dvi
Converting DocBook to PDF
The first part of this process is identical to that of
converting DocBook to &postscript;, using the same
jade command line ().
After the .tex file has been
generated, run pdfTeX.
However, use the &pdfjadetex macro
package instead.
&prompt.user; pdftex "&pdfjadetex" file.tex
Again, run this command three times.
This will generate
file.pdf,
which does not need to be processed any further.