2001-01-02 16:07:56 +00:00
<!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>
2001-03-28 22:47:19 +00:00
<revnumber>v1.7</revnumber>
<date>2001-03-28</date>
2001-01-02 16:07:56 +00:00
<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>
2001-03-28 22:47:19 +00:00
2001-01-02 16:07:56 +00:00
<sect1 id="intro">
<title>Introduction</title>
2001-03-28 22:47:19 +00:00
<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>
2001-01-02 16:07:56 +00:00
<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
2001-01-03 15:19:49 +00:00
or gml suffix.
</para>
<para>
When processed, a single DocBook SGML file can
2001-01-02 16:07:56 +00:00
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>
2001-01-03 15:19:49 +00:00
<para>
DocBook is also designed for authoring unix manpages using
<refentry>.
</para>
2001-01-02 16:07:56 +00:00
</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
2001-03-28 14:02:22 +00:00
that define the DocBook language. It defines the
2001-01-02 16:07:56 +00:00
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>
2001-01-03 15:19:49 +00:00
<title>HTMLdoc</title>
2001-01-02 16:07:56 +00:00
<para>
2001-01-03 15:19:49 +00:00
HTMLdoc is a free program for converting html files into a
2001-01-02 16:07:56 +00:00
pdf or ps file.
</para>
</FormalPara>
2001-01-03 15:19:49 +00:00
<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>
2001-01-02 16:07:56 +00:00
</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
2001-03-28 14:02:22 +00:00
for converting files to dvi and pdf. The following programs are provided by this
2001-01-02 16:07:56 +00:00
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>
2001-03-28 14:02:22 +00:00
To use jadetex and pdfjadetex for making dvi, ps, and pdf, you must have
2001-01-02 16:07:56 +00:00
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
2001-01-03 15:19:49 +00:00
<ulink url="http://nwalsh.com/docbook/dsssl/">Modular DocBook Stylesheets</ulink>, tell <filename>openjade</filename> what
2001-01-02 16:07:56 +00:00
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>
2001-01-03 15:19:49 +00:00
Sgmltools is a frontend for openjade, <filename>jadetex</filename>, <filename>pdfjadex</filename>,
<filename>dvips</filename>, and other programs. It
2001-01-02 16:07:56 +00:00
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
2001-01-03 15:19:49 +00:00
both and see which turns out best for a particular docbook file. See quick links
below for download site.
2001-01-02 16:07:56 +00:00
</para>
</sect2>
2001-01-03 15:19:49 +00:00
<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>
2001-01-02 16:07:56 +00:00
<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:
2001-01-03 15:19:49 +00:00
<ulink url="http://www.easysw.com/software.html">http://www.easysw.com/software.html</ulink>
2001-01-02 16:07:56 +00:00
</para>
</FormalPara>
2001-01-03 15:19:49 +00:00
<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>
2001-01-02 16:07:56 +00:00
<para>
2001-01-03 15:19:49 +00:00
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)
2001-01-02 16:07:56 +00:00
</para>
2001-01-03 15:19:49 +00:00
</FormalPara>
2001-01-02 16:07:56 +00:00
</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
2001-01-27 18:24:01 +00:00
# Once installed, the objects etc. can be deleted.
2001-01-02 16:07:56 +00:00
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>
2001-01-27 18:24:01 +00:00
bash$ which tex
2001-01-02 16:07:56 +00:00
/usr/share/texmf/bin/tex
2001-01-27 18:24:01 +00:00
bash$ kpsewhich -expand-var='$TEXMFMAIN'
2001-01-02 16:07:56 +00:00
/usr/share/texmf
2001-01-27 18:24:01 +00:00
bash$
2001-01-02 16:07:56 +00:00
</screen>
</para>
<para>
2001-03-28 14:02:22 +00:00
Using <filename>which</filename> should find the location of the tex program. If its not
2001-01-02 16:07:56 +00:00
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
2001-01-27 18:24:01 +00:00
tex -ini -progname=hugelatex latex.ini
mv latex.fmt hugelatex.fmt
2001-01-02 16:07:56 +00:00
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>
2001-01-27 18:24:01 +00:00
root# texhash
2001-01-02 16:07:56 +00:00
texhash: Updating /usr/share/texmf/ls-R...
texhash: Updating /var/cache/fonts/ls-R...
texhash: Done.
2001-01-27 18:24:01 +00:00
root#
2001-01-02 16:07:56 +00:00
</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
2001-01-27 18:24:01 +00:00
# make creates and installs the .fmt
# files to /usr/share/texmf/web2c
# Now create symlinks ...
2001-01-02 16:07:56 +00:00
cd /usr/share/texmf/bin
ln -s tex jadetex
2001-03-28 14:02:22 +00:00
ln -s pdftex pdfjadetex
2001-01-27 18:24:01 +00:00
# Finally, run texhash.
root# texhash
2001-01-02 16:07:56 +00:00
</screen>
This Makefile uses hugelatex, so hugelatex must have been
setup already. When tex is run as hugelatex, jadetex, or
2001-01-18 14:37:02 +00:00
pdfjadetex, it gets its program name (context) from argv[0]
2001-01-02 16:07:56 +00:00
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>
2001-01-27 18:24:01 +00:00
# DocBook DTD V4.1 in
# /usr/local/share/sgml/docbook/4.1
2001-01-02 16:07:56 +00:00
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>
2001-01-27 18:24:01 +00:00
# If needed ...
2001-01-02 16:07:56 +00:00
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
2001-01-27 18:24:01 +00:00
# If you downloaded the ldp.dsl stylesheet
# customization, copy it to ...
2001-01-02 16:07:56 +00:00
cd docbook
cp ~/ldp.dsl html
cp ~/ldp.dsl print
2001-01-27 18:24:01 +00:00
# Copy into both directories.
2001-01-02 16:07:56 +00:00
</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.
2001-01-18 14:37:02 +00:00
Its installation is the standard:
2001-01-02 16:07:56 +00:00
<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
2001-03-28 14:02:22 +00:00
you have to edit it and set the path to openjade:
2001-01-18 14:37:02 +00:00
vi `which sgmltools`. Consult its docs to learn more about it.
2001-01-02 16:07:56 +00:00
</para>
</sect2>
<sect2>
<title>htmldoc</title>
2001-01-18 14:37:02 +00:00
<sect3>
<title>binary</title>
2001-01-02 16:07:56 +00:00
<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>
2001-01-18 14:37:02 +00:00
</sect3>
2001-01-02 16:07:56 +00:00
2001-01-18 14:37:02 +00:00
<sect3>
<title>source</title>
2001-01-02 16:07:56 +00:00
<para>
2001-01-18 14:37:02 +00:00
If you downloaded the source, you will also need the Fast Light Tool Kit
or else it will not link:
2001-01-02 16:07:56 +00:00
</para>
<para>
2001-01-18 14:37:02 +00:00
<ulink url="http://www.fltk.org/">http://www.fltk.org/</ulink>
2001-01-02 16:07:56 +00:00
</para>
<para>
2001-01-18 14:37:02 +00:00
Installation is autoconf style.
Just run the configure script, make, make install. If all goes
well, it will install in /usr/bin.
2001-01-02 16:07:56 +00:00
</para>
2001-01-18 14:37:02 +00:00
</sect3>
2001-01-02 16:07:56 +00:00
2001-01-18 14:37:02 +00:00
<sect3>
2001-01-27 18:24:01 +00:00
<title>ldp_print</title>
2001-01-02 16:07:56 +00:00
<para>
2001-01-18 14:37:02 +00:00
The htmldoc program has a few glitches when generating output from
html files from openjade. For instance, bullet items are not
rendered properly and shaded areas are not always shaded.
2001-01-02 16:07:56 +00:00
</para>
<para>
2001-01-18 14:37:02 +00:00
To fix this problem, a perl script
2001-01-27 18:24:01 +00:00
(<ulink url="http://www.linuxdoc.org/authors/tools/ldp_print.tar.gz">ldp_print</ulink>)
2001-01-18 14:37:02 +00:00
is available from <ulink url="http://www.linuxdoc.org/">LinuxDoc.org</ulink>.
The script processes a nochunks html file from openjade and then runs htmldoc on it
to produce correctly rendered pdf and ps.
<tip><para>Get it!</para></tip>
2001-01-02 16:07:56 +00:00
</para>
2001-01-18 14:37:02 +00:00
<para>
<screen>
tar -xvzf ldp_print.tar.gz
cd ldp_print
2001-03-28 14:02:22 +00:00
# Copy the lib somewhere where perl looks.
2001-01-18 14:37:02 +00:00
cp fix_print_html.lib /usr/lib/perl5/site_perl
2001-01-27 18:24:01 +00:00
2001-01-18 14:37:02 +00:00
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 htmldoc's bugs will
be fixed and this script will not be needed anymore.
</para>
</sect3>
2001-01-02 16:07:56 +00:00
</sect2>
2001-01-03 15:19:49 +00:00
<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
2001-01-27 18:24:01 +00:00
# Edit Makfile
2001-01-03 15:19:49 +00:00
vi Makefile
2001-01-27 18:24:01 +00:00
# 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
2001-01-03 15:19:49 +00:00
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>
2001-01-02 16:07:56 +00:00
<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
2001-01-18 14:37:02 +00:00
and see how to use openjade and the other tools.
2001-01-02 16:07:56 +00:00
</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>
2001-01-03 15:19:49 +00:00
2001-01-02 16:07:56 +00:00
<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
[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 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
2001-01-27 18:24:01 +00:00
very descriptive. Section one appears on the same page as the article information.
2001-01-02 16:07:56 +00:00
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
2001-03-28 14:02:22 +00:00
<filename>ldp.dsl</filename> file and installed it as shown in Section 3.3,
then you already have a customized style available.
2001-01-02 16:07:56 +00:00
</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>
2001-01-27 18:24:01 +00:00
Note how the ldp.dsl file is written in the command line: it has "#html" appended. Ldp.dsl
2001-01-02 16:07:56 +00:00
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
2001-01-18 14:37:02 +00:00
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 -
2001-01-02 16:07:56 +00:00
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>
2001-01-18 14:37:02 +00:00
If the ps doesn't appear as expected, it is due to bugs in htmldoc.
Look inside the ldp_print script if you want to use it to make ps.
2001-01-02 16:07:56 +00:00
</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$
2001-01-18 14:37:02 +00:00
bash$ pdfjadetex test.tex
[snip]
bash$ pdfjadetex test.tex
[snip]
2001-01-02 16:07:56 +00:00
</screen>
</figure>
2001-01-18 14:37:02 +00:00
Pdfjadetex must be run up to three times to resolve all
internal references for things such as TOC page numbers.
2001-01-02 16:07:56 +00:00
</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
2001-01-18 14:37:02 +00:00
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
2001-01-02 16:07:56 +00:00
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>
2001-01-18 14:37:02 +00:00
If enabled in the ldp_print script, this would generate a ps file
also.
2001-01-02 16:07:56 +00:00
</para>
</sect2>
<sect2>
<title>Using make</title>
<para>
Repeating the commands to generate the output files is tedious.
2001-01-27 18:24:01 +00:00
The make command works perfectly to automate the process.
2001-01-02 16:07:56 +00:00
</para>
<para>
<Figure>
<title>Filename: Makefile - automates document generation.</title>
<ProgramListing>
# Generates online and print versions of SGML source file.
2001-01-18 14:37:02 +00:00
BASENAME=DocBook-Install
2001-01-02 16:07:56 +00:00
# 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
2001-01-18 14:37:02 +00:00
HTM_FILE=$(BASENAME).htm
2001-01-02 16:07:56 +00:00
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)
2001-01-18 14:37:02 +00:00
htm: $(HTM_FILE)
2001-01-02 16:07:56 +00:00
tex: $(TEX_FILE)
rtf: $(RTF_FILE)
pdf: $(PDF_FILE)
dvi: $(DVI_FILE)
ps: $(PS_FILE)
2001-01-18 14:37:02 +00:00
all: html htm tex rtf pdf dvi ps
2001-01-02 16:07:56 +00:00
clean:
2001-01-18 14:37:02 +00:00
rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot}
2001-01-02 16:07:56 +00:00
rm -f *.html
distclean: clean
rm -f $(BASENAME).tgz
package:
rm -f $(BASENAME).tgz
2001-01-03 15:19:49 +00:00
tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
mv /tmp/$(BASENAME).tgz .
2001-01-02 16:07:56 +00:00
dist: clean package
distall: all package
2001-01-18 14:37:02 +00:00
2001-01-02 16:07:56 +00:00
# Compile rules.
$(HTML_FILE): $(SGML_FILE)
openjade -t sgml -d $(DSL_HTML) $(SGML_FILE)
2001-01-18 14:37:02 +00:00
$(HTM_FILE): $(SGML_FILE)
openjade -t sgml -V nochunks -d $(DSL_HTML) \
$(SGML_FILE) > $(HTM_FILE)
2001-01-02 16:07:56 +00:00
$(TEX_FILE): $(SGML_FILE)
openjade -t tex -d $(DSL_PRINT) $(SGML_FILE)
$(RTF_FILE): $(SGML_FILE)
openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE)
2001-01-18 14:37:02 +00:00
# [pdf]jadetex is run 3 times to resolve references.
2001-01-02 16:07:56 +00:00
#$(PDF_FILE): $(TEX_FILE)
# pdfjadetex $(TEX_FILE)
2001-01-18 14:37:02 +00:00
# pdfjadetex $(TEX_FILE)
# pdfjadetex $(TEX_FILE)
2001-01-02 16:07:56 +00:00
2001-01-18 14:37:02 +00:00
# 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)
2001-01-02 16:07:56 +00:00
$(DVI_FILE): $(TEX_FILE)
jadetex $(TEX_FILE)
2001-01-18 14:37:02 +00:00
jadetex $(TEX_FILE)
jadetex $(TEX_FILE)
2001-01-02 16:07:56 +00:00
$(PS_FILE): $(DVI_FILE)
dvips $(DVI_FILE)
#$(PS_FILE): $(SGML_FILE)
2001-01-18 14:37:02 +00:00
# openjade -t sgml -V nochunks -d $(DSL_HTML) \
# $(SGML_FILE) | htmldoc -f $(PS_FILE) -
2001-01-02 16:07:56 +00:00
</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>
2001-01-03 15:19:49 +00:00
</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
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
2001-01-18 14:37:02 +00:00
-f bar Takes bar as its run control file. If this were a
2001-01-03 15:19:49 +00:00
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.
2001-01-02 16:07:56 +00:00
2001-01-03 15:19:49 +00:00
file...
Processes the files in the order listed, sending
all output to stdout.
2001-01-02 16:07:56 +00:00
2001-01-03 15:19:49 +00:00
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>
2001-01-02 16:07:56 +00:00
</sect2>
</sect1>
2001-03-28 22:47:19 +00:00
<appendix id="legal">
<title>Legal</title>
<sect1 id="copyright">
<title>Copyright and Licenses</title>
<blockquote>
<para>
Copyright (c) 2001 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>
2001-01-02 16:07:56 +00:00
2001-03-28 22:47:19 +00:00
<sect1 id="disclaimer">
2001-01-02 16:07:56 +00:00
<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>
2001-03-28 22:47:19 +00:00
All copyrights are held by their respective owners, unless
2001-01-02 16:07:56 +00:00
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>
2001-03-28 22:47:19 +00:00
</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:
-->
