<!-- -*- 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>
tag.</para>
<para>The following sections are for example only, and may not
actually mean anything.</para>
<section id="images">
<title>Images</title>
<mediaobject>
<imageobject>
<imagedata fileref="simple" format="eps" 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>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
PDF.</para>
<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>
<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]]>—<![CDATA[)
printf ("Count is now %d\n", count);
}
]]>
</programlisting>
<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><stdio.h></literal> isn't interpreted as an SGML
tag. The tags you need for this are:</para>
<programlisting>
<programlisting><![CDATA[
…
]]></programlisting>
</programlisting>
<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>
<warning>
<para>There used to be a bug in
<application>openjade</application> that caused incorrect TeX
output for <quote><literal>—</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>
</warning>
</section>
<section>
<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
properly.</para>
<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{…}</literal> and
<literal>\path{…}</literal>.</para>
<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
linkend="jadetex.cfg">).</para>
<para>The <sgmltag>ulink</sgmltag> element shown in <xref
linkend="selfdocbook.dsl"> handles the case where there are no
child elements—such as with <literal><ulink
url="http://…"></ulink></literal>—as
well as the case where the <sgmltag>ulink</sgmltag> text is the
same as the link itself, such as with <literal><ulink
url="http://…">http://…</ulink></literal>.</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="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>
<section id="euro">
<title>The euro character</title>
<para>There is a bug in versions of jadetex before 3.12 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 jadetex-3.11-8
package, available in rawhide.</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> SGML element.</para>
</section>
</chapter>
<!-- Local Variables: -->
<!-- sgml-indent-step: 1 -->
<!-- sgml-indent-data: 1 -->
<!-- sgml-parent-document: "selfdocbook.sgml" -->
<!-- End: -->