<?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>

  <section id="images">

     <imagedata fileref="simple.pdf" format="pdf" align="center"/>
     <imagedata fileref="simple.png" format="png" align="center"/>

   <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 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>

#include <stdio.h>
int main ()
        int count = 3;
        while (count--)
                printf ("Count is now %d\n", count);

   <para>The problem is that <literal>&lt;stdio.h&gt;</literal> will
    be interpreted as an SGML tag.  For this small fragment, it is
    easy to replace the &lt;-signs with <literal>&amp;lt;</literal>,
    but for larger code fragments there could easily be missed SGML

   <para>A slightly easier way is to enclose it in a
    <sgmltag>CDATA</sgmltag> tag (i.e. literal text), like


   <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>

    <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>

   <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 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 id="euro">
   <title>The euro character</title>

   <para>There is a bug in older versions (before 1.12) of PassiveTeX
    causing euro characters (&amp;euro;, which should look something
    like <quote>&euro;</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 id="indexing">
   <title>Creating an index</title>

    <primary>index entries</primary>
    <secondary>marking up</secondary>
    </indexterm>Adding an index to your document is easy; the DocBook XS
    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>&lt;index&nbsp;/></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

  <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>

<!-- Local Variables: -->
<!-- sgml-indent-step: 1 -->
<!-- sgml-indent-data: 1 -->
<!-- sgml-parent-document: "selfdocbookx.xml" -->
<!-- End: -->