374 lines
16 KiB
XML
374 lines
16 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- Copyright (c) 2000 Nik Clayton, All rights reserved.
|
|
|
|
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
|
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
|
|
modification, are permitted provided that the following conditions
|
|
are met:
|
|
|
|
1. Redistributions of source code (SGML DocBook) must retain the above
|
|
copyright notice, this list of conditions and the following
|
|
disclaimer as the first lines of this file unmodified.
|
|
|
|
2. Redistributions in compiled form (transformed to other DTDs,
|
|
converted to PDF, PostScript, RTF and other formats) must reproduce
|
|
the above copyright notice, this list of conditions and the
|
|
following disclaimer in the documentation and/or other materials
|
|
provided with the distribution.
|
|
|
|
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
|
|
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
|
|
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
|
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
|
|
POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
$FreeBSD$
|
|
-->
|
|
<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="examples">
|
|
<title>Examples</title>
|
|
|
|
<para>This appendix contains example <acronym>XML</acronym> files
|
|
and the commands to convert them from one output format to
|
|
another. After installing the Documentation Project tools (see
|
|
<xref linkend="tools-required"/>), these examples can be used
|
|
directly.</para>
|
|
|
|
<para>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 <acronym>XML</acronym> source for this and other
|
|
documents available in the <application>svn</application>
|
|
<literal>doc</literal> repository, or available online starting at
|
|
<uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para>
|
|
|
|
<para>To avoid confusion, these examples use the standard DocBook
|
|
4.1 <acronym>DTD</acronym> 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.</para>
|
|
|
|
<sect1 xml:id="examples-docbook-book">
|
|
<title>DocBook <tag>book</tag></title>
|
|
|
|
<example>
|
|
<title>DocBook <tag>book</tag></title>
|
|
|
|
<programlisting><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<tag class="starttag">book lang='en'</tag>
|
|
<tag class="starttag">bookinfo</tag>
|
|
<tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag>
|
|
|
|
<tag class="starttag">author</tag>
|
|
<tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
|
|
<tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
|
|
<tag class="starttag">affiliation</tag>
|
|
<tag class="starttag">address</tag><tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag><tag class="endtag">address</tag>
|
|
<tag class="endtag">affiliation</tag>
|
|
<tag class="endtag">author</tag>
|
|
|
|
<tag class="starttag">copyright</tag>
|
|
<tag class="starttag">year</tag>2000<tag class="endtag">year</tag>
|
|
<tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>
|
|
<tag class="endtag">copyright</tag>
|
|
|
|
<tag class="starttag">abstract</tag>
|
|
<tag class="starttag">para</tag>If your book has an abstract then it should go here.<tag class="endtag">para</tag>
|
|
<tag class="endtag">abstract</tag>
|
|
<tag class="endtag">bookinfo</tag>
|
|
|
|
<tag class="starttag">preface</tag>
|
|
<tag class="starttag">title</tag>Preface<tag class="endtag">title</tag>
|
|
|
|
<tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed
|
|
here.<tag class="endtag">para</tag>
|
|
<tag class="endtag">preface</tag>
|
|
|
|
<tag class="starttag">chapter</tag>
|
|
<tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag>
|
|
|
|
<tag class="starttag">para</tag>This is the first chapter in my book.<tag class="endtag">para</tag>
|
|
|
|
<tag class="starttag">sect1</tag>
|
|
<tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>
|
|
|
|
<tag class="starttag">para</tag>This is the first section in my book.<tag class="endtag">para</tag>
|
|
<tag class="endtag">sect1</tag>
|
|
<tag class="endtag">chapter</tag>
|
|
<tag class="endtag">book</tag></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="examples-docbook-article">
|
|
<title>DocBook <tag>article</tag></title>
|
|
|
|
<example>
|
|
<title>DocBook <tag>article</tag></title>
|
|
|
|
<programlisting><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<tag class="starttag">article lang='en'</tag>
|
|
<tag class="starttag">articleinfo</tag>
|
|
<tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag>
|
|
|
|
<tag class="starttag">author</tag>
|
|
<tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag>
|
|
<tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag>
|
|
<tag class="starttag">affiliation</tag>
|
|
<tag class="starttag">address</tag><tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag><tag class="endtag">address</tag>
|
|
<tag class="endtag">affiliation</tag>
|
|
<tag class="endtag">author</tag>
|
|
|
|
<tag class="starttag">copyright</tag>
|
|
<tag class="starttag">year</tag>2000<tag class="endtag">year</tag>
|
|
<tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag>
|
|
<tag class="endtag">copyright</tag>
|
|
|
|
<tag class="starttag">abstract</tag>
|
|
<tag class="starttag">para</tag>If your article has an abstract then it should go here.<tag class="endtag">para</tag>
|
|
<tag class="endtag">abstract</tag>
|
|
<tag class="endtag">articleinfo</tag>
|
|
|
|
<tag class="starttag">sect1</tag>
|
|
<tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag>
|
|
|
|
<tag class="starttag">para</tag>This is the first section in my article.<tag class="endtag">para</tag>
|
|
|
|
<tag class="starttag">sect2</tag>
|
|
<tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag>
|
|
|
|
<tag class="starttag">para</tag>This is the first sub-section in my article.<tag class="endtag">para</tag>
|
|
<tag class="endtag">sect2</tag>
|
|
<tag class="endtag">sect1</tag>
|
|
<tag class="endtag">article</tag></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 xml:id="examples-formatted">
|
|
<title>Producing Formatted Output</title>
|
|
|
|
<para>Before using these examples, install the required tools as
|
|
shown in <xref linkend="tools-required"/>.</para>
|
|
|
|
<sect2>
|
|
<title>Using <application>Jade</application></title>
|
|
|
|
<example>
|
|
<title>Converting DocBook to <acronym>XHTML</acronym> (One
|
|
Large File)</title>
|
|
|
|
<screen>&prompt.user; <userinput>jade -V nochunks \ <co xml:id="examples-co-jade-1-nochunks"/>
|
|
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-1-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 \<co xml:id="examples-co-jade-1-dsssl"/>
|
|
-t sgml <co xml:id="examples-co-jade-1-transform"/> <replaceable>file</replaceable>.xml > <replaceable>file</replaceable>.html <co xml:id="examples-co-jade-1-filename"/></userinput></screen>
|
|
|
|
<calloutlist>
|
|
<callout arearefs="examples-co-jade-1-nochunks">
|
|
<para>Specifies the <literal>nochunks</literal> parameter
|
|
to the stylesheets, forcing all output to be written to
|
|
the standard output (using Norm Walsh's
|
|
stylesheets).</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-1-catalog">
|
|
<para>Specifies the catalogs that
|
|
<application>Jade</application> will need to process.
|
|
Three catalogs are required. The first is a catalog
|
|
that contains information about the
|
|
<acronym>DSSSL</acronym> stylesheets. The second
|
|
contains information about the DocBook
|
|
<acronym>DTD</acronym>. The third contains information
|
|
specific to <application>Jade</application>.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-1-dsssl">
|
|
<para>Specifies the full path to the
|
|
<acronym>DSSSL</acronym> stylesheet that
|
|
<application>Jade</application> will use when processing
|
|
the document.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-1-transform">
|
|
<para>Instructs <application>Jade</application> to perform
|
|
a <emphasis>transformation</emphasis> from one
|
|
<acronym>DTD</acronym> to another. In this case, the
|
|
input is being transformed from the DocBook
|
|
<acronym>DTD</acronym> to the <acronym>XHTML</acronym>
|
|
<acronym>DTD</acronym>.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-1-filename">
|
|
<para>Specifies the file that
|
|
<application>Jade</application> should process, and
|
|
redirects output to the specified
|
|
<filename>.html</filename> file.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Converting DocBook to <acronym>XHTML</acronym> (Several
|
|
Small Files)</title>
|
|
|
|
<screen>&prompt.user; <userinput>jade \
|
|
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-2-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 \<co xml:id="examples-co-jade-2-dsssl"/>
|
|
-t sgml <co xml:id="examples-co-jade-2-transform"/> <replaceable>file</replaceable>.xml <co xml:id="examples-co-jade-2-filename"/></userinput></screen>
|
|
|
|
<calloutlist>
|
|
<callout arearefs="examples-co-jade-2-catalog">
|
|
<para>Specifies the catalogs that
|
|
<application>Jade</application> will need to process.
|
|
Three catalogs are required. The first is a catalog
|
|
that contains information about the
|
|
<acronym>DSSSL</acronym> stylesheets. The second
|
|
contains information about the DocBook
|
|
<acronym>DTD</acronym>. The third contains information
|
|
specific to <application>Jade</application>.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-2-dsssl">
|
|
<para>Specifies the full path to the
|
|
<acronym>DSSSL</acronym> stylesheet that
|
|
<application>Jade</application> will use when processing
|
|
the document.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-2-transform">
|
|
<para>Instructs <application>Jade</application> to perform
|
|
a <emphasis>transformation</emphasis> from one
|
|
<acronym>DTD</acronym> to another. In this case, the
|
|
input is being transformed from the DocBook
|
|
<acronym>DTD</acronym> to the <acronym>XHTML</acronym>
|
|
<acronym>DTD</acronym>.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-2-filename">
|
|
<para>Specifies the file that
|
|
<application>Jade</application> should process. The
|
|
stylesheets determine how the individual
|
|
<acronym>XHTML</acronym> files will be named, and the
|
|
name of the <quote>root</quote> file, the one that
|
|
contains the start of the document.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
|
|
<para>This example may still only generate one
|
|
<acronym>XHTML</acronym> file, depending on the structure of
|
|
the document you are processing, and the stylesheet's rules
|
|
for splitting output.</para>
|
|
</example>
|
|
|
|
<example xml:id="examples-docbook-postscript">
|
|
<title>Converting DocBook to &postscript;</title>
|
|
|
|
<para>The source <acronym>XML</acronym> file must be converted
|
|
to a &tex; file.</para>
|
|
|
|
<screen>&prompt.user; <userinput>jade -V tex-backend \ <co xml:id="examples-co-jade-3-tex-backend"/>
|
|
-c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-3-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 \<co xml:id="examples-co-jade-3-dsssl"/>
|
|
-t tex <co xml:id="examples-co-jade-3-tex"/> <replaceable>file</replaceable>.xml</userinput></screen>
|
|
|
|
<calloutlist>
|
|
<callout arearefs="examples-co-jade-3-tex-backend">
|
|
<para>Customizes the stylesheets to use various options
|
|
specific to producing output for &tex;.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-3-catalog">
|
|
<para>Specifies the catalogs that
|
|
<application>Jade</application> will need to process.
|
|
Three catalogs are required. The first is a catalog
|
|
that contains information about the
|
|
<acronym>DSSSL</acronym> stylesheets. The second
|
|
contains information about the DocBook
|
|
<acronym>DTD</acronym>. The third contains information
|
|
specific to <application>Jade</application>.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-3-dsssl">
|
|
<para>Specifies the full path to the
|
|
<acronym>DSSSL</acronym> stylesheet that
|
|
<application>Jade</application> will use when processing
|
|
the document.</para>
|
|
</callout>
|
|
|
|
<callout arearefs="examples-co-jade-3-tex">
|
|
<para>Instructs <application>Jade</application> to convert
|
|
the output to &tex;.</para>
|
|
</callout>
|
|
</calloutlist>
|
|
|
|
<para>The generated <filename>.tex</filename> file must now be
|
|
run through <command>tex</command>, specifying the
|
|
<literal>&jadetex</literal> macro package.</para>
|
|
|
|
<screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>file</replaceable>.tex</userinput></screen>
|
|
|
|
<para><command>tex</command> commands must be run
|
|
<emphasis>at least</emphasis> 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.</para>
|
|
|
|
<para>Do not be alarmed if you see warning messages such as
|
|
<errorname>LaTeX Warning: Reference `136' on page 5
|
|
undefined on input line 728.</errorname> at this
|
|
point.</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>The third pass performs any final cleanup
|
|
necessary.</para>
|
|
|
|
<para>The output from this stage will be
|
|
<filename><replaceable>file</replaceable>.dvi</filename>.</para>
|
|
|
|
<para>Finally, run <command>dvips</command> to convert the
|
|
<filename>.dvi</filename> file to &postscript;.</para>
|
|
|
|
<screen>&prompt.user; <userinput>dvips -o <replaceable>file</replaceable>.ps <replaceable>file.dvi</replaceable></userinput></screen>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Converting DocBook to <acronym>PDF</acronym></title>
|
|
|
|
<para>The first part of this process is identical to that of
|
|
converting DocBook to &postscript;, using the same
|
|
<command>jade</command> command line (<xref linkend="examples-docbook-postscript"/>).</para>
|
|
|
|
<para>After the <filename>.tex</filename> file has been
|
|
generated, run <application>pdfTeX</application>.
|
|
However, use the <literal>&pdfjadetex</literal> macro
|
|
package instead.</para>
|
|
|
|
<screen>&prompt.user; <userinput>pdftex "&pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen>
|
|
|
|
<para>Again, run this command three times.</para>
|
|
|
|
<para>This will generate
|
|
<filename><replaceable>file</replaceable>.pdf</filename>,
|
|
which does not need to be processed any further.</para>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
</appendix>
|