<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<book>
<title>DocBook 3.1 Samples</title>
<chapter><title>Media Objects</title>

<para>
One of the most significant additions to DocBook 3.1 is the
<sgmltag>MediaObject</sgmltag> element.  This element provides an
official DocBook mechanism for inserting non-image objects, such as
video, into a document.  It also allows you to provide several
alternative representations for an image, so that documents can
degrade gracefully on presentation systems with less power.
</para>

<para>
The example shown in <xref linkend="tennis"><footnote><para>
Provided courtesy Juha Haartaja and the Center for Scientific Computing,
Finland.</para></footnote>
contains a video
clip, an image, and a textual description. The presentation
system is required to select only one of these alternatives. For
online presentation, most likely the video clip; for print, the
image; in a text-only environment, the textual description.
</para>

<figure id=tennis>
<title>Animation of a Numerical Solution to a Boundary-Value Problem</title>
<mediaobject>
<objectinfo>
<copyright><year>1998</year>
<holder>Juha Haataja and Center for Scientific Computing, Finland</holder>
</copyright>
</objectinfo>
<videoobject><videodata fileref="tennis.mpeg"></videoobject>
<imageobject><imagedata fileref="tennis.jpg"></imageobject>
<textobject>
<para>
This figure presents an animation which shows a numerical
solution to a boundary-value problem using the shooting method.
</para>
</textobject>
<textobject>
<phrase>Animation of the Solution to a Boundary-Value Problem</phrase>
</textobject>
<caption>
<para>This animation is 
<ulink url="http://www.csc.fi/math_topics/Movies/ODE.html">part of
a series</ulink> designed to illustrate
topics in solving differential equations.  It was constructed by
Juha Haataja at CSC and shows an animation of a numerical
solution to a boundary-value problem using the shooting method.
</para>
</caption>
</mediaobject>
</figure>

<para>
The inline version of <sgmltag>MediaObject</sgmltag>:
<inlinemediaobject>
<imageobject><imagedata format="gif" fileref="emc2.gif"></imageobject>
<textobject><phrase>E=mc^2</phrase></textobject>
</inlinemediaobject>
is <sgmltag>InlineMediaObject</>.
</para>
</chapter>

<chapter><title>Recursive Sections</title>

<para>
DocBook 3.1 introduced the <sgmltag>Section</sgmltag> element.
It is an alternative to <sgmltag>Sect1</sgmltag>, and may be nested
arbitrarily deep.
</para>

<section><title>These are Recursive</title>
<section><title>Recursive</title>
<section><title>Recursive</title>
<section><title>Recursive</title>
<section><title>Recursive</title>
<section><title>Recursive</title>
<section><title>Recursive</title>
<section><title>Recursive</title>
<section><title>Recursive</title>
<section><title>Sections</title>
<para>See?</para>
</section>
</section>
</section>
</section>
</section>
</section>
</section>
</section>
</section>
</section>
</chapter>

<chapter><title>Question and Answer Sets</title>

<para>
The <sgmltag>QandASet</sgmltag> is a structure appropriate for FAQs
and other question and answer sets.
</para>

<para>
The DocBook FAQ is an example of a <sgmltag>QandASet</sgmltag>:
</para>

