1736 lines
33 KiB
HTML
1736 lines
33 KiB
HTML
<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
|
|
> |