mirror of https://github.com/tLDP/LDP
2263 lines
82 KiB
Plaintext
2263 lines
82 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@reaster.com</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>v1.8</revnumber>
|
|
<date>2002-02-04</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 files on a
|
|
<ulink url="http://www.gnu.org/gnu/linux-and-gnu.html">GNU</ulink>/<ulink url="http://www.linux.org">Linux</ulink>
|
|
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>
|
|
|
|
<sect2 id="versions">
|
|
<title>Information About this Document</title>
|
|
|
|
<para>
|
|
The lastest version of this mini-HOWTO can be found at:
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/">http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/</ulink>
|
|
</para>
|
|
|
|
<para>
|
|
See the "Legal" section in the appendix for copyright, licenses, and disclaimer information pertaining to this document.
|
|
</para>
|
|
</sect2>
|
|
|
|
|
|
<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 <SGMLTag class="StartTag">book</SGMLTag>
|
|
and <SGMLTag class="StartTag">article</SGMLTag>
|
|
DocBook tags are used to create books and articles. Within these
|
|
documents, the <SGMLTag class="StartTag">chapter</SGMLTag>,
|
|
<SGMLTag class="StartTag">sect1</SGMLTag>, and <SGMLTag class="StartTag">para</SGMLTag>
|
|
tags are used. DocBook SGML files are stored in text files with a <filename>sgml</filename>
|
|
or <filename>gml</filename> suffix.
|
|
</para>
|
|
<para>
|
|
When processed, a single DocBook SGML file can
|
|
output <filename>html</filename>, <filename>pdf</filename>, <filename>ps</filename>,
|
|
<filename>txt</filename> 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 <command>man</command> pages by writing
|
|
<SGMLTag class="StartTag">refentry</SGMLTag> documents. If you don't know what a <command>man</command> page is,
|
|
try the command <command>man man</command> on your terminal.
|
|
</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 implementation of the ISO/IEC 10179:1996
|
|
international standard Document Style Semantics and Specification
|
|
Language (DSSSL). OpenJade executes the DSSSL language to process
|
|
SGML and XML input files. In particular, it uses the Modular
|
|
DocBook Stylesheets dsl code to process DocBook SGML/XML files
|
|
into other formats such as <filename>html</filename>, <filename>tex</filename>,
|
|
<filename>rtf</filename>, <filename>txt</filename> and others.
|
|
OpenJade is the essential engine for converting a DocBook file into
|
|
other formats. The TeX output format is used mostly as an
|
|
intermediate format to obtain <filename>dvi</filename>, <filename>pdf</filename>,
|
|
and <filename>ps</filename> via TeX macros and dvi converters.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title>DocBook SGML DTD</title>
|
|
<para>
|
|
The DocBook Document Type Definition (DTD) files are SGML files
|
|
that define the DocBook language. It 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 (Modular DocBook Stylesheets)</title>
|
|
<para>
|
|
The DSSSL files (dsl suffix) for a particular DTD, in this case DocBook,
|
|
specify how to convert DocBook into html, rtf, tex etc. A
|
|
dsl file is input to <command>openjade</command> along with
|
|
your DocBook sgml file and tells <command>openjade</command>
|
|
how to transform/style your document into another file
|
|
format. The dsl for online (<filename>html</filename>) formats is often different
|
|
than for print (<filename>dvi</filename>, <filename>pdf</filename>, <filename>ps</filename>) formats.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title>SGMLtools-Lite</title>
|
|
<para>
|
|
SGMLtools-Lite is a frontend wrapper for running <command>openjade</command> and the
|
|
<command>TeX</command> macros <command>jadetex</command> and <command>pdfjadetex</command>,
|
|
macros included with OpenJade.
|
|
Converting a DocBook file to <filename>ps</filename> or <filename>pdf</filename> is a two or three-step
|
|
process. OpenJade outputs a <filename>tex</filename> file which is the input of <command>jadetex</command> to
|
|
produce a <filename>dvi</filename> file, and <command>pdfjadetex</command> to produce a <filename>pdf</filename>.
|
|
A <filename>ps</filename> file is obtained
|
|
by passing the <filename>dvi</filename> file through <command>dvips</command>. The <command>sgmltools</command>
|
|
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
|
|
<filename>pdf</filename> or <filename>ps</filename> file.
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<FormalPara>
|
|
<title>SGMLSpm and docbook2X</title>
|
|
<para>
|
|
Together, these two are used to generate <command>man</command> pages. 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 <command>man</command> pages.
|
|
</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 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, <command>jadetex</command> and <command>pdfjadetex</command>
|
|
for converting files to <filename>dvi</filename> and <filename>pdf</filename>. The following programs 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 <command>jadetex</command> and <command>pdfjadetex</command> for making
|
|
<filename>dvi</filename>, <filename>ps</filename>, and <filename>pdf</filename>, you must have
|
|
a working TeX (<command>tex</command>) 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.shtml">http://www.oasis-open.org/docbook/sgml/index.shtml</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>
|
|
<filename>ISOEnts.zip</filename> can simply be <command>unzip</command>ped into the directory where the DocBook DTD
|
|
is <command>unzip</command>ped without requiring anything else but
|
|
the files in <filename>isoENT-tar.gz</filename> are also needed. Again, the files in <filename>isoENT-tar.gz</filename>
|
|
are to be <command>unzip</command>ped into the DocBook DTD directory (see next section on installing for details),
|
|
but the filenames end with "<filename>.ent</filename>" suffix. These will need to
|
|
be renamed to a "<filename>.gml</filename>" 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 <filename>ISOEnts.zip</filename> and <filename>isoENT-tar.gz</filename>:
|
|
</para>
|
|
<para>
|
|
<ulink url="http://reaster.com/iso8879-entities.tar.gz">http://reaster.com/iso8879-entities.tar.gz</ulink>
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>DocBook DSSSL</title>
|
|
<para>
|
|
<ulink url="http://www.nwalsh.com/">Norman Walsh</ulink>'s Document Style Semantics and Specification
|
|
Language (DSSSL) files for the DocBook DTD (SGML/XML) are maintained at the
|
|
<ulink url="http://docbook.sourceforge.net/">DocBook Open Repository</ulink>
|
|
at <ulink url="http://www.sourceforge.net/">SourceForge</ulink>.
|
|
These files, also known as the <ulink url="http://docbook.sourceforge.net/projects/dsssl/doc/">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 the
|
|
<ulink url="http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/index.htm">DSSSL</ulink> language. The DSSSL
|
|
language is decomposed into a group of different languages, but running through it all is the
|
|
<ulink url="http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/h2-15.htm">Core Expression Language</ulink>
|
|
which is based on <ulink url="http://www.schemers.org/Documents/Standards/R5RS/HTML/">Scheme</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
The DocBook DSSSL package and documentation can be downloaded from the
|
|
<ulink url="http://docbook.sourceforge.net/projects/dsssl/">DocBook DSSSL Stylesheets Project</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-Lite 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 can be downloaded at:
|
|
</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 (<filename>pdf</filename>)
|
|
or <ProductName>PostScript</ProductName> (<filename>ps</filename>). For <filename>pdf</filename>, it creates
|
|
a tree of bookmarks that make navigation easy.
|
|
Both <command>htmldoc</command> and <command>pdfjadetex</command> output <filename>pdf</filename> 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>
|
|
|
|
<para>
|
|
You can download the lastest version of <ProductName>HTMLdoc</ProductName>
|
|
from <ulink url="http://www.easysw.com/">Easy Software Products</ulink>'
|
|
<ulink url="ftp://ftp.easysw.com/pub/htmldoc/">ftp site</ulink>.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>DocBook2X</title>
|
|
<para>
|
|
DocBook2X requires perl5 and the SGMLS.pm perl module, available at the Comprehensive
|
|
Perl Archive Network (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>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="install">
|
|
<title>Install the Packages</title>
|
|
<sect2>
|
|
<title>Before You Install</title>
|
|
<para>
|
|
The following sections suggest how you might install the downloaded packages to setup your
|
|
DocBook SGML environment. The examples may make reference to old versions of the packages
|
|
but you should adapt the examples and use the most recent versions instead.
|
|
</para>
|
|
<para>
|
|
For the most up-to-date, authoritative information, always read the documentation
|
|
that comes with a package you are installing. Often, you will find a <filename>README</filename>
|
|
and a <filename>INSTALL</filename> file after you unpack an archive.
|
|
</para>
|
|
<para>
|
|
The detailed instructions below may not work exactly as shown since packages are changing
|
|
all the time. However, the instructions should still give you a general idea of the procedure to
|
|
get DocBook SGML working.
|
|
</para>
|
|
</sect2>
|
|
|
|
<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>
|
|
<para>
|
|
You might be wondering why I dump the openjade source directly into <filename>/usr/local</filename>.
|
|
The author experienced some issues with openjade's installation. However, with newer releases
|
|
of OpenJade, you might try a standard (<filename>/usr/local/src</filename>) location for the
|
|
openjade source package with some other prefix install location, and see how it goes.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>jadetex & pdfjadetex</title>
|
|
<para>
|
|
As mentioned, <command>jadetex</command> and <command>pdfjadetex</command> 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://reaster.com/installjadetex.pdf">http://reaster.com/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 <command>jadetex</command> and <command>pdfjadetex</command> tex macros require more memory than a regular run of <command>tex</command>.
|
|
The default <command>tex</command> memory limit configuration is often too limited. The tex configuration file,
|
|
<filename>texmf.cnf</filename>, can be edited and variables which limit tex's memory use can be increased. But
|
|
rather than just editing the <filename>texmf.cnf</filename> file to allow tex in all instances to have more
|
|
memory, a custom <command>tex</command> context can be created, called <command>hugelatex</command>.
|
|
If <command>hugelatex</command> is already configured on your system, you can skip this
|
|
subsection (<command>which hugelatex</command>).
|
|
</para>
|
|
<para>
|
|
Verify that a working TeX is installed and find its directory:
|
|
<screen>
|
|
bash$ which tex
|
|
/usr/share/texmf/bin/tex
|
|
bash$ kpsewhich -expand-var='$TEXMFMAIN'
|
|
/usr/share/texmf
|
|
bash$
|
|
</screen>
|
|
</para>
|
|
<para>
|
|
Using <command>which</command> should find the location of the <command>tex</command> program. If its not
|
|
found, then you might need to install teTeX then return here.
|
|
<command>kpsewhich</command> is a utility that comes with teTeX and finds the main tex
|
|
directory if all goes well.
|
|
</para>
|
|
<para>
|
|
Now that the <filename>texmf</filename> 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 latex.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 <filename>web2c</filename> directory contains the <filename>texmf.cnf</filename> configuration file.
|
|
Make a backup of this file: <command>cp texmf.cnf texmf.cnf.orig</command>. 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
|
|
<command>jadetex</command> and <command>pdfjadetex</command>, 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 <command>hugelatex</command>, like above, it may not
|
|
work until the <command>texhash</command> program is called:
|
|
<screen>
|
|
root# texhash
|
|
texhash: Updating /usr/share/texmf/ls-R...
|
|
texhash: Updating /var/cache/fonts/ls-R...
|
|
texhash: Done.
|
|
root#
|
|
</screen>
|
|
</para>
|
|
</sect4>
|
|
|
|
<sect4>
|
|
<title>jadetex & pdfjadetex</title>
|
|
<para>
|
|
Setting up <command>jadetex</command> and <command>pdfjadetex</command>
|
|
is similar to <command>hugelatex</command>.
|
|
<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 pdftex pdfjadetex
|
|
|
|
# Finally, run texhash.
|
|
root# texhash
|
|
</screen>
|
|
This <filename>Makefile</filename> uses <command>hugelatex</command>,
|
|
so <command>hugelatex</command> must have been
|
|
setup already. When tex is run as <command>hugelatex</command>, <command>jadetex</command>, or
|
|
<command>pdfjadetex</command>, it gets its program name (context) from <VarName>argv[0]</VarName>
|
|
in the environment. Then, it scans <filename>texmf.cnf</filename>, and uses
|
|
any context-specific settings it finds. The format (<filename>.fmt</filename>)
|
|
files in <filename>/usr/share/texmf/web2c</filename> are also loaded based on
|
|
the context.
|
|
</para>
|
|
<para>
|
|
The <command>jadetex</command> command takes a tex file generated from
|
|
<command>openjade</command>, and outputs a <filename>dvi</filename> file.
|
|
<command>pdfjadetex</command> takes a <filename>tex</filename> file
|
|
generated from <command>openjade</command>, and outputs a <filename>pdf</filename>.
|
|
The <command>dvips</command> program takes the <filename>dvi</filename> file and outputs a <ProductName>PostScript</ProductName>
|
|
<filename>ps</filename> file that you can send to your printer or view with ghostscript <command>gs</command>.
|
|
</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 <filename>sgml</filename> text files, so there is nothing to compile.
|
|
Just <command>unzip</command> 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 <filename>doctools-1.2</filename> from the XFree86 distribution, it will
|
|
put some older versions of DocBook DTD, like <filename>2.4.1/</filename> and
|
|
<filename>3.0/</filename> in subdirectories of <filename>docbook</filename>.
|
|
</para>
|
|
<para>
|
|
There are some differences between
|
|
the different versions of the DocBook DTD. The <filename>xxissues.txt</filename> 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 <filename>3.1/</filename> subdirectory.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Unpack the ISO8879 Entities</title>
|
|
<para>
|
|
For each DocBook DTD version unpacked, go into its directory and unpack
|
|
the <filename>iso8879-entities.tar.gz</filename> 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 <filename>docbook.cat</filename> file or
|
|
a <filename>catalog</filename> file, or both. If both are present, they are likely to be
|
|
identical. If only <filename>docbook.cat</filename> 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 <command>unzip</command>ping 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.
|
|
Its 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 <command>sgmltools</command> <command>python</command> script to
|
|
<filename>/usr/local/bin</filename>. Note that it uses <command>python</command>,
|
|
so if you don't have it, then this package is useless.
|
|
</para>
|
|
<para>
|
|
One tweak that has to be done to make the <command>sgmltools</command> script work, is
|
|
you have to edit it and set the path to <command>openjade</command>:
|
|
<command>vi `which sgmltools`</command>. Consult its docs to learn more about it.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>htmldoc</title>
|
|
|
|
<sect3>
|
|
<title>binary</title>
|
|
<para>
|
|
Preferrably you downloaded a binary distribution of <command>htmldoc</command> for
|
|
your platform. The installation is straightforward: just unpack it
|
|
and run the setup. Read the docs in the package for more info.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>source</title>
|
|
<para>
|
|
If you downloaded the source, you will also need the <emphasis>Fast Light Tool Kit</emphasis>
|
|
or else it will not link:
|
|
</para>
|
|
<para>
|
|
<ulink url="http://www.fltk.org/">http://www.fltk.org/</ulink>
|
|
</para>
|
|
|
|
<para>
|
|
Installation is <command>autoconf</command> style.
|
|
Just run the <command>configure</command> script, <command>make</command>,
|
|
<command>make install</command>. If all goes well, it will install in
|
|
<filename>/usr/bin</filename>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>ldp_print</title>
|
|
<para>
|
|
The <command>htmldoc</command> program has (or had) a few glitches when generating output from
|
|
<filename>html</filename> files from <command>openjade</command>. For instance, bullet items are not
|
|
rendered properly and shaded areas are not always shaded.
|
|
</para>
|
|
<para>
|
|
To fix this problem, a <command>perl</command> script
|
|
(<ulink url="http://www.linuxdoc.org/authors/tools/ldp_print.tar.gz">ldp_print</ulink>)
|
|
is available from <ulink url="http://www.linuxdoc.org/">LinuxDoc.org</ulink>.
|
|
The <command>lpd_print</command> script processes a nochunks <filename>html</filename>
|
|
file from <command>openjade</command> and then runs <command>htmldoc</command>
|
|
on it to produce correctly rendered <filename>pdf</filename> and <filename>ps</filename>.
|
|
<tip><para>Get it!</para></tip>
|
|
</para>
|
|
<para>
|
|
<screen>
|
|
tar -xvzf ldp_print.tar.gz
|
|
cd ldp_print
|
|
|
|
# Copy the lib somewhere where perl looks.
|
|
cp fix_print_html.lib /usr/lib/perl5/site_perl
|
|
|
|
cp ldp_print /usr/local/bin
|
|
</screen>
|
|
Take a look at the script in case there are lines in it you need
|
|
to change for your system. Perhaps someday <command>htmldoc</command>'s bugs will
|
|
be fixed and this script will not be needed anymore.
|
|
</para>
|
|
</sect3>
|
|
|
|
</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 <filename>SGMLS.pm</filename> module
|
|
for <command>perl</command> version 5 has to be installed, assuming that
|
|
<command>perl</command> version 5 is installed. The
|
|
installation of this module is not as automated as most <command>perl</command> module
|
|
installs. It uses a <filename>Makefile</filename> that has to be edited first before
|
|
running <command>make</command>.
|
|
<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 <command>install</command>,
|
|
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 <filename>docbook2man-spec.pl</filename> 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 <emphasis>Using DocBook</emphasis>, you will see how to use
|
|
<command>sgmlspl</command> and <filename>docbook2man-spec.pl</filename>
|
|
to generate a <command>man</command> page from a <SGMLTag class="StartTag">refentry</SGMLTag>
|
|
DocBook document.
|
|
</para>
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
|
|
<sect2>
|
|
<title>$SGML_CATALOG_FILES</title>
|
|
<para>
|
|
The <envar>$SGML_CATALOG_FILES</envar> environment variable is used by
|
|
<command>openjade</command> (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 <filename>/etc/profile</filename>:
|
|
<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
|
|
# Norman 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 <filename>profile</filename>, <command>logout</command> and then log back in to take effect.
|
|
</para>
|
|
<para>
|
|
Installation is complete! In the next section, we'll test the installation
|
|
and <command>convert</command> 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 <command>openjade</command> and the other tools.
|
|
</para>
|
|
|
|
<para>
|
|
<figure>
|
|
<title>Example DocBook SGML file - <filename>test.sgml</filename></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, see:
|
|
</para>
|
|
|
|
<FormalPara>
|
|
<title>DocBook: The Definitive Guide</title>
|
|
<para>
|
|
<ulink url="http://www.docbook.org/tdg/en/">http://www.docbook.org/tdg/en/</ulink>
|
|
</para>
|
|
</FormalPara>
|
|
|
|
<sect2>
|
|
<title>Generating HTML</title>
|
|
<sect3>
|
|
<title><filename>docbook.dsl</filename></title>
|
|
<para>
|
|
<figure>
|
|
<title>Generating HTML output using <filename>docbook.dsl</filename></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
|
|
[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$
|
|
</screen>
|
|
</figure>
|
|
The warnings about <VarName>DTDDECL</VarName> can be ignored. They might be a little annoying,
|
|
but these warnings are normal when using <command>openjade</command>. Other warnings and errors
|
|
should be looked at and often indicate syntax errors that you should fix.
|
|
</para>
|
|
|
|
<para>
|
|
Two <filename>htm</filename> files are generated, one for each <SGMLTag class="StartTag">sect1</SGMLTag>.
|
|
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
|
|
<emphasis>Modular DocBook Stylesheets</emphasis>, <filename>docbook.dsl</filename>.
|
|
</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
|
|
<filename>ldp.dsl</filename> file and installed it as shown in Section 3.3,
|
|
then you already have a customized style available.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title><filename>ldp.dsl</filename></title>
|
|
<para>
|
|
<figure>
|
|
<title>Generating HTML output using <filename>ldp.dsl</filename></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 <filename>ldp.dsl</filename>, 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 <SGMLTag class="StartTag">sect1</SGMLTag> is in its own file.
|
|
</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>
|
|
Filenames are derived from ID attributes of the <SGMLTag class="StartTag">sect1</SGMLTag> elements.
|
|
</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>
|
|
The file extension has changed to <filename>html</filename>.
|
|
</para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<para>
|
|
The <SGMLTag class="StartTag">screen</SGMLTag> elements are shaded.
|
|
</para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</para>
|
|
|
|
<para>
|
|
Note how the <filename>ldp.dsl</filename> file is written in the command line:
|
|
it has "<filename>#html</filename>" appended. <filename>ldp.dsl</filename>
|
|
contains two <SGMLTag class="StartTag">STYLE-SPECIFICATION</SGMLTag> elements, one with
|
|
ID="html" and another with ID="print". This selects the <filename>html</filename> style from within
|
|
ldp.dsl. The DocBook DSSSL contains support for converting DocBook
|
|
files into <filename>html</filename> and print formats. In Section 3.3, we copied <filename>ldp.dsl</filename>
|
|
into both the print and <filename>html</filename> directories. When generating <filename>html</filename> output,
|
|
the <filename>html</filename> style should be selected like above. When generating other types of
|
|
files, such as <filename>rtf</filename> and <filename>tex</filename>, they fall under the print style and so
|
|
the print style should be selected from <filename>ldp.dsl</filename>. The alternative is
|
|
to comment out or delete the print or <filename>html</filename> style in the copy of
|
|
<filename>ldp.dsl</filename> in the respective directory. If a <filename>dsl</filename> 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 <filename>ldp.dsl</filename>, the print style-spec
|
|
is first in the file, so it gets selected by default. So in the example above,
|
|
without appending "<filename>#html</filename>" when specifying <filename>ldp.dsl</filename> as the dsssl stylesheet,
|
|
the "print" style-spec would be selected and used when generating the <filename>html</filename>
|
|
output. It will work, but is intended for when selecting the <filename>print/ldp.dsl</filename>
|
|
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 the
|
|
the <ulink url="http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/index.htm">DSSSL</ulink>
|
|
language.
|
|
</para>
|
|
|
|
<para>
|
|
The <command>openjade</command> 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 <filename>pdf</filename> and <filename>ps</filename>
|
|
formats. The dsssl_spec must specify a <filename>dsl</filename> 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 <command>jadetex</command> is run, warnings are printed. They can
|
|
be ignored. Running it a second time, they do not appear again.
|
|
</para>
|
|
<para>
|
|
<figure>
|
|
<title>Running <command>dvips</command> to generate a <ProductName>PostScript</ProductName> (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 <command>htmldoc</command> to generate a <ProductName>PostScript</ProductName> (<filename>ps</filename>) file.</title>
|
|
<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$
|
|
</Screen>
|
|
</figure>
|
|
If the <filename>ps</filename> file doesn't appear as expected, it may be due
|
|
to bugs in <command>htmldoc</command>. Look inside the <command>ldp_print</command>
|
|
script if you want to use it to make <filename>ps</filename>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Generating pdf</title>
|
|
<para>
|
|
<figure>
|
|
<title>Running <command>pdfjadetex</command> to generate a Portable Document Format (<filename>pdf</filename>) 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$
|
|
bash$ pdfjadetex test.tex
|
|
[snip]
|
|
bash$ pdfjadetex test.tex
|
|
[snip]
|
|
</screen>
|
|
</figure>
|
|
<command>pdfjadetex</command> must be run up to three times to resolve all
|
|
internal references for things such as TOC page numbers.
|
|
</para>
|
|
|
|
<para>
|
|
<figure>
|
|
<title>Running <command>htmldoc</command> to generate a Portable Document Format (<filename>pdf</filename>) file.</title>
|
|
<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$
|
|
</Screen>
|
|
</figure>
|
|
If enabled in the <command>ldp_print</command> script, this would generate a <filename>ps</filename> file
|
|
also.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Using <command>make</command></title>
|
|
|
|
<para>
|
|
Repeating the commands to generate the output files is tedious.
|
|
The <command>make</command> command works perfectly to automate the process.
|
|
</para>
|
|
|
|
<para>
|
|
<Figure>
|
|
<title>Filename: <filename>Makefile</filename> - automates document generation.</title>
|
|
|
|
<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) -
|
|
</ProgramListing>
|
|
|
|
</Figure>
|
|
</para>
|
|
<para>
|
|
Usage is just like for most projects:
|
|
<figure>
|
|
<title>Invoking <command>make</command> to run <filename>Makefile</filename></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 <filename>pdf</filename> and <filename>ps</filename> which
|
|
provide alternative means of generating those files.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Generating a <command>man</command> page</title>
|
|
<para>
|
|
During the section on installing everything, we installed
|
|
the <command>perl</command> version 5 module <filename>SGMLS.pm</filename>.
|
|
Then we installed Docbook2X which provides the <filename>spec.pl</filename> files for transforming
|
|
DocBook <SGMLTag class="StartTag">refentry</SGMLTag> documents into
|
|
<command>nroff</command> (<command>man</command> page) format
|
|
with <command>sgmlspl</command>.
|
|
</para>
|
|
<para>
|
|
An example Docbook <SGMLTag class="StartTag">refentry</SGMLTag> document, for the
|
|
<command>foo</command> command, is given below.
|
|
</para>
|
|
<para>
|
|
<figure>
|
|
<title><command>foo</command> command <command>man</command> page, docbook <SGMLTag class="StartTag">refentry</SGMLTag> source (<filename>foo-ref.sgml</filename>)</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 <command>man</command> page with <command>onsgmls</command>, <command>sgmlspl</command>, and <filename>docbook2man-spec.pl</filename></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
|
|
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
|
|
</screen>
|
|
</figure>
|
|
</para>
|
|
|
|
<para>
|
|
The <command>man</command> page, <filename>foo.1</filename>, is generated as a Section 1 page. The
|
|
<command>groff</command> command is used to give a quick look at its formatted
|
|
appearance.
|
|
</para>
|
|
<para>
|
|
To <command>install</command> this <command>man</command> page, it belongs in any <filename>man/man1</filename> directory,
|
|
where the directory <filename>man/</filename> is added to <envar>$MANPATH</envar>
|
|
in the environment. The standard location is
|
|
<filename>/usr/local/man/man1</filename>.
|
|
The standard sections in the <command>man</command> pages system are 1 though 9.
|
|
Each is for holding specific catagories of documentation.
|
|
</para>
|
|
|
|
<table>
|
|
<title>Manual Pages 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 <command>man</command> page, 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
|
|
<filename>html</filename> and print output types, a <command>man</command> page can
|
|
be made into <filename>html</filename> and <filename>rtf</filename>, <filename>tex</filename>,
|
|
<filename>pdf</filename>, <filename>dvi</filename>, and <filename>ps</filename>.
|
|
This can really save a lot of conversion work!
|
|
</para>
|
|
</tip>
|
|
|
|
<para>
|
|
Have fun <emphasis>!</emphasis>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<appendix id="legal">
|
|
<title>Legal</title>
|
|
<sect1 id="copyright">
|
|
<title>Copyright and Licenses</title>
|
|
|
|
<blockquote>
|
|
<para>
|
|
Copyright (c) 2001, 2002 Robert B. Easter
|
|
</para>
|
|
<para>
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.1
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with
|
|
no Back-Cover Texts. A copy of the license is included in the
|
|
section entitled "GNU Free Documentation License".
|
|
</para>
|
|
</blockquote>
|
|
</sect1>
|
|
|
|
<sect1 id="disclaimer">
|
|
<title>Disclaimer</title>
|
|
|
|
<para>
|
|
No liability for the contents of this document can be accepted.
|
|
Use the concepts, examples and other content at your own risk.
|
|
</para>
|
|
|
|
<para>
|
|
All copyrights are held 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>
|
|
</sect1>
|
|
</appendix>
|
|
|
|
|
|
<appendix id="gfdl">
|
|
<title>GNU Free Documentation License</title>
|
|
<!-- - GNU Project - Free Software Foundation (FSF) -->
|
|
<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" -->
|
|
|
|
|
|
<!-- sect1>
|
|
<title>GNU Free Documentation License</title -->
|
|
|
|
<para>Version 1.1, March 2000</para>
|
|
|
|
<blockquote>
|
|
<para>Copyright (C) 2000 Free Software Foundation, Inc.
|
|
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.</para>
|
|
</blockquote>
|
|
|
|
<sect1 label="0">
|
|
<title>PREAMBLE</title>
|
|
|
|
<para>The purpose of this License is to make a manual, textbook,
|
|
or other written document "free" in the sense of freedom: to
|
|
assure everyone the effective freedom to copy and redistribute it,
|
|
with or without modifying it, either commercially or
|
|
noncommercially. Secondarily, this License preserves for the
|
|
author and publisher a way to get credit for their work, while not
|
|
being considered responsible for modifications made by
|
|
others.</para>
|
|
|
|
<para>This License is a kind of "copyleft", which means that
|
|
derivative works of the document must themselves be free in the
|
|
same sense. It complements the GNU General Public License, which
|
|
is a copyleft license designed for free software.</para>
|
|
|
|
<para>We have designed this License in order to use it for manuals
|
|
for free software, because free software needs free documentation:
|
|
a free program should come with manuals providing the same
|
|
freedoms that the software does. But this License is not limited
|
|
to software manuals; it can be used for any textual work,
|
|
regardless of subject matter or whether it is published as a
|
|
printed book. We recommend this License principally for works
|
|
whose purpose is instruction or reference.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="1">
|
|
<title>APPLICABILITY AND DEFINITIONS</title>
|
|
|
|
<para>This License applies to any manual or other work that
|
|
contains a notice placed by the copyright holder saying it can be
|
|
distributed under the terms of this License. The "Document",
|
|
below, refers to any such manual or work. Any member of the
|
|
public is a licensee, and is addressed as "you".</para>
|
|
|
|
<para>A "Modified Version" of the Document means any work
|
|
containing the Document or a portion of it, either copied
|
|
verbatim, or with modifications and/or translated into another
|
|
language.</para>
|
|
|
|
<para>A "Secondary Section" is a named appendix or a front-matter
|
|
section of the Document that deals exclusively with the
|
|
relationship of the publishers or authors of the Document to the
|
|
Document's overall subject (or to related matters) and contains
|
|
nothing that could fall directly within that overall subject.
|
|
(For example, if the Document is in part a textbook of
|
|
mathematics, a Secondary Section may not explain any mathematics.)
|
|
The relationship could be a matter of historical connection with
|
|
the subject or with related matters, or of legal, commercial,
|
|
philosophical, ethical or political position regarding
|
|
them.</para>
|
|
|
|
<para>The "Invariant Sections" are certain Secondary Sections
|
|
whose titles are designated, as being those of Invariant Sections,
|
|
in the notice that says that the Document is released under this
|
|
License.</para>
|
|
|
|
<para>The "Cover Texts" are certain short passages of text that
|
|
are listed, as Front-Cover Texts or Back-Cover Texts, in the
|
|
notice that says that the Document is released under this
|
|
License.</para>
|
|
|
|
<para>A "Transparent" copy of the Document means a
|
|
machine-readable copy, represented in a format whose specification
|
|
is available to the general public, whose contents can be viewed
|
|
and edited directly and straightforwardly with generic text
|
|
editors or (for images composed of pixels) generic paint programs
|
|
or (for drawings) some widely available drawing editor, and that
|
|
is suitable for input to text formatters or for automatic
|
|
translation to a variety of formats suitable for input to text
|
|
formatters. A copy made in an otherwise Transparent file format
|
|
whose markup has been designed to thwart or discourage subsequent
|
|
modification by readers is not Transparent. A copy that is not
|
|
"Transparent" is called "Opaque".</para>
|
|
|
|
<para>Examples of suitable formats for Transparent copies include
|
|
plain ASCII without markup, Texinfo input format, LaTeX input
|
|
format, SGML or XML using a publicly available DTD, and
|
|
standard-conforming simple HTML designed for human modification.
|
|
Opaque formats include PostScript, PDF, proprietary formats that
|
|
can be read and edited only by proprietary word processors, SGML
|
|
or XML for which the DTD and/or processing tools are not generally
|
|
available, and the machine-generated HTML produced by some word
|
|
processors for output purposes only.</para>
|
|
|
|
<para>The "Title Page" means, for a printed book, the title page
|
|
itself, plus such following pages as are needed to hold, legibly,
|
|
the material this License requires to appear in the title page.
|
|
For works in formats which do not have any title page as such,
|
|
"Title Page" means the text near the most prominent appearance of
|
|
the work's title, preceding the beginning of the body of the
|
|
text.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="2">
|
|
<title>VERBATIM COPYING</title>
|
|
|
|
<para>You may copy and distribute the Document in any medium,
|
|
either commercially or noncommercially, provided that this
|
|
License, the copyright notices, and the license notice saying this
|
|
License applies to the Document are reproduced in all copies, and
|
|
that you add no other conditions whatsoever to those of this
|
|
License. You may not use technical measures to obstruct or
|
|
control the reading or further copying of the copies you make or
|
|
distribute. However, you may accept compensation in exchange for
|
|
copies. If you distribute a large enough number of copies you
|
|
must also follow the conditions in section 3.</para>
|
|
|
|
<para>You may also lend copies, under the same conditions stated
|
|
above, and you may publicly display copies.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="3">
|
|
<title>COPYING IN QUANTITY</title>
|
|
|
|
<para>If you publish printed copies of the Document numbering more
|
|
than 100, and the Document's license notice requires Cover Texts,
|
|
you must enclose the copies in covers that carry, clearly and
|
|
legibly, all these Cover Texts: Front-Cover Texts on the front
|
|
cover, and Back-Cover Texts on the back cover. Both covers must
|
|
also clearly and legibly identify you as the publisher of these
|
|
copies. The front cover must present the full title with all
|
|
words of the title equally prominent and visible. You may add
|
|
other material on the covers in addition. Copying with changes
|
|
limited to the covers, as long as they preserve the title of the
|
|
Document and satisfy these conditions, can be treated as verbatim
|
|
copying in other respects.</para>
|
|
|
|
<para>If the required texts for either cover are too voluminous to
|
|
fit legibly, you should put the first ones listed (as many as fit
|
|
reasonably) on the actual cover, and continue the rest onto
|
|
adjacent pages.</para>
|
|
|
|
<para>If you publish or distribute Opaque copies of the Document
|
|
numbering more than 100, you must either include a
|
|
machine-readable Transparent copy along with each Opaque copy, or
|
|
state in or with each Opaque copy a publicly-accessible
|
|
computer-network location containing a complete Transparent copy
|
|
of the Document, free of added material, which the general
|
|
network-using public has access to download anonymously at no
|
|
charge using public-standard network protocols. If you use the
|
|
latter option, you must take reasonably prudent steps, when you
|
|
begin distribution of Opaque copies in quantity, to ensure that
|
|
this Transparent copy will remain thus accessible at the stated
|
|
location until at least one year after the last time you
|
|
distribute an Opaque copy (directly or through your agents or
|
|
retailers) of that edition to the public.</para>
|
|
|
|
<para>It is requested, but not required, that you contact the
|
|
authors of the Document well before redistributing any large
|
|
number of copies, to give them a chance to provide you with an
|
|
updated version of the Document.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="4">
|
|
<title>MODIFICATIONS</title>
|
|
|
|
<para>You may copy and distribute a Modified Version of the
|
|
Document under the conditions of sections 2 and 3 above, provided
|
|
that you release the Modified Version under precisely this
|
|
License, with the Modified Version filling the role of the
|
|
Document, thus licensing distribution and modification of the
|
|
Modified Version to whoever possesses a copy of it. In addition,
|
|
you must do these things in the Modified Version:</para>
|
|
|
|
<orderedlist numeration="upperalpha">
|
|
<listitem><para>Use in the Title Page
|
|
(and on the covers, if any) a title distinct from that of the
|
|
Document, and from those of previous versions (which should, if
|
|
there were any, be listed in the History section of the
|
|
Document). You may use the same title as a previous version if
|
|
the original publisher of that version gives permission.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>List on the Title Page,
|
|
as authors, one or more persons or entities responsible for
|
|
authorship of the modifications in the Modified Version,
|
|
together with at least five of the principal authors of the
|
|
Document (all of its principal authors, if it has less than
|
|
five).</para>
|
|
</listitem>
|
|
|
|
<listitem><para>State on the Title page
|
|
the name of the publisher of the Modified Version, as the
|
|
publisher.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Preserve all the
|
|
copyright notices of the Document.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Add an appropriate
|
|
copyright notice for your modifications adjacent to the other
|
|
copyright notices.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Include, immediately
|
|
after the copyright notices, a license notice giving the public
|
|
permission to use the Modified Version under the terms of this
|
|
License, in the form shown in the Addendum below.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Preserve in that license
|
|
notice the full lists of Invariant Sections and required Cover
|
|
Texts given in the Document's license notice.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Include an unaltered
|
|
copy of this License.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Preserve the section
|
|
entitled "History", and its title, and add to it an item stating
|
|
at least the title, year, new authors, and publisher of the
|
|
Modified Version as given on the Title Page. If there is no
|
|
section entitled "History" in the Document, create one stating
|
|
the title, year, authors, and publisher of the Document as given
|
|
on its Title Page, then add an item describing the Modified
|
|
Version as stated in the previous sentence.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Preserve the network
|
|
location, if any, given in the Document for public access to a
|
|
Transparent copy of the Document, and likewise the network
|
|
locations given in the Document for previous versions it was
|
|
based on. These may be placed in the "History" section. You
|
|
may omit a network location for a work that was published at
|
|
least four years before the Document itself, or if the original
|
|
publisher of the version it refers to gives permission.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>In any section entitled
|
|
"Acknowledgements" or "Dedications", preserve the section's
|
|
title, and preserve in the section all the substance and tone of
|
|
each of the contributor acknowledgements and/or dedications
|
|
given therein.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Preserve all the
|
|
Invariant Sections of the Document, unaltered in their text and
|
|
in their titles. Section numbers or the equivalent are not
|
|
considered part of the section titles.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Delete any section
|
|
entitled "Endorsements". Such a section may not be included in
|
|
the Modified Version.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Do not retitle any
|
|
existing section as "Endorsements" or to conflict in title with
|
|
any Invariant Section.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>If the Modified Version includes new front-matter sections
|
|
or appendices that qualify as Secondary Sections and contain no
|
|
material copied from the Document, you may at your option
|
|
designate some or all of these sections as invariant. To do this,
|
|
add their titles to the list of Invariant Sections in the Modified
|
|
Version's license notice. These titles must be distinct from any
|
|
other section titles.</para>
|
|
|
|
<para>You may add a section entitled "Endorsements", provided it
|
|
contains nothing but endorsements of your Modified Version by
|
|
various parties--for example, statements of peer review or that
|
|
the text has been approved by an organization as the authoritative
|
|
definition of a standard.</para>
|
|
|
|
<para>You may add a passage of up to five words as a Front-Cover
|
|
Text, and a passage of up to 25 words as a Back-Cover Text, to the
|
|
end of the list of Cover Texts in the Modified Version. Only one
|
|
passage of Front-Cover Text and one of Back-Cover Text may be
|
|
added by (or through arrangements made by) any one entity. If the
|
|
Document already includes a cover text for the same cover,
|
|
previously added by you or by arrangement made by the same entity
|
|
you are acting on behalf of, you may not add another; but you may
|
|
replace the old one, on explicit permission from the previous
|
|
publisher that added the old one.</para>
|
|
|
|
<para>The author(s) and publisher(s) of the Document do not by
|
|
this License give permission to use their names for publicity for
|
|
or to assert or imply endorsement of any Modified Version.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="5">
|
|
<title>COMBINING DOCUMENTS</title>
|
|
|
|
<para>You may combine the Document with other documents released
|
|
under this License, under the terms defined in section 4 above for
|
|
modified versions, provided that you include in the combination
|
|
all of the Invariant Sections of all of the original documents,
|
|
unmodified, and list them all as Invariant Sections of your
|
|
combined work in its license notice.</para>
|
|
|
|
<para>The combined work need only contain one copy of this
|
|
License, and multiple identical Invariant Sections may be replaced
|
|
with a single copy. If there are multiple Invariant Sections with
|
|
the same name but different contents, make the title of each such
|
|
section unique by adding at the end of it, in parentheses, the
|
|
name of the original author or publisher of that section if known,
|
|
or else a unique number. Make the same adjustment to the section
|
|
titles in the list of Invariant Sections in the license notice of
|
|
the combined work.</para>
|
|
|
|
<para>In the combination, you must combine any sections entitled
|
|
"History" in the various original documents, forming one section
|
|
entitled "History"; likewise combine any sections entitled
|
|
"Acknowledgements", and any sections entitled "Dedications". You
|
|
must delete all sections entitled "Endorsements."</para>
|
|
</sect1>
|
|
|
|
<sect1 label="6">
|
|
<title>COLLECTIONS OF DOCUMENTS</title>
|
|
|
|
<para>You may make a collection consisting of the Document and
|
|
other documents released under this License, and replace the
|
|
individual copies of this License in the various documents with a
|
|
single copy that is included in the collection, provided that you
|
|
follow the rules of this License for verbatim copying of each of
|
|
the documents in all other respects.</para>
|
|
|
|
<para>You may extract a single document from such a collection,
|
|
and distribute it individually under this License, provided you
|
|
insert a copy of this License into the extracted document, and
|
|
follow this License in all other respects regarding verbatim
|
|
copying of that document.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="7">
|
|
<title>AGGREGATION WITH INDEPENDENT WORKS</title>
|
|
|
|
<para>A compilation of the Document or its derivatives with other
|
|
separate and independent documents or works, in or on a volume of
|
|
a storage or distribution medium, does not as a whole count as a
|
|
Modified Version of the Document, provided no compilation
|
|
copyright is claimed for the compilation. Such a compilation is
|
|
called an "aggregate", and this License does not apply to the
|
|
other self-contained works thus compiled with the Document, on
|
|
account of their being thus compiled, if they are not themselves
|
|
derivative works of the Document.</para>
|
|
|
|
<para>If the Cover Text requirement of section 3 is applicable to
|
|
these copies of the Document, then if the Document is less than
|
|
one quarter of the entire aggregate, the Document's Cover Texts
|
|
may be placed on covers that surround only the Document within the
|
|
aggregate. Otherwise they must appear on covers around the whole
|
|
aggregate.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="8">
|
|
<title>TRANSLATION</title>
|
|
|
|
<para>Translation is considered a kind of modification, so you may
|
|
distribute translations of the Document under the terms of section
|
|
4. Replacing Invariant Sections with translations requires
|
|
special permission from their copyright holders, but you may
|
|
include translations of some or all Invariant Sections in addition
|
|
to the original versions of these Invariant Sections. You may
|
|
include a translation of this License provided that you also
|
|
include the original English version of this License. In case of
|
|
a disagreement between the translation and the original English
|
|
version of this License, the original English version will
|
|
prevail.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="9">
|
|
<title>TERMINATION</title>
|
|
|
|
<para>You may not copy, modify, sublicense, or distribute the
|
|
Document except as expressly provided for under this License. Any
|
|
other attempt to copy, modify, sublicense or distribute the
|
|
Document is void, and will automatically terminate your rights
|
|
under this License. However, parties who have received copies, or
|
|
rights, from you under this License will not have their licenses
|
|
terminated so long as such parties remain in full
|
|
compliance.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="10">
|
|
<title>FUTURE REVISIONS OF THIS LICENSE</title>
|
|
|
|
<para>The Free Software Foundation may publish new, revised
|
|
versions of the GNU Free Documentation License from time to time.
|
|
Such new versions will be similar in spirit to the present
|
|
version, but may differ in detail to address new problems or
|
|
concerns. See <ulink
|
|
url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para>
|
|
|
|
<para>Each version of the License is given a distinguishing
|
|
version number. If the Document specifies that a particular
|
|
numbered version of this License "or any later version" applies to
|
|
it, you have the option of following the terms and conditions
|
|
either of that specified version or of any later version that has
|
|
been published (not as a draft) by the Free Software Foundation.
|
|
If the Document does not specify a version number of this License,
|
|
you may choose any version ever published (not as a draft) by the
|
|
Free Software Foundation.</para>
|
|
</sect1>
|
|
|
|
<sect1 label="">
|
|
<title>How to use this License for your documents</title>
|
|
|
|
<para>To use this License in a document you have written, include
|
|
a copy of the License in the document and put the following
|
|
copyright and license notices just after the title page:</para>
|
|
|
|
<blockquote><para>
|
|
Copyright (c) YEAR YOUR NAME.
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.1
|
|
or any later version published by the Free Software Foundation;
|
|
with the Invariant Sections being LIST THEIR TITLES, with the
|
|
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
|
A copy of the license is included in the section entitled "GNU
|
|
Free Documentation License".
|
|
</para></blockquote>
|
|
|
|
<para>If you have no Invariant Sections, write "with no Invariant
|
|
Sections" instead of saying which ones are invariant. If you have
|
|
no Front-Cover Texts, write "no Front-Cover Texts" instead of
|
|
"Front-Cover Texts being LIST"; likewise for Back-Cover
|
|
Texts.</para>
|
|
|
|
<para>If your document contains nontrivial examples of program
|
|
code, we recommend releasing these examples in parallel under your
|
|
choice of free software license, such as the GNU General Public
|
|
License, to permit their use in free software.</para>
|
|
</sect1>
|
|
|
|
</appendix>
|
|
|
|
</article>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:nil
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:2
|
|
sgml-parent-document: ("referenz.sgml" "appendix")
|
|
sgml-exposed-tags:nil
|
|
sgml-local-ecat-files:nil
|
|
sgml-local-catalogs: CATALOG
|
|
sgml-validate-command: "nsgmls -s referenz.sgml"
|
|
ispell-skip-sgml: t
|
|
End:
|
|
-->
|