<?xml version='1.0' encoding='utf-8'?> <!-- -*- xml -*- -->
<chapter id="tips">
<title>Tips and examples</title>
<para>This document is an example of a <sgmltag>book</sgmltag>, and
a <sgmltag>book</sgmltag> generally contains
<sgmltag>chapter</sgmltag>s, which may contain
<sgmltag>section</sgmltag>s. A paragraph of text can be put in a
<sgmltag>para</sgmltag> tag. There are lots of examples of that in
this book (see <xref linkend="source"/>).</para>
<para>When you want text to appear with its layout intact (spaces
and newlines kept where they are), you can use the
<sgmltag>literallayout</sgmltag> tag. Note that
<keysym>Tab</keysym> characters are <emphasis>not</emphasis>
expanded. If you also would like a different font for the listed
text, you might want to use the <sgmltag>programlisting</sgmltag>
tag.</para>
<section id="images">
<title>Images</title>
<mediaobject>
<imageobject>
<imagedata fileref="simple.pdf" format="pdf" align="center"/>
</imageobject>
<imageobject>
<imagedata fileref="simple.png" format="png" align="center"/>
</imageobject>
</mediaobject>
<para>This shows how to handle images for both print and web
display; each format is included in one
<sgmltag>mediaobject</sgmltag> so the stylesheet, when faced with
a limited subset of formats for the current output media, can
select the best fit.</para>
<para>I have cheated slightly, in that the for-print version is
using a PDF format image even though PDF is not an officially
allowed format in this version of DocBook XML. Luckily though,
the tools I am using allow it through anyway.</para>
</section>
<section id="listing">
<title>Program listings</title>
<para>There are some things to watch out for when doing program
listings. Let's say that we want to put the following fragment of
code into DocBook:</para>
<programlisting><![CDATA[
#include <stdio.h>
int main ()
{
int count = 3;
while (count--)
printf ("Count is now %d\n", count);
}
]]>
</programlisting>
<para>The problem is that <literal><stdio.h></literal> will
be interpreted as an SGML tag. For this small fragment, it is
easy to replace the <-signs with <literal>&lt;</literal>,
but for larger code fragments there could easily be missed SGML
entities.</para>
<para>A slightly easier way is to enclose it in a
<sgmltag>CDATA</sgmltag> tag (i.e. literal text), like
this:</para>
<programlisting>
<programlisting><![CDATA[
…
]]></programlisting>
</programlisting>
<para>The next thing to bear in mind is that <keysym>Tab</keysym>
characters will not be expanded to spaces, so you will need to do
all the indenting with spaces.</para>
<warning>
<para>There is currently a bug in
<application>xmltex</application> that causes incorrect output
for <quote><literal>--</literal></quote> (i.e. two
dashes). Grab the latest PassiveTeX for an
<filename>xmltex.tex</filename> and PassiveTeX distribution with
this fixed.</para>
</warning>
<para>Of course, <xref linkend="source"/> of this book needs to
include quite a lot of source code (XML rather than C), and the
approach I have taken in order to be sure that I haven't missed
anything is to have the <filename>Makefile</filename> run
<application>sed</application> on the original source, and just
include the result as an entity. Take a look at <xref
linkend="source"/> to see how that's done.</para>
</section>
<section id="css">
<title>HTML stylesheets</title>
<para>The HTML version of this document makes use of a custom CSS
stylesheet for rendering HTML elements slightly differently (in
fact, in this small example only some colours are changed). The
CSS stylesheet is <xref linkend="selfdocbookx.css"/>, and the
DocBook HTML stylesheet is told about it by our custom XSL layer:
the <varname>html.stylesheet</varname> parameter is set to the
name of the CSS file we want to use. See <xref
linkend="css.xsl"/> for how that's done.</para>
</section>
<section id="euro">
<title>The euro character</title>
<para>There is a bug in older versions (before 1.12) of PassiveTeX
causing euro characters (&euro;, which should look something
like <quote>€</quote>) to appear as black boxes.</para>
<para>This bug is fixed in the Red Hat Linux passivetex-1.11-5
package, available in rawhide.</para>
<para>However, you'll need an up to date
<filename>marvosym.sty</filename> file, which you can get from
CTAN. (The current Red Hat Linux rawhide teTeX package has this
updated already, but <filename>marvosym.sty</filename> is much
smaller to download!)</para>
</section>
<section id="indexing">
<title>Creating an index</title>
<para><indexterm>
<primary>index</primary>
<secondary>adding</secondary>
</indexterm><indexterm>
<primary>index</primary>
<secondary>generating</secondary>
</indexterm><indexterm>
<primary>index entries</primary>
<secondary>marking up</secondary>
</indexterm>Adding an index to your document is easy; the DocBook XS
L
stylesheets automatically cross-reference your tagged index words
to generate the page numbers in the index section. For example,
in the source XML of this document you'll see that the index
section at the end is indicated by just
<quote><literal><index /></literal></quote>. Examples of
how to mark up index entries in the document are in this paragraph
(<xref linkend="tips.xml" />) and throughout <xref
linkend="tools.xml" />. The key tag is
<sgmltag>indexterm</sgmltag>.</para>
</section>
<section id="no-more">
<title>Please send me examples</title>
<para>There are no more examples in this section yet, because I
haven't written any. If you would like to see a particular
element of DocBook demonstrated here, feel free to send me an
example, preferably demonstrated inside a
<sgmltag>section</sgmltag> XML element.</para>
</section>
</chapter>
<!-- Local Variables: -->
<!-- sgml-indent-step: 1 -->
<!-- sgml-indent-data: 1 -->
<!-- sgml-parent-document: "selfdocbookx.xml" -->
<!-- End: -->