<!-- -*- sgml -*- -->
 <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
   <keycap>Tab</keycap> 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>

  <para>The following sections are for example only, and may not
   actually mean anything.</para>

  <section id="images">

     <imagedata fileref="simple" format="eps" 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>There are some fairly subtle things going on to make this
    work properly with <application>openjade</application>.  The
    problem is that we don't go straight from DocBook to PostScript,
    or from DocBook to PDF.  Instead, we go from DocBook to TeX
    (actually JadeTeX), and then from TeX to either PostScript or

   <para>The complication comes from the fact that included images
    must be in encapsulated PostScript for PostScript output, and in
    PNG or PDF for PDF output.  But
    <application>openjade</application> has no way of telling which
    output format we want!  It just knows that we are converting to
    TeX, as an intermediate stage.</para>

   <para>The way around this that I am using is to <emphasis>miss
     out</emphasis> the graphics file extension for EPS altogether,
    and to tweak the DSSSL stylesheet so that it passes that filename
    straight through, extension-less, to the TeX output.</para>

   <para>So, for HTML output, the PNG format is preferred and
    <filename>simple.png</filename> is selected.  For TeX output
    (either for PostScript or for PDF), the EPS format is preferred
    and so <filename>simple</filename> is used: note that it has no
    file extension.  Then, for the second stage of processing, if I
    am converting to PostScript then the conversion tool will run
    <application>tex</application>, which will assume an extension of
    <filename>.eps</filename>.  If, however, I am converting to PDF
    then the conversion tool will run
    <application>pdfjadetex</application>, which will assume an
    extension of <filename>.png</filename>.</para>

   <para>I also have to make sure that the
    <filename>Makefile</filename> knows to have a file of the right
    format around in the current directory too, of course!</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]]>&mdash;<![CDATA[)
                printf ("Count is now %d\n", count);

   <para>To do this you need to enclose it in a
    <sgmltag>programlisting</sgmltag> tag, and also make it into
    <sgmltag>CDATA</sgmltag> (i.e. literal text) so that
    <literal>&lt;stdio.h&gt;</literal> isn't interpreted as an SGML
    tag.  The tags you need for this are:</para>


   <para>The next thing to bear in mind is that <keycap>Tab</keycap>
    characters will not be expanded to spaces, so you will need to do
    all the indenting with spaces.</para>

    <para>There used to be a bug in
     <application>openjade</application> that caused incorrect TeX
     output for <quote><literal>&mdash;</literal></quote> (i.e. two
     dashes).  This bug is fixed in CVS, and in the
     <literal>openjade-1.3-17</literal> Red Hat Linux package.</para>

   <title>Getting URLs and file names to line wrap</title>

   <para>URLs and file names can be quite long, and that can lead to
    problems when using full justification (so that the left and right
    hand sides of a paragraph line up).  There are certain places in a
    URL or file name where it is safe to break over two lines, and
    there is a TeX package that knows how to break URLs and file names

   <para>In the stylesheet customization layer (see <xref
     linkend="selfdocbook.dsl">) the <sgmltag>ulink</sgmltag> and
    <sgmltag>filename</sgmltag> elements are redefined to output
    formatting instructions like <literal>\url{&hellip;}</literal> and

   <para>By default, URLs and file names marked up in this way are
    rendered magenta.  To turn this off, put
    <literal>\hypersetup{colorlinks=false}</literal> in your
    <filename>jadetex.cfg</filename> (see <xref

   <para>The <sgmltag>ulink</sgmltag> element shown in <xref
    linkend="selfdocbook.dsl"> handles the case where there are no
    child elements&mdash;such as with <literal>&lt;ulink
    well as the case where the <sgmltag>ulink</sgmltag> text is the
    same as the link itself, such as with <literal>&lt;ulink

  <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="selfdocbook.css">, and the
    DocBook HTML stylesheet is told about it by our custom DSSSL
    layer: the <varname>stylesheet</varname> parameter is set to the
    name of the CSS file we want to use.  See <xref
    linkend="selfdocbook.dsl"> for how that's done.</para>

  <section id="euro">
   <title>The euro character</title>

   <para>There is a bug in versions of jadetex before 3.12 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 jadetex-3.11-8
    package, available in rawhide.</para>

  <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> SGML element.</para>

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