mirror of https://github.com/tLDP/LDP
1870 lines
58 KiB
Plaintext
1870 lines
58 KiB
Plaintext
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
|
|
|
<article lang="en">
|
|
|
|
<articleinfo>
|
|
<title>DocBook Install mini-HOWTO</title>
|
|
|
|
<author>
|
|
<firstname>Robert</firstname>
|
|
<surname>Easter</surname>
|
|
<othername role="mi">B</othername>
|
|
<affiliation>
|
|
<address>
|
|
<email>reaster@comptechnews.com</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>v1.2</revnumber>
|
|
<date>2001-01-03</date>
|
|
<authorinitials>rbe</authorinitials>
|
|
</revision>
|
|
</revhistory>
|
|
|
|
<abstract>
|
|
<para>
|
|
DocBook-Install-mini-HOWTO is a detailed practical guide for novices to
|
|
quickly getting DocBook installed and processing sgml files into html,
|
|
ps, and pdf on a GNU/Linux system - other systems may be similar. Since
|
|
setup of DocBook requires files from several separately distributed
|
|
packages, it can be confusing for beginners.
|
|
</para>
|
|
</abstract>
|
|
|
|
</articleinfo>
|
|
|
|
<sect1 id="intro">
|
|
<title>Introduction</title>
|
|
<para>
|
|
DocBook-Install-mini-HOWTO is a detailed practical guide for novices to
|
|
quickly getting DocBook installed and processing sgml files into html,
|
|
ps, and pdf on a GNU/Linux system - other systems may be similar. Since
|
|
setup of DocBook requires files from several separately distributed
|
|
packages, it can be confusing for beginners.
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>What is DocBook</title>
|
|
|
|
<para>
|
|
DocBook is a Standard Generalized Markup Language (SGML) Document
|
|
Type Definition (DTD) that defines a set of textual document markup
|
|
tags that work much like the familiar HTML language used on the web.
|
|
</para>
|
|
<para>
|
|
DocBook is intended for the authoring of books and articles. As
|
|
such, it provides tags specifically designed to describe books
|
|
and articles. For instance, the <book> and <article>
|
|
DocBook tags are used to create books and articles. Within these
|
|
documents, the <chapter>, <sect1>, and <para>
|
|
tags are used. DocBook SGML files are stored in text files with a sgml
|
|
or gml suffix.
|
|
</para>
|
|
<para>
|
|
When processed, a single DocBook SGML file can
|
|
output html, pdf, ps, txt and other formats for both
|
|
online and printed publication. The processing is governed by
|
|
stylesheets that can automatically generate a table of contents,
|
|
page numbering, chapter & section numbering, and other
|
|
features.
|
|
</para>
|
|
<para>
|
|
DocBook is also designed for authoring unix manpages using
|
|
<refentry>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Brief Overview</title>
|
|
<para>
|
|
Here are brief descriptions of the packages we will work with in the next sections:
|
|
</para>
|
|
|
|
<formalpara>
|
|
<title>OpenJade</title>
|
|
<para>
|
|
OpenJade is an Standard Generalized Markup Language (SGML)
|
|
and Document Style Semantics and Specification Language
|
|
(DSSSL) processor. It processes DocBook sgml source
|
|
files into html, tex, rtf, txt and others. Openjade is
|
|
the essential engine for converting a DocBook file into
|
|
other formats. The tex out format is used mostly as an
|
|
intermediate format to obtain dvi, pdf, and ps via
|
|
TeX macros and dvi converters.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title>DocBook SGML DTD</title>
|
|
<para>
|
|
The Document Type Definition (DTD) files are SGML files
|
|
that define the DocBook language. Its defines the
|
|
valid tag set and rules of their use. OpenJade
|
|
requires access to the DTD files for every document
|
|
type that it parses.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<FormalPara>
|
|
<title>ISO8879 ENTITY SGML</title>
|
|
<para>
|
|
Entities define how to represent special characters that
|
|
have either no keyboard key or have special meaning
|
|
in SGML. Examples familiar from HTML include
|
|
"&amp;"='&', "&gt;"='>', and "&lt;"='<'.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title>DocBook DSSSL</title>
|
|
<para>
|
|
Document Style Semantics and Specification Language (DSSSL)
|
|
files (dsl suffix) for a particular DTD, in this case DocBook,
|
|
specify how to convert DocBook into html, rtf, tex etc.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title>SgmlTools-lite</title>
|
|
<para>
|
|
Sgmltools is a frontend wrapper for running openjade and the
|
|
TeX macros jadetex and pdfjadetex, macros included with openjade.
|
|
Converting a DocBook file to ps or pdf is a two or three-step
|
|
process. OpenJade outputs a tex file which is the input of jadetex, to
|
|
produce a dvi, and pdfjadetex, to produce a pdf. A ps file is obtained
|
|
by passing the dvi file through dvips. The sgmltools script provides
|
|
a single command to perform these tasks.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title>HTMLdoc</title>
|
|
<para>
|
|
HTMLdoc is a free program for converting html files into a
|
|
pdf or ps file.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title>SGMLSpm and docbook2X</title>
|
|
<para>
|
|
Together, these two are used to generate manpages. SGMLSpm is a perl5 module
|
|
library for processing parsed output from <filename>onsgmls</filename>, a program
|
|
included with OpenJade. SGMLSpm includes an application called <filename>sgmlspl</filename>
|
|
to use the SGMLSpm library. <filename>Sgmlspl</filename> requires "spec files",
|
|
which are available from various other sources on the Internet, for each
|
|
type of document transformation to be performed. DocBook2X is a package that
|
|
provides the spec files for transforming DocBook files into manpages.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1 id="download">
|
|
<title>Download the Packages</title>
|
|
<para>
|
|
In this section, we will locate and download the software on the Internet.
|
|
</para>
|
|
|
|
|
|
<sect2>
|
|
<title>OpenJade</title>
|
|
<para>
|
|
OpenJade is an actively maintained open-source software project based
|
|
on the Jade package by <ulink url="http://www.jclark.com/">James Clark</ulink>.
|
|
Download the lastest stable release (1.3?) at:
|
|
</para>
|
|
<para>
|
|
<ulink url="http://openjade.sourceforge.net/">http://openjade.sourceforge.net/</ulink>
|
|
</para>
|
|
<para>
|
|
OpenJade also includes the OpenSP package and the TeX macros, jadetex and pdfjadetex
|
|
for converting files to dvi and pdf. The following program are provided by this
|
|
package:
|
|
</para>
|
|
<ItemizedList>
|
|
<ListItem><para>openjade</para></ListItem>
|
|
<ListItem><para>onsgmls</para></ListItem>
|
|
<ListItem><para>osgmlnorm</para></ListItem>
|
|
<ListItem><para>ospam</para></ListItem>
|
|
<ListItem><para>ospent</para></ListItem>
|
|
<ListItem><para>osx</para></ListItem>
|
|
</ItemizedList>
|
|
|
|
<para>
|
|
To use the jadetex and pdfjadetex for making dvi, ps, and pdf, you must have
|
|
a working TeX (tex) installation. If you do not have TeX, check with your
|
|
Linux distribution for a binary package that can be downloaded and installed.
|
|
Otherwise, you can download the <ProductName>teTeX</ProductName> distribution
|
|
of TeX from:
|
|
</para>
|
|
<para>
|
|
<ulink url="http://www.tug.org/tetex/">http://www.tug.org/tetex/</ulink>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>DocBook SGML DTD</title>
|
|
|
|
<para>The DocBook DTD for SGML and XML are maintained by a technical committee at
|
|
<ulink url="http://www.oasis-open.org/">Oasis-Open.ORG</ulink>. Download the current
|
|
version (and any old versions you might need) of DocBook SGML at:
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://www.oasis-open.org/docbook/sgml/index.html">http://www.oasis-open.org/docbook/sgml/index.html</ulink>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>ISO8879 ENTITY SGML</title>
|
|
<para>
|
|
The entities define representations for special or untypeable symbols or characters, including
|
|
mathematical symbols, and the entities that you may be familiar with from HTML. These entity
|
|
files need to be installed for a proper configuration.
|
|
</para>
|
|
|
|
<ItemizedList>
|
|
<ListItem>
|
|
<para>Resources at <ulink url="http://www.oasis-open.org/">OASIS</ulink>:
|
|
<ItemizedList>
|
|
<ListItem><para><ulink url="http://www.oasis-open.org/cover/topics.html#entities">http://www.oasis-open.org/cover/topics.html#entities</ulink></para></ListItem>
|
|
<ListItem><para><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">http://www.oasis-open.org/cover/ISOEnts.zip</ulink></para></ListItem>
|
|
<ListItem><para><ulink url="http://www.oasis-open.org/cover/isoENT-tar.gz">http://www.oasis-open.org/cover/isoENT-tar.gz</ulink></para></ListItem>
|
|
</ItemizedList>
|
|
</para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
|
|
<para>
|
|
ISOEnts.zip can simply be unzipped into the directory where the DocBook DTD is unzipped without requiring anything else but
|
|
the files in isoENT-tar.gz are also needed. Again, the files in isoENT-tar.gz are to be unzipped into the DocBook DTD
|
|
directory (see next section on installing for details), but the filenames end with ".ent" suffix. These will need to
|
|
be renamed to a ".gml" ending. You can do this manually, or you can download and use the file below, made by this
|
|
author, which contains the files of both ISOEnts.zip and isoENT-tar.gz:
|
|
</para>
|
|
<para>
|
|
<ulink url="http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz">http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz</ulink>
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>DocBook DSSSL</title>
|
|
<para>
|
|
The Document Style Semantics and Specification Language (DSSSL) files for the DocBook DTD (SGML/XML)
|
|
is provided by <ulink url="http://www.nwalsh.com/">Norm Walsh</ulink>. These files, called the
|
|
<ulink url="http://nwalsh.com/docbook/dsssl/">Modular DocBook Stylesheets</ulink>, tell <filename>openjade</filename> what
|
|
to do when converting your DocBook SGML file into other formats. A dsl file specifies things such as the
|
|
mappings from one DTD's tags to another DTD's tags and other programmatic conversions, programmed in a
|
|
language called the <ulink url="http://www.nwalsh.com/">Core Expression Language</ulink> which is derived from
|
|
<ulink url="http://www.gnu.org/manual/elisp-manual-20-2.5/html_chapter/elisp_2.html#SEC5">Scheme</ulink>.
|
|
The DocBook DSSSL package and documentation can be downloaded from Norm Walsh:
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://nwalsh.com/docbook/dsssl/">http://nwalsh.com/docbook/dsssl/</ulink>
|
|
</para>
|
|
|
|
<para>
|
|
The <ulink url="http://www.linuxdoc.org/">Linux Documentation Project</ulink> has a stylesheet
|
|
customization file that turns on some nice style features. It can be downloaded at:
|
|
</para>
|
|
<para>
|
|
<ulink url="http://www.linuxdoc.org/authors/tools/ldp.dsl">http://www.linuxdoc.org/authors/tools/ldp.dsl</ulink>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Sgmltools-lite</title>
|
|
<para>
|
|
Sgmltools is a frontend for openjade, <filename>jadetex</filename>, <filename>pdfjadex</filename>,
|
|
<filename>dvips</filename>, and other programs. It
|
|
provides a single command for generating all the formats possible with these tools. The
|
|
lastest release, v1.3 as of writing, can be downloaded at:
|
|
</para>
|
|
<para><ulink url="http://www.sgmltools.org/">http://www.sgmltools.org/</ulink></para>
|
|
<para><ulink url="http://sourceforge.net/projects/sgmltools-lite/">http://sourceforge.net/projects/sgmltools-lite/</ulink></para>
|
|
<para>
|
|
This package is optional, but does make things easier sometimes.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>HTMLdoc</title>
|
|
<para>
|
|
Htmldoc is a free program for converting websites into Portable Document Format (pdf)
|
|
or Postscript (ps). For pdf, it creates a tree of bookmarks that make navigation easy.
|
|
Both htmldoc and pdfjadetex output pdf files, but in slightly different formats. Try
|
|
both and see which turns out best for a particular docbook file. See quick links
|
|
below for download site.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>DocBook2X</title>
|
|
<para>
|
|
DocBook2X requires perl5 and the SGMLS.pm perl module, available at CPAN. SGMLS.pm
|
|
provides libraries and a program called <filename>sgmlspl</filename> which translates DocBook files into other
|
|
formats by using specification files. The specification files are perl files that
|
|
provide the logic for the translation to a particular format.
|
|
</para>
|
|
<para><ulink url="http://www.cpan.org/">http://www.cpan.org/</ulink></para>
|
|
<para><ulink url="http://docbook2x.sourceforge.net/">http://docbook2x.sourceforge.net/</ulink></para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Quick Download Links</title>
|
|
<para>
|
|
The files below are the latest versions as of this writing:
|
|
</para>
|
|
<FormalPara>
|
|
<title><ulink url="http://download.sourceforge.net/openjade/openjade-1.3.tar.gz">openjade-1.3.tar.gz</ulink></title>
|
|
<para>
|
|
OpenJade, release version 1.3.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title><ulink url="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip">docbk41.zip</ulink></title>
|
|
<para>
|
|
DocBook SGML DTD, version 4.1.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title><ulink url="http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz">iso8879-entities.tar.gz</ulink></title>
|
|
<para>
|
|
ISO 8879 SGML entities. It's easier to just use this file. You can download the two other files
|
|
if you want and then rename filename extensions to gml.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title><ulink url="http://nwalsh.com/docbook/dsssl/db160.zip">db160.zip</ulink> & <ulink url="http://nwalsh.com/docbook/dsssl/db160d.zip">db160d.zip</ulink></title>
|
|
<para>
|
|
Norm Walsh Modular DocBook DSSSL stylesheets, version 1.60 and its <ulink url="http://nwalsh.com/docbook/dsssl/doc/">documentation</ulink>.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title><ulink url="http://download.sourceforge.net/sgmltools-lite/sgmltools-lite-3.0.2.tar.gz">sgmltools-lite-3.0.2.tar.gz</ulink></title>
|
|
<para>
|
|
Sgmltools-lite release version 3.0.2. Again, this is optional.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title><ulink url="ftp://ftp.easysw.com/pub/htmldoc/1.8.9/">ftp://ftp.easysw.com/pub/htmldoc/1.8.9/</ulink></title>
|
|
<para>
|
|
Htmldoc 1.8.9. Binaries and source are available. Choose what you
|
|
need for your platform. Binaries are recommended. To find a binary,
|
|
you can download it directly from ftp with the link above. If which to choose
|
|
is not obvious, then try to going to the EasySw website:
|
|
<ulink url="http://www.easysw.com/software.html">http://www.easysw.com/software.html</ulink>
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title><ulink url="http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz">http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz</ulink></title>
|
|
<para>
|
|
SGMLS.pm 1.03ii at CPAN. (sgmlspl)
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title><ulink url="http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz">http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz</ulink></title>
|
|
<para>
|
|
DocBook2X 0.6.0 (provides docbook2man-spec.pl for use with sgmlspl above)
|
|
</para>
|
|
</FormalPara>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="install">
|
|
<title>Install the Packages</title>
|
|
|
|
<sect2>
|
|
<title>Install OpenJade</title>
|
|
|
|
<sect3>
|
|
<title>openjade</title>
|
|
<para>
|
|
Here is what to do, but remember to read the files that come with OpenJade to see if
|
|
there are any things you want to do special for your platform:
|
|
<screen>
|
|
cd /usr/local
|
|
tar -xvzf ~/openjade-1.3.tar.gz
|
|
cd openjade-1.3
|
|
./configure --prefix=/usr/local/openjade-1.3
|
|
make
|
|
make install
|
|
-- once installed, the objects etc can be deleted
|
|
make clean
|
|
</screen>
|
|
The installation puts libraries in /usr/local/openjade-1.3/lib, so you might
|
|
like to add it to /etc/ld.so.conf and run ldconfig.
|
|
Add /usr/local/openjade-1.3/bin to your <envar>$PATH</envar>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>jadetex & pdfjadetex</title>
|
|
<para>
|
|
As mentioned, jadetex and pdfjadetex are TeX macros that are packaged with
|
|
OpenJade. They can be found in /usr/local/openjade-3.1/dsssl. A handy
|
|
guide to installing these macros was prepared by
|
|
<author>
|
|
<firstname>Frank</firstname>
|
|
<othername role="mi">Atanassow</othername>
|
|
<surname>Christoph</surname>
|
|
<affiliation>
|
|
<orgname>Next Solution Co., Ltd.</orgname>
|
|
</affiliation>
|
|
</author> and can be found at:
|
|
</para>
|
|
<para><ulink url="ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf">ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf</ulink></para>
|
|
<para><ulink url="http://www.comptechnews.com/~reaster/installjadetex.pdf">http://www.comptechnews.com/~reaster/installjadetex.pdf</ulink></para>
|
|
<para>
|
|
The following, is based on the instructions in install.pdf:
|
|
</para>
|
|
<sect4>
|
|
<title>Create hugelatex (if needed)</title>
|
|
<para>
|
|
The jadetex and pdfjadetex tex macros require more memory than a regular run of tex.
|
|
The default tex memory limit configuration is often too limited. The tex configuration file,
|
|
texmf.cnf, can be edited and variables which limit tex's memory use can be increased. But
|
|
rather than just editing the texmf.cnf file to allow tex in all instances to have more
|
|
memory, a custom tex context can be created, called hugelatex. If hugelatex is already
|
|
configured on your system, you can skip this subsection (which hugelatex).
|
|
</para>
|
|
<para>
|
|
Verify that a working TeX is installed and find its directory:
|
|
<screen>
|
|
bash-2.04$ which tex
|
|
/usr/share/texmf/bin/tex
|
|
bash-2.04$ kpsewhich -expand-var='$TEXMFMAIN'
|
|
/usr/share/texmf
|
|
bash-2.04$
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Using which should find the location of the tex program. If its not
|
|
found, then you might need to install teTeX then return here.
|
|
kpsewhich is a utility that comes with teTeX and finds the main tex
|
|
directory if all goes well.
|
|
</para>
|
|
<para>
|
|
Now that the texmf directory is known, installation can begin:
|
|
<screen>
|
|
cd /usr/share/texmf
|
|
cd tex/latex
|
|
cp -r config config-temp
|
|
cd config-temp
|
|
tex -ini -progname=hugelatex tex.ini
|
|
mv latex.fmt hugelatex.fmt
|
|
mv hugelatex.fmt /usr/share/texmf/web2c
|
|
cd ..
|
|
rm -r config-temp
|
|
cd /usr/share/texmf/bin
|
|
ln -s tex hugelatex
|
|
cd /usr/share/texmf/web2c
|
|
</screen>
|
|
The web2c directory contains the texmf.cnf configuration file.
|
|
Make a backup of this file: cp texmf.cnf texmf.cnf.orig. Edit
|
|
the file using whatever editor you like, and add the following
|
|
lines at the end:
|
|
<screen>
|
|
% hugelatex settings
|
|
extra_mem_top.hugelatex = 8000000
|
|
extra_mem_bot.hugelatex = 8000000
|
|
hash_extra.hugelatex = 15000
|
|
pool_size.hugelatex = 5000000
|
|
string_vacancies.hugelatex = 45000
|
|
max_strings.hugelatex = 55000
|
|
pool_free.hugelatex = 47500
|
|
nest_size.hugelatex = 500
|
|
param_size.hugelatex = 1500
|
|
save_size.hugelatex = 5000
|
|
stack_size.hugelatex = 15000
|
|
|
|
% jadetex
|
|
extra_mem_top.jadetex = 8000000
|
|
extra_mem_bot.jadetex = 8000000
|
|
hash_extra.jadetex = 20000
|
|
pool_size.jadetex = 5000000
|
|
string_vacancies.jadetex = 45000
|
|
max_strings.jadetex = 55000
|
|
pool_free.jadetex = 47500
|
|
nest_size.jadetex = 500
|
|
param_size.jadetex = 1500
|
|
save_size.jadetex = 5000
|
|
stack_size.jadetex = 15000
|
|
|
|
% pdfjadetex
|
|
extra_mem_top.pdfjadetex = 8000000
|
|
extra_mem_bot.pdfjadetex = 8000000
|
|
hash_extra.pdfjadetex = 20000
|
|
pool_size.pdfjadetex = 5000000
|
|
string_vacancies.pdfjadetex = 45000
|
|
max_strings.pdfjadetex = 55000
|
|
pool_free.pdfjadetex = 47500
|
|
nest_size.pdfjadetex = 500
|
|
param_size.pdfjadetex = 1500
|
|
save_size.pdfjadetex = 5000
|
|
stack_size.pdfjadetex = 15000
|
|
</screen>
|
|
Here, we've gone ahead and added entries for
|
|
jadetex and pdfjadetex, which we'll be setting
|
|
up below. You can play with these memory settings
|
|
any way you like if you experience trouble with them.
|
|
</para>
|
|
<para>
|
|
After setting up hugelatex, like above, it may not
|
|
work until the texhash program is called:
|
|
<screen>
|
|
root@comptechnews:~# texhash
|
|
texhash: Updating /usr/share/texmf/ls-R...
|
|
texhash: Updating /var/cache/fonts/ls-R...
|
|
texhash: Done.
|
|
root@comptechnews:~#
|
|
</screen>
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>jadetex & pdfjadetex</title>
|
|
<para>
|
|
Setting up jadetex and pdfjadetex is similar to hugelatex.
|
|
<screen>
|
|
cd /usr/local/openjade-1.3/dsssl
|
|
make -f Makefile.jadetex install
|
|
-- make creates and installs the .fmt
|
|
-- files to /usr/share/texmf/web2c
|
|
-- now create symlinks ...
|
|
cd /usr/share/texmf/bin
|
|
ln -s tex jadetex
|
|
ln -s tex pdfjadetex
|
|
-- finally, run texhash
|
|
texhash
|
|
</screen>
|
|
This Makefile uses hugelatex, so hugelatex must have been
|
|
setup already. When tex is run as hugelatex, jadetex, or
|
|
pdfjadetex, is gets it's program name (context) from argv[0]
|
|
in the environment. Then, it scans texmf.cnf, and uses
|
|
any context-specific settings it finds. The format (.fmt)
|
|
files in /usr/share/texmf/web2c are also loaded based on
|
|
the context.
|
|
</para>
|
|
<para>
|
|
Jadetex takes a tex file generated from
|
|
openjade, and outputs a dvi. pdfjadetex takes a tex file
|
|
generated from openjade, and outputs a pdf. The dvips
|
|
program takes the dvi and outputs a postscript ps file.
|
|
</para>
|
|
</sect4>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>DocBook SGML DTD</title>
|
|
<sect3>
|
|
<title>Unpack the DocBook SGML DTD</title>
|
|
<para>
|
|
The DocBook DTD is just some sgml text files, so there is nothing to compile.
|
|
Just unzip them somewhere:
|
|
<screen>
|
|
-- DocBook DTD V4.1 in
|
|
-- /usr/local/share/sgml/docbook/4.1
|
|
cd /usr/local/share
|
|
mkdir sgml; cd sgml
|
|
mkdir docbook; cd docbook
|
|
mkdir 4.1; cd 4.1
|
|
unzip -a ~/docbk41.zip
|
|
</screen>
|
|
If you install doctools-1.2 from the XFree86 distribution, it will
|
|
put some older versions of DocBook DTD, like 2.4.1/ and 3.0/ in
|
|
subdirectories of docbook.
|
|
</para>
|
|
<para>
|
|
There are some differences between
|
|
the different versions of the DocBook DTD. The xxissues.txt files
|
|
document those issues. Tags have been added, removed, and renamed
|
|
between the versions.
|
|
</para>
|
|
<para>
|
|
If you need to use DocBook DTD V3.1, it is available from the same
|
|
place where V4.1 is downloaded. V3.1 is used a lot, so its
|
|
a good idea to get it and install it in a 3.1/ subdirectory.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Unpack the ISO8879 Entities</title>
|
|
<para>
|
|
For each DocBook DTD version unpacked, go into its directory and unpack
|
|
the iso8879-entities.tar.gz file:
|
|
<screen>
|
|
cd /usr/local/share/sgml/docbook/4.1
|
|
tar -xvzf ~/iso8879-entities.tar.gz
|
|
</screen>
|
|
In each DocBook directory, there should be a docbook.cat file or
|
|
a catalog file, or both. If both are present, they are likely to be
|
|
identical. If only docbook.cat is present, go ahead and make
|
|
a symlink:
|
|
<screen>
|
|
-- if needed
|
|
cd /usr/local/share/sgml/docbook/4.1
|
|
ln -s docbook.cat catalog
|
|
</screen>
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>DocBook DSSSL</title>
|
|
<para>
|
|
Installation of the DocBook DSSSL, which works for all versions of DocBook, is
|
|
just a matter of unzipping it somwhere.
|
|
<screen>
|
|
cd /usr/local/share/sgml
|
|
mkdir dsssl; cd dsssl
|
|
unzip -a ~/db160.zip
|
|
|
|
-- if you downloaded the ldp.dsl stylesheet
|
|
-- customization, copy it to
|
|
cd docbook
|
|
cp ~/ldp.dsl html
|
|
cp ~/ldp.dsl print
|
|
-- copy into both directories
|
|
</screen>
|
|
That's all there is to installing the DSSSL, except for the setup
|
|
of the <envar>$SGML_CATALOG_PATH</envar> discussed later. Don't
|
|
forget to straighten out the file modes and owner/group of these
|
|
unpacked files - often they are scrambled and inappropriate.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>sgmltools-lite</title>
|
|
<para>
|
|
If you like it, you can install the sgmltools-lite, but it is optional.
|
|
It's installation is the standard:
|
|
<screen>
|
|
cd /usr/src
|
|
tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz
|
|
cd sgmltools-lite-3.0.2
|
|
./configure
|
|
make install
|
|
</screen>
|
|
This installs the sgmltools python script to /usr/local/bin. Note
|
|
that it uses python, so if you don't have it, then this package
|
|
is useless.
|
|
</para>
|
|
<para>
|
|
One tweak that has to be done to make the sgmltools script work, is
|
|
you have have to edit it and set the path to openjade:
|
|
vi `which sgmltools`. Consult it's docs to learn more about it.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>htmldoc</title>
|
|
<para>
|
|
Preferrably you downloaded a binary distribution of htmldoc for
|
|
your platform. The installation is straightforward: just unpack it
|
|
and run the setup. Read the docs in the package for more info.
|
|
</para>
|
|
<para>
|
|
If you downloaded the source, installation is autoconf style.
|
|
Just run the configure script, make, make install. If all goes
|
|
well, it will install in /usr/bin.
|
|
</para>
|
|
|
|
<para>
|
|
When generating pdf and ps files from html using htmldoc, it is
|
|
desireable to suppress generation of the header-navigation and
|
|
footer-navigation links that are at the top and bottom of every
|
|
html page. These navigation features look ugly in this
|
|
case. To suppress them, a custom dsl stylesheet file is used.
|
|
</para>
|
|
<para>
|
|
The stylesheet below also directs openjade to output everything as
|
|
one chunck of data to standard out. This output is piped to htmldoc.
|
|
</para>
|
|
|
|
<para>
|
|
<Figure>
|
|
<title>htmldoc.dsl - custom DSSSL DocBook stylesheet</title>
|
|
<ProgramListing>
|
|
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
|
|
<!ENTITY % html "IGNORE">
|
|
<![%html;[
|
|
<!ENTITY % print "IGNORE">
|
|
<!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl>
|
|
]]>
|
|
<!ENTITY % print "INCLUDE">
|
|
<![%print;[
|
|
<!ENTITY docbook.dsl SYSTEM "docbook.dsl" CDATA dsssl>
|
|
]]>
|
|
]>
|
|
|
|
<style-sheet>
|
|
|
|
<style-specification id="htmldoc" use="docbook">
|
|
<style-specification-body>
|
|
|
|
(declare-characteristic preserve-sdata?
|
|
;; this is necessary because right now jadetex does not understand
|
|
;; symbolic entities, whereas things work well with numeric entities.
|
|
"UNREGISTERED::James Clark//Characteristic::preserve-sdata?"
|
|
#f)
|
|
|
|
(define %header-navigation%
|
|
;; Should navigation links be added to the top of each page?
|
|
#f)
|
|
|
|
(define %footer-navigation%
|
|
;; Should navigation links be added to the bottom of each page?
|
|
#f)
|
|
|
|
(define %generate-legalnotice-link%
|
|
;; put the legal notice in a separate file
|
|
#t)
|
|
|
|
(define %admon-graphics-path%
|
|
;; use graphics in admonitions, set their
|
|
"../images/")
|
|
|
|
(define %admon-graphics%
|
|
#f)
|
|
|
|
(define %funcsynopsis-decoration%
|
|
;; make funcsynopsis look pretty
|
|
#t)
|
|
|
|
(define nochunks
|
|
;; dont make multiple files, output all to stdout
|
|
#t)
|
|
|
|
(define %root-filename%
|
|
;; The filename of the root HTML document (e.g, "index").
|
|
"index")
|
|
|
|
(define %html-ext%
|
|
;; Default extension for HTML output files
|
|
".htm")
|
|
|
|
(define %generate-article-toc%
|
|
;; Should a Table of Contents be produced for Articles?
|
|
;; If true, a Table of Contents will be generated for each 'Article'.
|
|
#t)
|
|
|
|
(define %generate-part-toc%
|
|
#f)
|
|
|
|
(define %generate-article-titlepage%
|
|
#t)
|
|
|
|
(define (chunk-skip-first-element-list)
|
|
;; forces the Table of Contents on separate page
|
|
'())
|
|
|
|
(define %shade-verbatim%
|
|
#t)
|
|
|
|
(define %use-id-as-filename%
|
|
;; Use ID attributes as name for component HTML files?
|
|
#f)
|
|
|
|
(define %graphic-default-extension%
|
|
"gif")
|
|
|
|
(define %section-autolabel%
|
|
;; For enumerated sections (1.1, 1.1.1, 1.2, etc.)
|
|
#t)
|
|
|
|
(define (toc-depth nd)
|
|
;; more depth, 2 levels, to toc, instead of flat hierarchy
|
|
2)
|
|
|
|
</style-specification-body>
|
|
</style-specification>
|
|
|
|
<external-specification id="docbook" document="docbook.dsl">
|
|
|
|
</style-sheet>
|
|
</ProgramListing>
|
|
</Figure>
|
|
This file can be downloaded at the link below:
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://www.comptechnews.com/~reaster/htmldoc.dsl">http://www.comptechnews.com/~reaster/htmldoc.dsl</ulink>
|
|
</para>
|
|
|
|
<para>
|
|
Install the file to the same place where ldp.dsl is installed: in the
|
|
html/ directory of the Modular DocBook Stylesheets, which was installed
|
|
at /usr/local/share/sgml/dsssl/docbook in Section 3.3 above.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>DocBook2X and SGMLS.pm (sgmlspl)</title>
|
|
<sect3>
|
|
<title>sgmlspl</title>
|
|
<para>
|
|
Before the spec files from DocBook2X are of any use, the SGMLS.pm module
|
|
for perl5 has to be installed, assuming that perl5 is installed. The
|
|
installation of this module is not as automated as most perl module
|
|
installs. It uses a Makefile that has to be edited first before
|
|
running make.
|
|
<screen>
|
|
cd /usr/src
|
|
tar -xvzf ~/SGMLSpm-1.03ii.tar.gz
|
|
cd SGMLSpm
|
|
-- Edit Makfile
|
|
vi Makefile
|
|
-- In the user options of the Makefile
|
|
-- set everything correct for
|
|
-- your system.
|
|
-- Example:
|
|
-- PERL = /usr/bin/perl
|
|
-- BINDIR = /usr/local/bin
|
|
-- PERL5DIR = /usr/lib/perl5/site_perl
|
|
-- MODULEDIR = ${PERL5DIR}/SGMLS
|
|
-- SPECDIR = ${PERL5DIR}
|
|
-- HTMLDIR= /usr/local/apache/htdocs
|
|
make install
|
|
</screen>
|
|
sgmlspl gets copied to /usr/local/bin.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>docbook2X (docbook2man-spec.pl)</title>
|
|
<para>
|
|
DocBook2X contains no program to compile or install,
|
|
though it has some scripts you might want to look at,
|
|
so all there is to do is unpack it somwhere.
|
|
<screen>
|
|
cd /usr/local/share/sgml
|
|
tar -xvzf ~/docbook2X-0.6.0.tar.gz
|
|
cd docbook2X
|
|
</screen>
|
|
In the unpacked directory is the docbook2man-spec.pl and
|
|
a patch file for it that corrects a few things.
|
|
Applying the patch is optional but recommended.
|
|
<screen>
|
|
patch docbook2man-spec.pl docbook2man-spec.pl.patch
|
|
</screen>
|
|
Later, in Using DocBook, you will see how to use
|
|
sgmlspl and docbook2man-spec.pl to generate a manpage from
|
|
a refentry docbook document.
|
|
</para>
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
|
|
<sect2>
|
|
<title>$SGML_CATALOG_FILES</title>
|
|
<para>
|
|
The <envar>$SGML_CATALOG_FILES</envar> environment variable is used by
|
|
openjade (and other SGML software) to locate DTDs and DSL (stylesheets).
|
|
SGML software cannot function without finding these files, which have
|
|
been unpacked to various directories. Given the setup as done so far,
|
|
here is how <envar>$SGML_CATALOG_FILES</envar> can be set in /etc/profile:
|
|
<screen>
|
|
##########################################################################################
|
|
# SGML DocBook - openjade sgmltools-lite
|
|
JADE_HOME=/usr/local/openjade-1.3
|
|
SGML_SHARE=/usr/local/share/sgml
|
|
|
|
PATH=$PATH:$JADE_HOME/bin
|
|
|
|
# DSSSL stylesheets
|
|
# Norm Walsh's Modular DocBook Stylesheets
|
|
SGML_CATALOG_FILES=$SGML_SHARE/dsssl/docbook/catalog
|
|
# OpenJade stylesheets
|
|
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$JADE_HOME/dsssl/catalog
|
|
# sgmltools-lite's stylesheets
|
|
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/stylesheets/sgmltools/sgmltools.cat
|
|
|
|
# DocBook DTD
|
|
# From OASIS-Open.org
|
|
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.1/catalog
|
|
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/4.1/catalog
|
|
# These old ones were installed with doctools-1.2 from XFree86.org
|
|
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/2.4.1/catalog
|
|
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/docbook/3.0/catalog
|
|
|
|
# sgmltools-lite catalogs for LinuxDoc
|
|
SGML_CATALOG_FILES=$SGML_CATALOG_FILES:$SGML_SHARE/dtd/sgmltools/catalog
|
|
|
|
export JADE_HOME SGML_SHARE PATH SGML_CATALOG_FILES
|
|
##########################################################################################
|
|
</screen>
|
|
Save your profile, logout and then log back in to take effect.
|
|
</para>
|
|
<para>
|
|
Installation is complete! In the next section, we'll test the installation
|
|
and convert some test DocBook files.
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="using">
|
|
<title>Using DocBook</title>
|
|
<para>
|
|
Now that everything is installed, it's time to test it out
|
|
and see how to use openjade and sgmltools.
|
|
</para>
|
|
|
|
<para>
|
|
<figure>
|
|
<title>Example DocBook SGML file - test.sgml</title>
|
|
<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>
|
|
</screen>
|
|
</figure>
|
|
For a guide to DocBook and a reference of DocBook elements, go to:
|
|
</para>
|
|
|
|
<FormalPara>
|
|
<title>DocBook: The Definitive Reference</title>
|
|
<para>
|
|
<ulink url="http://www.docbook.org/tdg/html/docbook.html">http://www.docbook.org/tdg/html/docbook.html</ulink>
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<sect2>
|
|
<title>Generating HTML</title>
|
|
<sect3>
|
|
<title>docbook.dsl</title>
|
|
<para>
|
|
<figure>
|
|
<title>Generating HTML output using docbook.dsl</title>
|
|
<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
|
|
openjade:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported
|
|
[snip - DTDDECL catalog entries are not supported, repeats]
|
|
openjade:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported
|
|
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$
|
|
</screen>
|
|
</figure>
|
|
The warnings about DTDDECL can be ignored. They might be a little annoying,
|
|
but these warnings are normal when using jade. Other warnings and errors
|
|
should be looked at and often indicate syntax errors that you should fix.
|
|
</para>
|
|
|
|
<para>
|
|
Two htm files are generated, one for each <SECT1>. The filenames are not
|
|
very discriptive. Section one appears on the same page as the article information.
|
|
These are the results of using the default stylesheet that comes with the
|
|
Modular DocBook Stylesheets, docbook.dsl.
|
|
</para>
|
|
|
|
<para>
|
|
Stylesheets can be customized to improve on these defaults. If you
|
|
downloaded the
|
|
<ulink url="http://www.linuxdoc.org/">Linux Documentation Project</ulink>'s
|
|
ldp.dsl file and installed it as shown in Section 3.3, then you already
|
|
have a customized style available.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>ldp.dsl</title>
|
|
<para>
|
|
<figure>
|
|
<title>Generating HTML output using ldp.dsl</title>
|
|
<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$
|
|
</screen>
|
|
</figure>
|
|
</para>
|
|
<para>
|
|
Using ldp.dsl, the output looks better:
|
|
<ItemizedList>
|
|
<ListItem>
|
|
<para>
|
|
An index file has been created that contains the article information.
|
|
</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>
|
|
A table of contents has been automatically generated.
|
|
</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>
|
|
Each <SECT1> is in its own file.
|
|
</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>
|
|
Filenames are derived from ID attributes of the <SECT1> elements.
|
|
</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>
|
|
The file extension has changed to html.
|
|
</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>
|
|
The <SCREEN> elements are shaded.
|
|
</para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</para>
|
|
|
|
<para>
|
|
Note how the ldp.dsl file is written in the command line: it has "#html" appended. Lpd.dsl
|
|
contains two <STYLE-SPECIFICATION> elements, one with ID="html"
|
|
and another with ID="print". This selects the html style from within
|
|
ldp.dsl. The DocBook DSSSL contains support for converting DocBook
|
|
files into html and print formats. In Section 3.3, we copied ldp.dsl
|
|
into both the print and html directories. When generating html output,
|
|
the html style should be selected like above. When generating other types of
|
|
files, such as rtf and tex, they fall under the print style and so
|
|
the print style should be selected from ldp.dsl. The alternative is
|
|
to comment out or delete the print or html style in the copy of
|
|
ldp.dsl in the respective directory. If a dsl 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 ldp.dsl, the print style-spec
|
|
is first in the file, so it gets selected by default. So in the example above,
|
|
without appending "#html" when specifying ldp.dsl as the dsssl stylesheet,
|
|
the "print" style-spec would be selected and used when generating the html
|
|
output. It will work, but is intended for when selecting the "print/ldp.dsl"
|
|
and the formatting will be different.
|
|
</para>
|
|
|
|
<para>
|
|
To learn more about how the stylesheet customization files are made, read the
|
|
<ulink url="http://nwalsh.com/docbook/dsssl/doc/">documentation for the Modular DocBook Stylesheets</ulink>.
|
|
Customization mainly involves setting boolean option parameters to toggle style
|
|
features on and off. Completely new style logic can be programmed using
|
|
DSSSL's <ulink url="http://www.mulberrytech.com/dsssl/dsssldoc/tutorials/core-exp/core-exp.html">Core Programming Language</ulink>,
|
|
as mentioned in Section 2.4.
|
|
</para>
|
|
|
|
<para>
|
|
The openjade 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
|
|
<ulink url="http://www.w3.org/TR/html4/sgml/dtd.html">HTML Document Type Definition (DTD)</ulink>,
|
|
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 pdf and ps formats. The dsssl_spec must
|
|
specify a dsl file, not a directory.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Generating rtf and tex</title>
|
|
<para>
|
|
<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
|
|
</screen>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Generating dvi and ps</title>
|
|
<para>
|
|
<figure>
|
|
<title>Running jadetex to generate a Device Independent (dvi) file.</title>
|
|
<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$
|
|
</screen>
|
|
</figure>
|
|
</para>
|
|
<para>
|
|
The first time jadetex is run, warnings are printed. They can
|
|
be ignored. Running it a second time, they do not appear again.
|
|
</para>
|
|
<para>
|
|
<figure>
|
|
<title>Running dvips to generate a Postscript (ps) file.</title>
|
|
<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$
|
|
</screen>
|
|
</figure>
|
|
</para>
|
|
|
|
<para>
|
|
<figure>
|
|
<title>Running htmldoc to generate a Postscript (ps) file.</title>
|
|
<Screen>
|
|
bash$ ls -l
|
|
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
|
|
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/htmldoc.dsl 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$
|
|
</Screen>
|
|
</figure>
|
|
Notice the use of htmldoc.dsl, the customized dsssl stylesheet for this task.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Generating pdf</title>
|
|
<para>
|
|
<figure>
|
|
<title>Running pdfjadetex to generate a Portable Document Format (pdf) file.</title>
|
|
<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$
|
|
</screen>
|
|
</figure>
|
|
</para>
|
|
|
|
<para>
|
|
<figure>
|
|
<title>Running htmldoc to generate a Portable Document Format (pdf) file.</title>
|
|
<Screen>
|
|
bash$ ls -l
|
|
-rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml
|
|
bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/htmldoc.dsl test.sgml | htmldoc -f test-htmldoc.pdf -
|
|
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$
|
|
</Screen>
|
|
</figure>
|
|
This is nearly the same command as used to generated a ps file with htmldoc but
|
|
with just a different filename. Htmldoc understands what you want based on
|
|
the filename extension.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Using make</title>
|
|
|
|
<para>
|
|
Repeating the commands to generate the output files is tedious.
|
|
The make command works pefectly to automate the process.
|
|
</para>
|
|
|
|
<para>
|
|
<Figure>
|
|
<title>Filename: Makefile - automates document generation.</title>
|
|
|
|
<ProgramListing>
|
|
# Generates online and print versions of SGML source file.
|
|
|
|
BASENAME=DocBook-Install-mini-HOWTO
|
|
|
|
# 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
|
|
DSL_HTMLDOC=$(SGML_SHARE)/dsssl/docbook/html/htmldoc.dsl
|
|
|
|
# Generated files.
|
|
HTML_FILE=index.html
|
|
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)
|
|
|
|
tex: $(TEX_FILE)
|
|
|
|
rtf: $(RTF_FILE)
|
|
|
|
pdf: $(PDF_FILE)
|
|
|
|
dvi: $(DVI_FILE)
|
|
|
|
ps: $(PS_FILE)
|
|
|
|
all: html tex rtf pdf dvi ps
|
|
|
|
clean:
|
|
rm -f $(BASENAME).{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)
|
|
|
|
$(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_FILE): $(TEX_FILE)
|
|
# pdfjadetex $(TEX_FILE)
|
|
|
|
$(PDF_FILE): $(SGML_FILE)
|
|
openjade -t sgml -d $(DSL_HTMLDOC) $(SGML_FILE) | htmldoc -f $(PDF_FILE) -
|
|
|
|
$(DVI_FILE): $(TEX_FILE)
|
|
jadetex $(TEX_FILE)
|
|
|
|
$(PS_FILE): $(DVI_FILE)
|
|
dvips $(DVI_FILE)
|
|
|
|
#$(PS_FILE): $(SGML_FILE)
|
|
# openjade -t sgml -d $(DSL_HTMLDOC) $(SGML_FILE) | htmldoc -f $(PS_FILE) -
|
|
</ProgramListing>
|
|
|
|
</Figure>
|
|
</para>
|
|
<para>
|
|
Usage is just like for most projects:
|
|
<figure>
|
|
<title>Invoking make to run Makefile</title>
|
|
<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
|
|
</screen>
|
|
</figure>
|
|
</para>
|
|
<para>
|
|
Notice the commented compile rules for pdf and ps which
|
|
provide alternative means of generating those files.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Generating a manpage</title>
|
|
<para>
|
|
During the section on installing everything, we installed
|
|
the perl5 module SGMLSpm. Then we installed docbook2X
|
|
which provides the spec.pl files for transforming
|
|
DocBook RefEntry documents into nroff (manpage) format
|
|
with sgmlspl.
|
|
</para>
|
|
<para>
|
|
An example Docbook RefEntry document, for the
|
|
<filename>foo</filename> command, is given below.
|
|
</para>
|
|
<para>
|
|
<figure>
|
|
<title>foo manpage, docbook refentry source (foo-ref.sgml)</title>
|
|
<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>
|
|
</screen>
|
|
</figure>
|
|
</para>
|
|
|
|
<para>
|
|
<figure>
|
|
<title>Generating a manpage with onsgmls, sgmlspl, and docbook2man-spec.pl</title>
|
|
<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
|
|
onsgmls:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported
|
|
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 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.
|
|
|
|
-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
|
|
</screen>
|
|
</figure>
|
|
</para>
|
|
|
|
<para>
|
|
The manpage, <filename>foo.1</filename>, is generated as a Section 1 page. The
|
|
groff command is used to give a quick look at its formatted
|
|
appearance.
|
|
</para>
|
|
<para>
|
|
To install this manpage, it belongs in any man/man1 directory,
|
|
where the directory man/ is added to <envar>$MANPATH</envar>
|
|
in the environment. The standard location is
|
|
<filename>/usr/local/man/man1</filename>.
|
|
The standard sections in the manpages system are 1 though 9.
|
|
Each is for holding specific catagories of documentation.
|
|
</para>
|
|
|
|
<table>
|
|
<title>Manpage Sections</title>
|
|
<tgroup cols="2" align="center">
|
|
<thead>
|
|
<row>
|
|
<entry>Section</entry>
|
|
<entry>Purpose</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>man1</entry>
|
|
<entry>User programs</entry>
|
|
</row>
|
|
<row>
|
|
<entry>man2</entry>
|
|
<entry>System calls</entry>
|
|
</row>
|
|
<row>
|
|
<entry>man3</entry>
|
|
<entry>Library functions and subroutines</entry>
|
|
</row>
|
|
<row>
|
|
<entry>man4</entry>
|
|
<entry>Devices</entry>
|
|
</row>
|
|
<row>
|
|
<entry>man5</entry>
|
|
<entry>File formats</entry>
|
|
</row>
|
|
<row>
|
|
<entry>man6</entry>
|
|
<entry>Games</entry>
|
|
</row>
|
|
<row>
|
|
<entry>man7</entry>
|
|
<entry>Miscellaneous</entry>
|
|
</row>
|
|
<row>
|
|
<entry>man8</entry>
|
|
<entry>System administration</entry>
|
|
</row>
|
|
<row>
|
|
<entry>man9</entry>
|
|
<entry>Kernel internal variables and functions</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<tip>
|
|
<para>
|
|
The source file for a manpage, like <filename>foo-ref.sgml</filename>,
|
|
can be processed into all the other formats just like any other
|
|
DocBook file. So using the same commands discussed earlier to generate
|
|
html and print output types, a manpage can be made into html and rtf, tex,
|
|
pdf, dvi, and ps. This can really save a lot of conversion work!
|
|
</para>
|
|
</tip>
|
|
|
|
<para>
|
|
Have fun!
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
|
|
|
|
<sect1 id="misc">
|
|
<title>Copyright</title>
|
|
|
|
<sect2>
|
|
<title>New Versions of this Document</title>
|
|
|
|
<para>
|
|
The lastest version of this mini-HOWTO can be found at:
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://www.comptechnews.com/~reaster/mini-HOWTO/DocBook-Install-mini-HOWTO/">http://www.comptechnews.com/~reaster/mini-HOWTO/DocBook-Install-mini-HOWTO/</ulink>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="copyright">
|
|
<title>Copyright Information</title>
|
|
|
|
<para>
|
|
This document is copyrighted (c) 2000 Robert B. Easter and is
|
|
distributed under the terms of the Linux Documentation Project
|
|
(LDP) license, stated below.
|
|
</para>
|
|
|
|
<para>
|
|
Unless otherwise stated, Linux HOWTO documents are
|
|
copyrighted by their respective authors. Linux HOWTO documents may
|
|
be reproduced and distributed in whole or in part, in any medium
|
|
physical or electronic, as long as this copyright notice is
|
|
retained on all copies. Commercial redistribution is allowed and
|
|
encouraged; however, the author would like to be notified of any
|
|
such distributions.
|
|
</para>
|
|
|
|
<para>
|
|
All translations, derivative works, or aggregate works
|
|
incorporating any Linux HOWTO documents must be covered under this
|
|
copyright notice. That is, you may not produce a derivative work
|
|
from a HOWTO and impose additional restrictions on its
|
|
distribution. Exceptions to these rules may be granted under
|
|
certain conditions; please contact the Linux HOWTO coordinator at
|
|
the address given below.
|
|
</para>
|
|
|
|
<para>
|
|
In short, we wish to promote dissemination of this
|
|
information through as many channels as possible. However, we do
|
|
wish to retain copyright on the HOWTO documents, and would like to
|
|
be notified of any plans to redistribute the HOWTOs.
|
|
</para>
|
|
|
|
<para>
|
|
If you have any questions, please contact
|
|
<email>linux-howto@metalab.unc.edu</email>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="disclaimer">
|
|
<title>Disclaimer</title>
|
|
|
|
<para>
|
|
No liability for the contents of this documents can be accepted.
|
|
Use the concepts, examples and other content at your own risk.
|
|
</para>
|
|
|
|
<para>
|
|
All copyrights are held by their by their respective owners, unless
|
|
specifically noted otherwise. Use of a term in this document
|
|
should not be regarded as affecting the validity of any trademark
|
|
or service mark.
|
|
</para>
|
|
|
|
<para>
|
|
Naming of particular products or brands should not be seen
|
|
as endorsements.
|
|
</para>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
</article> |