<qandaset defaultlabel=number><title>Frequently Asked Questions about DocBook</title>
<qandadiv><title>Questions about the FAQ</title>
<qandaentry>
<question>
<para>What version of the FAQ is this?</para>
</question>
<answer>
<para>This is $Revision: 1.2 $ from $Date: 2000/09/28 12:51:04 $.</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv><title>General Questions about DocBook</title>
<qandaentry>
<question>
<para>What is DocBook?</para>
</question>
<answer>
<para>DocBook is an
<ulink url="http://www.oasis-open.org/docbook/distributions/">SGML DTD</ulink>
An <ulink url="http://nwalsh.com/docbook/xml/">XML version</ulink>
is also available.</para>
<para>DocBook is maintained by the DocBook Technical Committee of
<ulink url="http://www.oasis-open.org/">OASIS</ulink>.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What is SGML? What is XML? What is a DTD?</para>
</question>
<answer>
<para>
There are many sources of information about these general topics.
Robin Cover's <ulink url="http://www.oasis-open.org/cover/">SGML/XML
Web Page</ulink> is a great place to start.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Where can I get DocBook?</para>
</question>
<answer>
<para>DocBook is available from OASIS at
<ulink url="http://www.oasis-open.org/docbook/">http://www.oasis-open.org/docbook/</ulink>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What is the current version of DocBook?</para>
</question>
<answer>
<para>DocBook version 3.0 is the current version.</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv><title>Questions about the Modular DocBook Stylesheets</title>
<qandadiv><title>General Questions about the Stylesheets</title>
<qandaentry>
<question>
<para>What are the Modular DocBook Stylesheets?</para>
</question>
<answer>
<para>The Modular DocBook Stylesheets are a popular way to format
DocBook documents for print presentation (using TeX, RTF, or FrameMaker)
or online presentation (using HTML).</para>
<para>They are DSSSL stylesheets.
The acronym stands for <citetitle>Document Style Semantics and Specification
Language</citetitle>. It is defined by ISO/IEC 10179:1996. For more general
information about DSSSL, see <ulink url="http://www.jclark.com/dsssl/">the
DSSSL Page</ulink>.</para>
<para>
The most common DSSSL engine is
<ulink url="http://www.jclark.com/jade/">Jade</ulink>, by James Clark.
Jade is available for Unix and Windows platforms.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Where can I get the Modular DocBook Stylesheets?</para>
</question>
<answer>
<para>From <ulink url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink>. They are maintained by
<ulink url="mailto:ndw@nwalsh.com">Norman Walsh</ulink>.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What is the current version of the stylesheets?</para>
</question>
<answer>
<para>See
<ulink url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink> for the latest version information.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How do I create my own custom stylesheet?</para>
</question>
<answer>
<para>
DSSSL allows one stylesheet to "use" another.  The stylesheet
inherits all of the properties of the stylesheet that it is
using, but local definitions take precedence over imported ones.
</para>
<para>
The simplest custom stylesheet looks like this:
</para>
<screen>
<![CDATA[
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY docbook.dsl 
         PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"
         CDATA DSSSL>
]>

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

;; your (re)definitions go here

</style-specification-body>
</style-specification>

<external-specification id="docbook" document="docbook.dsl">

</style-sheet>
]]>
</screen>
<para>This stylesheet customizes the print stylesheet.  If you want to
customize the HTML stylesheet, use the HTML stylesheet public identifier
in the declaration of the <literal>docbook.dsl</literal> entity.
</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv><title>Internationalization</title>
<qandaentry>
<question>
<para>What languages are supported by the Modular DSSSL Stylesheets?</para>
</question>
<answer>
<para>As of January, 1999: 
<simplelist type="inline">
<member>Danish</member>
<member>Dutch</member>
<member>English</member>
<member>Finnish</member>
<member>French</member>
<member>German</member>
<member>Italian</member>
<member>Norsk Bokm&#229;l</member>
<member>Polish</member>
<member>Portuguese</member>
<member>Russian</member>
<member>Spanish</member>
<member>Swedish</member>
</simplelist>
</para>
<para>In version 1.33 of the stylesheets, I changed the language codes
to be ISO/RFC compliant.  Old <sgmltag class=attribute>lang</sgmltag>
attribute values will continue to work, but the filenames have changed.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What does support mean?</para>
</question>
<answer>
<para>Primarily, it means that generated text (the words
"Chapter" or "Table of Contents") will appear in the desired
language.  Language support also changes some punctuation in
some languages.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What if the language I need isn't supported?</para>
</question>
<answer>
<para>Please create a localization for the language and contribute it!
Supporting another language is not very difficult.
</para>
<procedure>
<step><para>Choose the abbreviation for the language.  This should be
the ISO language code plus the ISO country code.  For example, XXYY.
</para></step>
<step><para>Copy the files
<filename>dbl1en.ent</filename> and <filename>dbl1en.dsl</filename>
in the <filename>common</filename> directory to
<filename>dbl1XX.ent</filename> and <filename>dbl1XX.dsl</filename>.
</para></step>
<step><para>
Translate the English words in <filename>dbl1XX.ent</filename> into
the proper language.
</para></step>
<step><para>
Change "en" to "XX" in <filename>dbl1XX.dsl</filename>.
Make any other required changes.
</para></step>
<step><para>
In <filename>common/dbl10n.dsl</filename>, add a new marked section for "XX"
to each of the functions.
Update <filename>html/dbl10n.dsl</filename> in the same way.
</para></step>
<step><para>
In <filename>print/docbook.dsl</filename> and 
<filename>html/docbook.dsl</filename>, add a new parameter entity for
XX, source it in, and add a new
<sgmltag class=starttag>external-specification</sgmltag> for it.
</para></step>
<step><para>
Create <filename>dbl1XX.dsl</filename> in the <filename>print</filename>
and <filename>html</filename> directories.  Again, you can use
<filename>dbl1en.dsl</filename> as a model.
</para></step>
<step><para>
If you have any questions, ask <ulink url="mailto:ndw@nwalsh.com">Norman
Walsh</ulink>.
</para></step>
</procedure>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How do I make the stylesheets use French (German, etc.)?</para>
</question>
<answer>
<para>There are two ways: set the 
<sgmltag class=attribute>lang</sgmltag> attribute to the language code
of the desired language, or create a stylesheet that defines the
default language.
</para>
<table id="tbl.lang">
<title>DocBook Stylesheet Language Codes</title>
<tgroup cols="2"><colspec colname="COLSPEC0"><colspec colname="COLSPEC1">
<thead>
<row><entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char=""
charoff="50" valign="top">Language Code<footnote><para>The desired form for
language codes is the two-letter ISO standard language code.  If the
language is not unique (e.g., if you wanted to make a British English 
stylesheet), use the two-letter country code plus the language code,
as described in RFC 1766.</para>
</footnote></entry><entry colname="COLSPEC1" colsep="1" rowsep="1" align="left"
char="" charoff="50" valign="top">Language</entry></row>
</thead>
<tbody>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>nl</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">Dutch</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>en</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">English</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>fr</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">French</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>de</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">German</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>it</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">Italian</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>no</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">Norwegian</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>pl</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">Polish</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>pt</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">Portuguese</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>ru</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">Russian</entry>
</row>
<row>
<entry colname="COLSPEC0" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top"><literal>es</literal></entry>
<entry colname="COLSPEC1" colsep="1" rowsep="1" align="left" char="" charoff="50"
valign="top">Spanish</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
For example, to make a Russian book, start your document with
<literal>&lt;book lang="ru"&gt;</literal>.
</para>
<para>Alternatively, put
<screen>
(define %default-language% "fr")
</screen>
in your custom stylesheet.
</para>
</answer>
</qandaentry>
</qandadiv>
</qandadiv>
</qandaset>

</chapter>

<chapter><title>Informal Figures</title>

<para>
An untitled figure is an <sgmltag>InformalFigure</sgmltag>:
</para>

<informalfigure>
<mediaobject>
<imageobject><imagedata format="gif" fileref="emc2.gif"></imageobject>
<textobject><phrase>E=mc^2</phrase></textobject>
<caption><para>This equation relates matter and energy.</para></caption>
</mediaobject>
</informalfigure>
</chapter>

<chapter><title>New Inlines</title>
<para>
Finally, DocBook 3.1 introduces two new inlines: <constant>Constant</constant>,
for constants, and <varname>VarName</varname>, for the names of variables.
</para>
</chapter>

<colophon>
<para>And it introduces the <sgmltag>Colophon</sgmltag> element.
</para>
</colophon>
</book>
