<HTML
><HEAD
><TITLE
>Using DocBook</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.63
"><LINK
REL="HOME"
TITLE="DocBook Install mini-HOWTO"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Install the Packages"
HREF="install.html"><LINK
REL="NEXT"
TITLE="Legal"
HREF="legal.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>DocBook Install mini-HOWTO</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="install.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="legal.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="USING"
>4. Using DocBook</A
></H1
><P
> Now that everything is installed, it's time to test it out
and see how to use <B
CLASS="COMMAND"
>openjade</B
> and the other tools.
</P
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN449"
></A
><P
><B
>Figure 1. Example DocBook SGML file - <TT
CLASS="FILENAME"
>test.sgml</TT
></B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article lang="en">
<articleinfo>
<title>This is a Test</title>
<author>
<firstname>John</firstname>
<surname>Doe</surname>
<othername role="mi">L</othername>
<affiliation>
<address>
<email>j.doe@jdoe dot com</email>
</address>
</affiliation>
</author>
<revhistory>
<revision>
<revnumber>v1.0</revnumber>
<date>2000-12-30</date>
<authorinitials>jld</authorinitials>
</revision>
</revhistory>
<abstract>
<para>
This is a test DocBook document.
</para>
</abstract>
</articleinfo>
<sect1 id="test1">
<title>Test 1</title>
<para>
Test section 1.
</para>
<sect2>
<title>Test 1.1</title>
<para>
Test section 1.1
</para>
</sect2>
<sect2>
<title>Test 1.2</title>
<para>
<screen>
-- Test section 1.2
openjade -t sgml -d $DSLFILE test.sgml
</screen>
</para>
</sect2>
</sect1>
<sect1 id="test2">
<title>Test 2</title>
<para>
Test section 2.
</para>
<sect2>
<title>Test 2.1</title>
<para>
Test section 2.1
</para>
</sect2>
<sect2>
<title>Test 2.2</title>
<para>
Test section 2.2
</para>
</sect2>
</sect1>
</article>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
For a guide to DocBook and a reference of DocBook elements, see:
</P
><DIV
CLASS="FORMALPARA"
><P
><B
>DocBook: The Definitive Guide. </B
> <A
HREF="http://www.docbook.org/tdg/en/"
TARGET="_top"
>http://www.docbook.org/tdg/en/</A
>
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN457"
>4.1. Generating HTML</A
></H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN459"
>4.1.1. <TT
CLASS="FILENAME"
>docbook.dsl</TT
></A
></H3
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN463"
></A
><P
><B
>Figure 2. Generating HTML output using <TT
CLASS="FILENAME"
>docbook.dsl</TT
></B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>bash$ ls -l
total 4
-rw-r--r-- 1 reaster users 1077 Dec 31 16:25 test.sgml
bash$ echo $SGML_SHARE
/usr/local/share/sgml
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/docbook.dsl test.sgml
[snip - DTDDECL catalog entries are not supported, repeats]
bash$ ls -l
total 12
-rw-r--r-- 1 reaster users 1885 Dec 31 17:34 t1.htm
-rw-r--r-- 1 reaster users 1077 Dec 31 16:25 test.sgml
-rw-r--r-- 1 reaster users 1544 Dec 31 17:34 x27.htm
bash$
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
The warnings about <TT
CLASS="VARNAME"
>DTDDECL</TT
> can be ignored. They might be a little annoying,
but these warnings are normal when using <B
CLASS="COMMAND"
>openjade</B
>. Other warnings and errors
should be looked at and often indicate syntax errors that you should fix.
</P
><P
> Two <TT
CLASS="FILENAME"
>htm</TT
> files are generated, one for each <TT
CLASS="SGMLTAG"
><sect1></TT
>.
The filenames are not very descriptive. Section one appears on the same page as the article information.
These are the results of using the default stylesheet that comes with the
<EM
>Modular DocBook Stylesheets</EM
>, <TT
CLASS="FILENAME"
>docbook.dsl</TT
>.
</P
><P
> Stylesheets can be customized to improve on these defaults. If you
downloaded the
<A
HREF="http://www.linuxdoc.org/"
TARGET="_top"
>Linux Documentation Project</A
>'s
<TT
CLASS="FILENAME"
>ldp.dsl</TT
> file and installed it as shown in Section 3.3,
then you already have a customized style available.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN477"
>4.1.2. <TT
CLASS="FILENAME"
>ldp.dsl</TT
></A
></H3
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN481"
></A
><P
><B
>Figure 3. Generating HTML output using <TT
CLASS="FILENAME"
>ldp.dsl</TT
></B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/ldp.dsl#html test.sgml
bash$ ls -l
total 16
-rw-r--r-- 1 reaster users 2006 Dec 31 18:00 index.html
-rw-r--r-- 1 reaster users 1077 Dec 31 16:25 test.sgml
-rw-r--r-- 1 reaster users 1677 Dec 31 18:00 test1.html
-rw-r--r-- 1 reaster users 1598 Dec 31 18:00 test2.html
bash$
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
</P
><P
> Using <TT
CLASS="FILENAME"
>ldp.dsl</TT
>, the output looks better:
<P
></P
><UL
><LI
><P
> An index file has been created that contains the article information.
</P
></LI
><LI
><P
> A table of contents has been automatically generated.
</P
></LI
><LI
><P
> Each <TT
CLASS="SGMLTAG"
><sect1></TT
> is in its own file.
</P
></LI
><LI
><P
> Filenames are derived from ID attributes of the <TT
CLASS="SGMLTAG"
><sect1></TT
> elements.
</P
></LI
><LI
><P
> The file extension has changed to <TT
CLASS="FILENAME"
>html</TT
>.
</P
></LI
><LI
><P
> The <TT
CLASS="SGMLTAG"
><screen></TT
> elements are shaded.
</P
></LI
></UL
>
</P
><P
> Note how the <TT
CLASS="FILENAME"
>ldp.dsl</TT
> file is written in the command line:
it has "<TT
CLASS="FILENAME"
>#html</TT
>" appended. <TT
CLASS="FILENAME"
>ldp.dsl</TT
>
contains two <TT
CLASS="SGMLTAG"
><STYLE-SPECIFICATION></TT
> elements, one with
ID="html" and another with ID="print". This selects the <TT
CLASS="FILENAME"
>html</TT
> style from within
ldp.dsl. The DocBook DSSSL contains support for converting DocBook
files into <TT
CLASS="FILENAME"
>html</TT
> and print formats. In Section 3.3, we copied <TT
CLASS="FILENAME"
>ldp.dsl</TT
>
into both the print and <TT
CLASS="FILENAME"
>html</TT
> directories. When generating <TT
CLASS="FILENAME"
>html</TT
> output,
the <TT
CLASS="FILENAME"
>html</TT
> style should be selected like above. When generating other types of
files, such as <TT
CLASS="FILENAME"
>rtf</TT
> and <TT
CLASS="FILENAME"
>tex</TT
>, they fall under the print style and so
the print style should be selected from <TT
CLASS="FILENAME"
>ldp.dsl</TT
>. The alternative is
to comment out or delete the print or <TT
CLASS="FILENAME"
>html</TT
> style in the copy of
<TT
CLASS="FILENAME"
>ldp.dsl</TT
> in the respective directory. If a <TT
CLASS="FILENAME"
>dsl</TT
> file has more than one style-spec
in it and none is selected like in the example above, then the first
style encountered in the file is selected. For <TT
CLASS="FILENAME"
>ldp.dsl</TT
>, the print style-spec
is first in the file, so it gets selected by default. So in the example above,
without appending "<TT
CLASS="FILENAME"
>#html</TT
>" when specifying <TT
CLASS="FILENAME"
>ldp.dsl</TT
> as the dsssl stylesheet,
the "print" style-spec would be selected and used when generating the <TT
CLASS="FILENAME"
>html</TT
>
output. It will work, but is intended for when selecting the <TT
CLASS="FILENAME"
>print/ldp.dsl</TT
>
and the formatting will be different.
</P
><P
> To learn more about how the stylesheet customization files are made, read the
<A
HREF="http://nwalsh.com/docbook/dsssl/doc/"
TARGET="_top"
>documentation for the Modular DocBook Stylesheets</A
>.
Customization mainly involves setting boolean option parameters to toggle style
features on and off. Completely new style logic can be programmed using the
the <A
HREF="http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/index.htm"
TARGET="_top"
>DSSSL</A
>
language.
</P
><P
> The <B
CLASS="COMMAND"
>openjade</B
> option "-t output_type" specifies the output type. The "-d dsssl_spec" option is the path
to the dsssl stylesheet to use. In the example above, the output type specified is sgml, which
is for SGML to SGML transformations. HTML, defined by the
<A
HREF="http://www.w3.org/TR/html4/sgml/dtd.html"
TARGET="_top"
>HTML Document Type Definition (DTD)</A
>,
is an SGML document type just as DocBook is, so "sgml" is the correct output_type option. The
other two output types commonly used are "rtf" and "tex". The tex output_type will be used
later as an intermediate format for the generation of <TT
CLASS="FILENAME"
>pdf</TT
> and <TT
CLASS="FILENAME"
>ps</TT
>
formats. The dsssl_spec must specify a <TT
CLASS="FILENAME"
>dsl</TT
> file, not a directory.
</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN535"
>4.2. Generating rtf and tex</A
></H2
><P
> <TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>bash$ ls -l
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$ openjade -t rtf -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
bash$ openjade -t tex -d $SGML_SHARE/dsssl/docbook/print/ldp.dsl#print test.sgml
bash$ ls -l
-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
</PRE
></FONT
></TD
></TR
></TABLE
>
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN539"
>4.3. Generating dvi and ps</A
></H2
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN542"
></A
><P
><B
>Figure 4. Running jadetex to generate a Device Independent (dvi) file.</B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
No file test.aux.
(/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd)
LaTeX Warning: Reference `TEST1' on page 1 undefined on input line 238.
LaTeX Warning: Reference `20' on page 1 undefined on input line 262.
LaTeX Warning: Reference `23' on page 1 undefined on input line 285.
LaTeX Warning: Reference `TEST2' on page 1 undefined on input line 316.
LaTeX Warning: Reference `30' on page 1 undefined on input line 340.
LaTeX Warning: Reference `33' on page 1 undefined on input line 363.
[1.0.46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
(test.aux)
LaTeX Warning: There were undefined references.
)
Output written on test.dvi (3 pages, 34984 bytes).
Transcript written on test.log.
bash$ ls -l
total 80
-rw-r--r-- 1 reaster users 771 Dec 31 20:55 test.aux
-rw-r--r-- 1 reaster users 34984 Dec 31 20:55 test.dvi
-rw-r--r-- 1 reaster users 5072 Dec 31 20:55 test.log
-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
bash$ jadetex test.tex
This is TeX, Version 3.14159 (Web2C 7.3.1)
(test.tex
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46]
(/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) )
Output written on test.dvi (3 pages, 34148 bytes).
Transcript written on test.log.
You have new mail in /var/spool/mail/reaster
bash$ ls -l
total 80
-rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux
-rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi
-rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log
-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
bash$
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
</P
><P
> The first time <B
CLASS="COMMAND"
>jadetex</B
> is run, warnings are printed. They can
be ignored. Running it a second time, they do not appear again.
</P
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN548"
></A
><P
><B
>Figure 5. Running <B
CLASS="COMMAND"
>dvips</B
> to generate a <SPAN
CLASS="PRODUCTNAME"
>PostScript</SPAN
> (ps) file.</B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>bash$ ls -l
total 80
-rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux
-rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi
-rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log
-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
bash$ dvips test.dvi
This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com)
' TeX output 2000.12.31:2058' -> test.ps
<texc.pro><8r.enc><texps.pro><special.pro><color.pro>. [1] [2] [3]
bash$ ls -l
total 116
-rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux
-rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi
-rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log
-rw-r--r-- 1 reaster users 34817 Dec 31 21:06 test.ps
-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
bash$
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
</P
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN554"
></A
><P
><B
>Figure 6. Running <B
CLASS="COMMAND"
>htmldoc</B
> to generate a <SPAN
CLASS="PRODUCTNAME"
>PostScript</SPAN
> (<TT
CLASS="FILENAME"
>ps</TT
>) file.</B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>bash$ ls -l
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml | htmldoc -f test-htmldoc.ps -
bash$ ls -l
-rw-r--r-- 1 reaster users 9050 Jan 1 00:44 test-htmldoc.ps
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
If the <TT
CLASS="FILENAME"
>ps</TT
> file doesn't appear as expected, it may be due
to bugs in <B
CLASS="COMMAND"
>htmldoc</B
>. Look inside the <B
CLASS="COMMAND"
>ldp_print</B
>
script if you want to use it to make <TT
CLASS="FILENAME"
>ps</TT
>.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN564"
>4.4. Generating pdf</A
></H2
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN567"
></A
><P
><B
>Figure 7. Running <B
CLASS="COMMAND"
>pdfjadetex</B
> to generate a Portable Document Format (<TT
CLASS="FILENAME"
>pdf</TT
>) file.</B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>bash$ ls -l
-rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux
-rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi
-rw-r--r-- 1 reaster users 4433 Dec 31 20:58 test.log
-rw-r--r-- 1 reaster users 34817 Dec 31 21:06 test.ps
-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
bash$ pdfjadetex test.tex
This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1)
(test.tex[/usr/share/texmf/pdftex/config/pdftex.cfg]
JadeTeX 1999/06/29: 2.7
(/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
(/usr/share/texmf/tex/jadetex/isoents.tex)
Elements will be labelled
Jade begin document sequence at 19
(test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
(/usr/share/texmf/tex/latex/base/ts1cmr.fd)
(/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
(/usr/share/texmf/tex/context/base/supp-pdf.tex
(/usr/share/texmf/tex/context/base/supp-mis.tex
loading : Context Support Macros / Missing
)
loading : Context Support Macros / PDF
) (/usr/share/texmf/tex/latex/hyperref/nameref.sty)
(/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46[/usr/share/texmf/dvips/con
fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
(test.aux) )<8r.enc>
Output written on test.pdf (3 pages, 9912 bytes).
Transcript written on test.log.
bash$ ls -l
total 128
-rw-r--r-- 1 reaster users 753 Dec 31 21:13 test.aux
-rw-r--r-- 1 reaster users 34148 Dec 31 20:58 test.dvi
-rw-r--r-- 1 reaster users 5075 Dec 31 21:13 test.log
-rw-r--r-- 1 reaster users 9912 Dec 31 21:13 test.pdf
-rw-r--r-- 1 reaster users 34817 Dec 31 21:06 test.ps
-rw-r--r-- 1 reaster users 4584 Dec 31 20:51 test.rtf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
-rw-r--r-- 1 reaster users 18719 Dec 31 20:51 test.tex
bash$
bash$ pdfjadetex test.tex
[snip]
bash$ pdfjadetex test.tex
[snip]
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
<B
CLASS="COMMAND"
>pdfjadetex</B
> must be run up to three times to resolve all
internal references for things such as TOC page numbers.
</P
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN574"
></A
><P
><B
>Figure 8. Running <B
CLASS="COMMAND"
>htmldoc</B
> to generate a Portable Document Format (<TT
CLASS="FILENAME"
>pdf</TT
>) file.</B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>bash$ ls -l
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml > test-htmldoc.htm
bash$ ldp_print test-htmldoc.htm
bash$ ls -l
-rw-r--r-- 1 reaster users 9050 Jan 1 01:17 test-htmldoc.pdf
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
bash$
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
If enabled in the <B
CLASS="COMMAND"
>ldp_print</B
> script, this would generate a <TT
CLASS="FILENAME"
>ps</TT
> file
also.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN581"
>4.5. Using <B
CLASS="COMMAND"
>make</B
></A
></H2
><P
> Repeating the commands to generate the output files is tedious.
The <B
CLASS="COMMAND"
>make</B
> command works perfectly to automate the process.
</P
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN587"
></A
><P
><B
>Figure 9. Filename: <TT
CLASS="FILENAME"
>Makefile</TT
> - automates document generation.</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="PROGRAMLISTING"
># Generates online and print versions of SGML source file.
BASENAME=DocBook-Install
# SGML source file.
SGML_FILE=$(BASENAME).sgml
# Stylesheets
DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print
DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html
# Generated files.
HTML_FILE=index.html
HTM_FILE=$(BASENAME).htm
TEX_FILE=$(BASENAME).tex
RTF_FILE=$(BASENAME).rtf
PDF_FILE=$(BASENAME).pdf
DVI_FILE=$(BASENAME).dvi
PS_FILE=$(BASENAME).ps
# Build rules.
html: $(HTML_FILE)
htm: $(HTM_FILE)
tex: $(TEX_FILE)
rtf: $(RTF_FILE)
pdf: $(PDF_FILE)
dvi: $(DVI_FILE)
ps: $(PS_FILE)
all: html htm tex rtf pdf dvi ps
clean:
rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot}
rm -f *.html
distclean: clean
rm -f $(BASENAME).tgz
package:
rm -f $(BASENAME).tgz
tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
mv /tmp/$(BASENAME).tgz .
dist: clean package
distall: all package
# Compile rules.
$(HTML_FILE): $(SGML_FILE)
openjade -t sgml -d $(DSL_HTML) $(SGML_FILE)
$(HTM_FILE): $(SGML_FILE)
openjade -t sgml -V nochunks -d $(DSL_HTML) \
$(SGML_FILE) > $(HTM_FILE)
$(TEX_FILE): $(SGML_FILE)
openjade -t tex -d $(DSL_PRINT) $(SGML_FILE)
$(RTF_FILE): $(SGML_FILE)
openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE)
# [pdf]jadetex is run 3 times to resolve references.
#$(PDF_FILE): $(TEX_FILE)
# pdfjadetex $(TEX_FILE)
# pdfjadetex $(TEX_FILE)
# pdfjadetex $(TEX_FILE)
# This *should* work, but htmldoc has bugs ...
#$(PDF_FILE): $(SGML_FILE)
# openjade -t sgml -V nochunks -d $(DSL_HTML) \
# $(SGML_FILE) | htmldoc -f $(PDF_FILE) -
# Have to use ldp_print to work around htmldoc bugs
# ldp_print can also do the ps file - see script
$(PDF_FILE): $(HTM_FILE)
ldp_print $(HTM_FILE)
$(DVI_FILE): $(TEX_FILE)
jadetex $(TEX_FILE)
jadetex $(TEX_FILE)
jadetex $(TEX_FILE)
$(PS_FILE): $(DVI_FILE)
dvips $(DVI_FILE)
#$(PS_FILE): $(SGML_FILE)
# openjade -t sgml -V nochunks -d $(DSL_HTML) \
# $(SGML_FILE) | htmldoc -f $(PS_FILE) -
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
</P
><P
> Usage is just like for most projects:
<DIV
CLASS="FIGURE"
><A
NAME="AEN592"
></A
><P
><B
>Figure 10. Invoking <B
CLASS="COMMAND"
>make</B
> to run <TT
CLASS="FILENAME"
>Makefile</TT
></B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
> -- generate html (default)
make
-- generate just pdf
make pdf
-- generate all files
make all
-- delete all generated files
make clean
-- create tgz distribution
-- with no generated files
make dist
-- create tgz distribution
-- containing all generated files
make distall
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
</P
><P
> Notice the commented compile rules for <TT
CLASS="FILENAME"
>pdf</TT
> and <TT
CLASS="FILENAME"
>ps</TT
> which
provide alternative means of generating those files.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN600"
>4.6. Generating a <B
CLASS="COMMAND"
>man</B
> page</A
></H2
><P
> During the section on installing everything, we installed
the <B
CLASS="COMMAND"
>perl</B
> version 5 module <TT
CLASS="FILENAME"
>SGMLS.pm</TT
>.
Then we installed Docbook2X which provides the <TT
CLASS="FILENAME"
>spec.pl</TT
> files for transforming
DocBook <TT
CLASS="SGMLTAG"
><refentry></TT
> documents into
<B
CLASS="COMMAND"
>nroff</B
> (<B
CLASS="COMMAND"
>man</B
> page) format
with <B
CLASS="COMMAND"
>sgmlspl</B
>.
</P
><P
> An example Docbook <TT
CLASS="SGMLTAG"
><refentry></TT
> document, for the
<B
CLASS="COMMAND"
>foo</B
> command, is given below.
</P
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN615"
></A
><P
><B
>Figure 11. <B
CLASS="COMMAND"
>foo</B
> command <B
CLASS="COMMAND"
>man</B
> page, docbook <TT
CLASS="SGMLTAG"
><refentry></TT
> source (<TT
CLASS="FILENAME"
>foo-ref.sgml</TT
>)</B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
><!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>
<refentryinfo>
<date>2001-01-01</date>
</refentryinfo>
<refmeta>
<refentrytitle>
<application>foo</application>
</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>foo 1.0</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
<application>foo</application>
</refname>
<refpurpose>
Does nothing useful.
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2001-01-01</date>
</refsynopsisdivinfo>
<cmdsynopsis>
<command>foo</command>
<arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
<arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
<arg rep="repeat"><replaceable class="parameter">file</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<refsect1info>
<date>2001-01-01</date>
</refsect1info>
<title>DESCRIPTION</title>
<para>
<command>foo</command> does nothing useful.
</para>
</refsect1>
<refsect1>
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>-f <replaceable class="parameter">bar</replaceable></term>
<listitem>
<para>
Takes <filename>bar</filename> as it's run
control file. If this were a real program,
there might be more to say here about what
bar is and how it will be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-d<replaceable class="parameter">n</replaceable></term>
<listitem>
<para>
Do something, where integer
<replaceable class="parameter">n</replaceable>
specifies how many times.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">file...</replaceable></term>
<listitem>
<para>
Processes the files in the order listed,
sending all output to stdout.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>USAGE</title>
<para>
<command>foo</command> -f foo.conf -d2 foodata.foo
</para>
</refsect1>
<refsect1>
<title>CAVEATS</title>
<para>
Other programs named <command>foo</command> may exist and actually
do something!
</para>
</refsect1>
<refsect1>
<title>BUGS</title>
<para>
None. Program does nothing.
</para>
</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
<author>
<firstname>Foo</firstname>
<othername role="mi">E</othername>
<surname>Bar</surname>
<contrib>Original author</contrib>
</author>
</para>
</refsect1>
</refentry>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
</P
><P
> <DIV
CLASS="FIGURE"
><A
NAME="AEN623"
></A
><P
><B
>Figure 12. Generating a <B
CLASS="COMMAND"
>man</B
> page with <B
CLASS="COMMAND"
>onsgmls</B
>, <B
CLASS="COMMAND"
>sgmlspl</B
>, and <TT
CLASS="FILENAME"
>docbook2man-spec.pl</TT
></B
></P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>bash$ ls -l
-rw-r--r-- 1 reaster users 2434 Jan 3 03:51 foo-ref.sgml
bash$ onsgmls foo-ref.sgml | sgmlspl $SGML_SHARE/docbook2X/docbook2man-spec.pl
bash$ ls -l
-rw-r--r-- 1 reaster users 2434 Jan 3 03:51 foo-ref.sgml
-rw-r--r-- 1 reaster users 1129 Jan 3 04:03 foo.1
-rw-r--r-- 1 reaster users 0 Jan 3 04:03 manpage.links
-rw-r--r-- 1 reaster users 0 Jan 3 04:03 manpage.log
-rw-r--r-- 1 reaster users 15 Jan 3 04:03 manpage.refs
bash$ groff -mandoc -Tascii foo.1
FOO(1) FOO(1)
NAME
foo - Does nothing useful.
SYNOPSIS
foo [ -f bar ] [ -dn ] [ file... ]
DESCRIPTION
foo does nothing useful.
OPTIONS
-f bar Takes bar as its run control file. If this were a
real program, there might be more to say here about
what bar is and how it will be used.
-dn Do something, where integer n specifies how many
times.
file...
Processes the files in the order listed, sending
all output to stdout.
USAGE
foo -f foo.conf -d2 foodata.foo
CAVEATS
Other programs named foo may exist and actually do some-
thing!
BUGS
None. Program does nothing.
AUTHOR
Foo E Bar (Original author)
[snip - several extra blank lines that man would not show]
foo 1.0 2001-01-01 1
bash$ groff -mandoc -Tascii foo.1 | less
bash$ less foo.1
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
>
</P
><P
> The <B
CLASS="COMMAND"
>man</B
> page, <TT
CLASS="FILENAME"
>foo.1</TT
>, is generated as a Section 1 page. The
<B
CLASS="COMMAND"
>groff</B
> command is used to give a quick look at its formatted
appearance.
</P
><P
> To <B
CLASS="COMMAND"
>install</B
> this <B
CLASS="COMMAND"
>man</B
> page, it belongs in any <TT
CLASS="FILENAME"
>man/man1</TT
> directory,
where the directory <TT
CLASS="FILENAME"
>man/</TT
> is added to <TT
CLASS="ENVAR"
>$MANPATH</TT
>
in the environment. The standard location is
<TT
CLASS="FILENAME"
>/usr/local/man/man1</TT
>.
The standard sections in the <B
CLASS="COMMAND"
>man</B
> pages system are 1 though 9.
Each is for holding specific catagories of documentation.
</P
><DIV
CLASS="TABLE"
><A
NAME="AEN642"
></A
><P
><B
>Table 1. Manual Pages Sections</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="CENTER"
VALIGN="TOP"
>Section</TH
><TH
ALIGN="CENTER"
VALIGN="TOP"
>Purpose</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man1</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>User programs</TD
></TR
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man2</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>System calls</TD
></TR
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man3</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>Library functions and subroutines</TD
></TR
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man4</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>Devices</TD
></TR
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man5</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>File formats</TD
></TR
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man6</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>Games</TD
></TR
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man7</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>Miscellaneous</TD
></TR
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man8</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>System administration</TD
></TR
><TR
><TD
ALIGN="CENTER"
VALIGN="TOP"
>man9</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
>Kernel internal variables and functions</TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="TIP"
><P
></P
><TABLE
CLASS="TIP"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
> The source file for a <B
CLASS="COMMAND"
>man</B
> page, like <TT
CLASS="FILENAME"
>foo-ref.sgml</TT
>,
can be processed into all the other formats just like any other
DocBook file. So using the same commands discussed earlier to generate
<TT
CLASS="FILENAME"
>html</TT
> and print output types, a <B
CLASS="COMMAND"
>man</B
> page can
be made into <TT
CLASS="FILENAME"
>html</TT
> and <TT
CLASS="FILENAME"
>rtf</TT
>, <TT
CLASS="FILENAME"
>tex</TT
>,
<TT
CLASS="FILENAME"
>pdf</TT
>, <TT
CLASS="FILENAME"
>dvi</TT
>, and <TT
CLASS="FILENAME"
>ps</TT
>.
This can really save a lot of conversion work!
</P
></TD
></TR
></TABLE
></DIV
><P
> Have fun <EM
>!</EM
>
</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="install.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="legal.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Install the Packages</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
> </TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Legal</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
