1886 lines
112 KiB
Plaintext
1886 lines
112 KiB
Plaintext
|
DocBook Install mini-HOWTO
|
|||
|
|
|||
|
Robert B Easter
|
|||
|
|
|||
|
reaster@reaster.com
|
|||
|
Revision History
|
|||
|
Revision v1.8 2002-02-04 Revised by: rbe
|
|||
|
|
|||
|
|
|||
|
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 [http://www.gnu.org/gnu/linux-and-gnu.html] GNU/[http://
|
|||
|
www.linux.org] Linux system - other systems may be similar. Since setup of
|
|||
|
DocBook requires files from several separately distributed packages, it can
|
|||
|
be confusing for beginners.
|
|||
|
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
Table of Contents
|
|||
|
1. Introduction
|
|||
|
1.1. Information About this Document
|
|||
|
1.2. What is DocBook
|
|||
|
1.3. Brief Overview
|
|||
|
|
|||
|
|
|||
|
2. Download the Packages
|
|||
|
2.1. OpenJade
|
|||
|
2.2. DocBook SGML DTD
|
|||
|
2.3. ISO8879 ENTITY SGML
|
|||
|
2.4. DocBook DSSSL
|
|||
|
2.5. SGMLtools-Lite
|
|||
|
2.6. HTMLdoc
|
|||
|
2.7. DocBook2X
|
|||
|
|
|||
|
|
|||
|
3. Install the Packages
|
|||
|
3.1. Before You Install
|
|||
|
3.2. Install OpenJade
|
|||
|
3.3. DocBook SGML DTD
|
|||
|
3.4. DocBook DSSSL
|
|||
|
3.5. SGMLtools-Lite
|
|||
|
3.6. htmldoc
|
|||
|
3.7. DocBook2X and SGMLS.pm (sgmlspl)
|
|||
|
3.8. $SGML_CATALOG_FILES
|
|||
|
|
|||
|
|
|||
|
4. Using DocBook
|
|||
|
4.1. Generating HTML
|
|||
|
4.2. Generating rtf and tex
|
|||
|
4.3. Generating dvi and ps
|
|||
|
4.4. Generating pdf
|
|||
|
4.5. Using make
|
|||
|
4.6. Generating a man page
|
|||
|
|
|||
|
|
|||
|
A. Legal
|
|||
|
A.1. Copyright and Licenses
|
|||
|
A.2. Disclaimer
|
|||
|
|
|||
|
|
|||
|
B. GNU Free Documentation License
|
|||
|
0. PREAMBLE
|
|||
|
1. APPLICABILITY AND DEFINITIONS
|
|||
|
2. VERBATIM COPYING
|
|||
|
3. COPYING IN QUANTITY
|
|||
|
4. MODIFICATIONS
|
|||
|
5. COMBINING DOCUMENTS
|
|||
|
6. COLLECTIONS OF DOCUMENTS
|
|||
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|||
|
8. TRANSLATION
|
|||
|
9. TERMINATION
|
|||
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|||
|
How to use this License for your documents
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
1. Introduction
|
|||
|
|
|||
|
1.1. Information About this Document
|
|||
|
|
|||
|
The lastest version of this mini-HOWTO can be found at:
|
|||
|
|
|||
|
[http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/] http://www.linuxdoc.org
|
|||
|
/HOWTO/mini/DocBook-Install/
|
|||
|
|
|||
|
See the "Legal" section in the appendix for copyright, licenses, and
|
|||
|
disclaimer information pertaining to this document.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
1.2. What is DocBook
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
DocBook is intended for the authoring of books and articles. As such, it
|
|||
|
provides tags specifically designed to describe books and articles. For
|
|||
|
instance, the <book> and <article> DocBook tags are used to create books and
|
|||
|
articles. Within these documents, the <chapter>, <sect1>, and <para> tags are
|
|||
|
used. DocBook SGML files are stored in text files with a sgml or gml suffix.
|
|||
|
|
|||
|
When processed, a single DocBook SGML file can output html, pdf, ps, txt and
|
|||
|
other formats for both online and printed publication. The processing is
|
|||
|
governed by stylesheets that can automatically generate a table of contents,
|
|||
|
page numbering, chapter & section numbering, and other features.
|
|||
|
|
|||
|
DocBook is also designed for authoring unix man pages by writing <refentry>
|
|||
|
documents. If you don't know what a man page is, try the command man man on
|
|||
|
your terminal.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
1.3. Brief Overview
|
|||
|
|
|||
|
Here are brief descriptions of the packages we will work with in the next
|
|||
|
sections:
|
|||
|
|
|||
|
OpenJade. 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 html, tex, rtf, txt
|
|||
|
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 dvi, pdf, and ps via TeX macros and dvi converters.
|
|||
|
|
|||
|
DocBook SGML DTD. 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.
|
|||
|
|
|||
|
ISO8879 ENTITY SGML. Entities define how to represent special characters that
|
|||
|
have either no keyboard key or have special meaning in SGML. Examples
|
|||
|
familiar from HTML include "&"='&', ">"='>', and "<"='<'.
|
|||
|
|
|||
|
DocBook DSSSL (Modular DocBook Stylesheets). 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 openjade along with your DocBook
|
|||
|
sgml file and tells openjade how to transform/style your document into
|
|||
|
another file format. The dsl for online (html) formats is often different
|
|||
|
than for print (dvi, pdf, ps) formats.
|
|||
|
|
|||
|
SGMLtools-Lite. SGMLtools-Lite 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
|
|||
|
file, 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.
|
|||
|
|
|||
|
HTMLdoc. HTMLdoc is a free program for converting html files into a pdf or ps
|
|||
|
file.
|
|||
|
|
|||
|
SGMLSpm and docbook2X. Together, these two are used to generate man pages.
|
|||
|
SGMLSpm is a perl5 module library for processing parsed output from onsgmls,
|
|||
|
a program included with OpenJade. SGMLSpm includes an application called
|
|||
|
sgmlspl to use the SGMLSpm library. Sgmlspl 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 man pages.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2. Download the Packages
|
|||
|
|
|||
|
In this section, we will locate and download the software on the Internet.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2.1. OpenJade
|
|||
|
|
|||
|
OpenJade is an actively maintained open-source software project based on the
|
|||
|
Jade package by [http://www.jclark.com/] James Clark. Download the lastest
|
|||
|
stable release at:
|
|||
|
|
|||
|
[http://openjade.sourceforge.net/] http://openjade.sourceforge.net/
|
|||
|
|
|||
|
OpenJade also includes the OpenSP package and the TeX macros, jadetex and
|
|||
|
pdfjadetex for converting files to dvi and pdf. The following programs are
|
|||
|
provided by this package:
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>openjade
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>onsgmls
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>osgmlnorm
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>ospam
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>ospent
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>osx
|
|||
|
|
|||
|
|
|||
|
To use jadetex and pdfjadetex for making dvi, ps, and pdf, you must have a
|
|||
|
working TeX (tex) installation. If you do not have TeX, check with your Linux
|
|||
|
distribution for a binary package that can be downloaded and installed.
|
|||
|
Otherwise, you can download the teTeX distribution of TeX from:
|
|||
|
|
|||
|
[http://www.tug.org/tetex/] http://www.tug.org/tetex/
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2.2. DocBook SGML DTD
|
|||
|
|
|||
|
The DocBook DTD for SGML and XML are maintained by a technical committee at
|
|||
|
[http://www.oasis-open.org/] Oasis-Open.ORG. Download the current version
|
|||
|
(and any old versions you might need) of DocBook SGML at:
|
|||
|
|
|||
|
[http://www.oasis-open.org/docbook/sgml/index.shtml] http://
|
|||
|
www.oasis-open.org/docbook/sgml/index.shtml
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2.3. ISO8879 ENTITY SGML
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>Resources at [http://www.oasis-open.org/] OASIS:
|
|||
|
|
|||
|
<20><>+<2B>[http://www.oasis-open.org/cover/topics.html#entities] http://
|
|||
|
www.oasis-open.org/cover/topics.html#entities
|
|||
|
|
|||
|
<20><>+<2B>[http://www.oasis-open.org/cover/ISOEnts.zip] http://
|
|||
|
www.oasis-open.org/cover/ISOEnts.zip
|
|||
|
|
|||
|
<20><>+<2B>[http://www.oasis-open.org/cover/isoENT-tar.gz] http://
|
|||
|
www.oasis-open.org/cover/isoENT-tar.gz
|
|||
|
|
|||
|
|
|||
|
|
|||
|
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:
|
|||
|
|
|||
|
[http://reaster.com/iso8879-entities.tar.gz] http://reaster.com/
|
|||
|
iso8879-entities.tar.gz
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2.4. DocBook DSSSL
|
|||
|
|
|||
|
[http://www.nwalsh.com/] Norman Walsh's Document Style Semantics and
|
|||
|
Specification Language (DSSSL) files for the DocBook DTD (SGML/XML) are
|
|||
|
maintained at the [http://docbook.sourceforge.net/] DocBook Open Repository
|
|||
|
at [http://www.sourceforge.net/] SourceForge. These files, also known as the
|
|||
|
[http://docbook.sourceforge.net/projects/dsssl/doc/] Modular DocBook
|
|||
|
Stylesheets, tell openjade 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 [http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/
|
|||
|
index.htm] DSSSL language. The DSSSL language is decomposed into a group of
|
|||
|
different languages, but running through it all is the [http://
|
|||
|
www.cs.berkeley.edu/~wilensky/CS294/dsssl/html/h2-15.htm] Core Expression
|
|||
|
Language which is based on [http://www.schemers.org/Documents/Standards/R5RS/
|
|||
|
HTML/] Scheme.
|
|||
|
|
|||
|
The DocBook DSSSL package and documentation can be downloaded from the [http:
|
|||
|
//docbook.sourceforge.net/projects/dsssl/] DocBook DSSSL Stylesheets Project
|
|||
|
|
|||
|
The [http://www.linuxdoc.org/] Linux Documentation Project has a stylesheet
|
|||
|
customization file that turns on some nice style features. It can be
|
|||
|
downloaded at:
|
|||
|
|
|||
|
[http://www.linuxdoc.org/authors/tools/ldp.dsl] http://www.linuxdoc.org/
|
|||
|
authors/tools/ldp.dsl
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2.5. SGMLtools-Lite
|
|||
|
|
|||
|
SGMLtools-Lite is a frontend for openjade, jadetex, pdfjadex, dvips, and
|
|||
|
other programs. It provides a single command for generating all the formats
|
|||
|
possible with these tools. The lastest release can be downloaded at:
|
|||
|
|
|||
|
[http://sourceforge.net/projects/sgmltools-lite/] http://sourceforge.net/
|
|||
|
projects/sgmltools-lite/
|
|||
|
|
|||
|
This package is optional, but does make things easier sometimes.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2.6. HTMLdoc
|
|||
|
|
|||
|
HTMLdoc is a free program for converting websites into Portable Document
|
|||
|
Format (pdf) or PostScript (ps). For pdf, it creates a tree of bookmarks that
|
|||
|
make navigation easy. Both htmldoc and pdfjadetex output pdf files, but in
|
|||
|
slightly different formats. Try both and see which turns out best for a
|
|||
|
particular docbook file. See quick links below for download site.
|
|||
|
|
|||
|
You can download the lastest version of HTMLdoc from [http://www.easysw.com/]
|
|||
|
Easy Software Products' [ftp://ftp.easysw.com/pub/htmldoc/] ftp site.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2.7. DocBook2X
|
|||
|
|
|||
|
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 sgmlspl 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.
|
|||
|
|
|||
|
[http://www.cpan.org/] http://www.cpan.org/
|
|||
|
|
|||
|
[http://docbook2x.sourceforge.net/] http://docbook2x.sourceforge.net/
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3. Install the Packages
|
|||
|
|
|||
|
3.1. Before You Install
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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 README and a INSTALL file after you unpack an archive.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.2. Install OpenJade
|
|||
|
|
|||
|
3.2.1. openjade
|
|||
|
|
|||
|
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:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| 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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
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 $PATH.
|
|||
|
|
|||
|
You might be wondering why I dump the openjade source directly into /usr/
|
|||
|
local. The author experienced some issues with openjade's installation.
|
|||
|
However, with newer releases of OpenJade, you might try a standard (/usr/
|
|||
|
local/src) location for the openjade source package with some other prefix
|
|||
|
install location, and see how it goes.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.2.2. jadetex & pdfjadetex
|
|||
|
|
|||
|
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 Frank Atanassow Christoph and can
|
|||
|
be found at:
|
|||
|
|
|||
|
[ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf] ftp://
|
|||
|
ftp.dante.de/tex-archive/macros/jadetex/install.pdf
|
|||
|
|
|||
|
[http://reaster.com/installjadetex.pdf] http://reaster.com/installjadetex.pdf
|
|||
|
|
|||
|
The following is based on the instructions in install.pdf:
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.2.2.1. Create hugelatex (if needed)
|
|||
|
|
|||
|
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).
|
|||
|
|
|||
|
Verify that a working TeX is installed and find its directory:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| bash$ which tex |
|
|||
|
| /usr/share/texmf/bin/tex |
|
|||
|
| bash$ kpsewhich -expand-var='$TEXMFMAIN' |
|
|||
|
| /usr/share/texmf |
|
|||
|
| bash$ |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
|
|||
|
Using which should find the location of the tex program. If its not found,
|
|||
|
then you might need to install teTeX then return here. kpsewhich is a utility
|
|||
|
that comes with teTeX and finds the main tex directory if all goes well.
|
|||
|
|
|||
|
Now that the texmf directory is known, installation can begin:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| 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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
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:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| % 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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
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.
|
|||
|
|
|||
|
After setting up hugelatex, like above, it may not work until the texhash
|
|||
|
program is called:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| root# texhash |
|
|||
|
| texhash: Updating /usr/share/texmf/ls-R... |
|
|||
|
| texhash: Updating /var/cache/fonts/ls-R... |
|
|||
|
| texhash: Done. |
|
|||
|
| root# |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.2.2.2. jadetex & pdfjadetex
|
|||
|
|
|||
|
Setting up jadetex and pdfjadetex is similar to hugelatex.
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| 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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
This Makefile uses hugelatex, so hugelatex must have been setup already. When
|
|||
|
tex is run as hugelatex, jadetex, or pdfjadetex, it gets its program name
|
|||
|
(context) from argv[0] in the environment. Then, it scans texmf.cnf, and uses
|
|||
|
any context-specific settings it finds. The format (.fmt) files in /usr/share
|
|||
|
/texmf/web2c are also loaded based on the context.
|
|||
|
|
|||
|
The jadetex command takes a tex file generated from openjade, and outputs a
|
|||
|
dvi file. pdfjadetex takes a tex file generated from openjade, and outputs a
|
|||
|
pdf. The dvips program takes the dvi file and outputs a PostScript ps file
|
|||
|
that you can send to your printer or view with ghostscript gs.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.3. DocBook SGML DTD
|
|||
|
|
|||
|
3.3.1. Unpack the DocBook SGML DTD
|
|||
|
|
|||
|
The DocBook DTD is just some sgml text files, so there is nothing to compile.
|
|||
|
Just unzip them somewhere:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| # 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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.3.2. Unpack the ISO8879 Entities
|
|||
|
|
|||
|
For each DocBook DTD version unpacked, go into its directory and unpack the
|
|||
|
iso8879-entities.tar.gz file:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| cd /usr/local/share/sgml/docbook/4.1 |
|
|||
|
| tar -xvzf ~/iso8879-entities.tar.gz |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
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:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| # If needed ... |
|
|||
|
| cd /usr/local/share/sgml/docbook/4.1 |
|
|||
|
| ln -s docbook.cat catalog |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.4. DocBook DSSSL
|
|||
|
|
|||
|
Installation of the DocBook DSSSL, which works for all versions of DocBook,
|
|||
|
is just a matter of unzipping it somwhere.
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| 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. |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
That's all there is to installing the DSSSL, except for the setup of the
|
|||
|
$SGML_CATALOG_PATH discussed later. Don't forget to straighten out the file
|
|||
|
modes and owner/group of these unpacked files - often they are scrambled and
|
|||
|
inappropriate.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.5. SGMLtools-Lite
|
|||
|
|
|||
|
If you like it, you can install the SGMLtools-Lite, but it is optional. Its
|
|||
|
installation is the standard:
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| cd /usr/src |
|
|||
|
| tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz |
|
|||
|
| cd sgmltools-lite-3.0.2 |
|
|||
|
| ./configure |
|
|||
|
| make install |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
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.
|
|||
|
|
|||
|
One tweak that has to be done to make the sgmltools script work, is you have
|
|||
|
to edit it and set the path to openjade: vi `which sgmltools`. Consult its
|
|||
|
docs to learn more about it.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.6. htmldoc
|
|||
|
|
|||
|
3.6.1. binary
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.6.2. source
|
|||
|
|
|||
|
If you downloaded the source, you will also need the Fast Light Tool Kit or
|
|||
|
else it will not link:
|
|||
|
|
|||
|
[http://www.fltk.org/] http://www.fltk.org/
|
|||
|
|
|||
|
Installation is autoconf style. Just run the configure script, make, make
|
|||
|
install. If all goes well, it will install in /usr/bin.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.6.3. ldp_print
|
|||
|
|
|||
|
The htmldoc program has (or had) 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.
|
|||
|
|
|||
|
To fix this problem, a perl script ([http://www.linuxdoc.org/authors/tools/
|
|||
|
ldp_print.tar.gz] ldp_print) is available from [http://www.linuxdoc.org/]
|
|||
|
LinuxDoc.org. The lpd_print script processes a nochunks html file from
|
|||
|
openjade and then runs htmldoc on it to produce correctly rendered pdf and
|
|||
|
ps.
|
|||
|
|
|||
|
Tip Get it!
|
|||
|
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| 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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.7. DocBook2X and SGMLS.pm (sgmlspl)
|
|||
|
|
|||
|
3.7.1. sgmlspl
|
|||
|
|
|||
|
Before the spec files from DocBook2X are of any use, the SGMLS.pm module for
|
|||
|
perl version 5 has to be installed, assuming that perl version 5 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.
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| 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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
sgmlspl gets copied to /usr/local/bin.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.7.2. docbook2X (docbook2man-spec.pl)
|
|||
|
|
|||
|
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.
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| cd /usr/local/share/sgml |
|
|||
|
| tar -xvzf ~/docbook2X-0.6.0.tar.gz |
|
|||
|
| cd docbook2X |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
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.
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| patch docbook2man-spec.pl docbook2man-spec.pl.patch |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
Later, in Using DocBook, you will see how to use sgmlspl and
|
|||
|
docbook2man-spec.pl to generate a man page from a <refentry> DocBook
|
|||
|
document.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3.8. $SGML_CATALOG_FILES
|
|||
|
|
|||
|
The $SGML_CATALOG_FILES 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 $SGML_CATALOG_FILES
|
|||
|
can be set in /etc/profile:
|
|||
|
+-------------------------------------------------------------------------------------------+
|
|||
|
|########################################################################################## |
|
|||
|
|# 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 |
|
|||
|
|########################################################################################## |
|
|||
|
| |
|
|||
|
+-------------------------------------------------------------------------------------------+
|
|||
|
Save your profile, logout and then log back in to take effect.
|
|||
|
|
|||
|
Installation is complete! In the next section, we'll test the installation
|
|||
|
and convert some test DocBook files.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4. Using DocBook
|
|||
|
|
|||
|
Now that everything is installed, it's time to test it out and see how to use
|
|||
|
openjade and the other tools.
|
|||
|
|
|||
|
Figure 1. Example DocBook SGML file - test.sgml
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
|<!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> |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
For a guide to DocBook and a reference of DocBook elements, see:
|
|||
|
|
|||
|
DocBook: The Definitive Guide. [http://www.docbook.org/tdg/en/] http://
|
|||
|
www.docbook.org/tdg/en/
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4.1. Generating HTML
|
|||
|
|
|||
|
4.1.1. docbook.dsl
|
|||
|
|
|||
|
Figure 2. Generating HTML output using docbook.dsl
|
|||
|
+-------------------------------------------------------------------------------+
|
|||
|
|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$ |
|
|||
|
| |
|
|||
|
+-------------------------------------------------------------------------------+
|
|||
|
The warnings about DTDDECL can be ignored. They might be a little annoying,
|
|||
|
but these warnings are normal when using openjade. Other warnings and errors
|
|||
|
should be looked at and often indicate syntax errors that you should fix.
|
|||
|
|
|||
|
Two htm files are generated, one for each <sect1>. 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
|
|||
|
Modular DocBook Stylesheets, docbook.dsl.
|
|||
|
|
|||
|
Stylesheets can be customized to improve on these defaults. If you downloaded
|
|||
|
the [http://www.linuxdoc.org/] Linux Documentation Project's ldp.dsl file and
|
|||
|
installed it as shown in Section 3.3, then you already have a customized
|
|||
|
style available.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4.1.2. ldp.dsl
|
|||
|
|
|||
|
Figure 3. Generating HTML output using ldp.dsl
|
|||
|
+--------------------------------------------------------------------------------+
|
|||
|
|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$ |
|
|||
|
| |
|
|||
|
+--------------------------------------------------------------------------------+
|
|||
|
|
|||
|
Using ldp.dsl, the output looks better:
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>An index file has been created that contains the article information.
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>A table of contents has been automatically generated.
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>Each <sect1> is in its own file.
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>Filenames are derived from ID attributes of the <sect1> elements.
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>The file extension has changed to html.
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>The <screen> elements are shaded.
|
|||
|
|
|||
|
|
|||
|
Note how the ldp.dsl file is written in the command line: it has "#html"
|
|||
|
appended. ldp.dsl contains two <STYLE-SPECIFICATION> elements, one with ID=
|
|||
|
"html" and another with ID="print". This selects the html style from within
|
|||
|
ldp.dsl. The DocBook DSSSL contains support for converting DocBook files into
|
|||
|
html and print formats. In Section 3.3, we copied ldp.dsl into both the print
|
|||
|
and html directories. When generating html output, the html style should be
|
|||
|
selected like above. When generating other types of files, such as rtf and
|
|||
|
tex, they fall under the print style and so the print style should be
|
|||
|
selected from ldp.dsl. The alternative is to comment out or delete the print
|
|||
|
or html style in the copy of ldp.dsl in the respective directory. If a dsl
|
|||
|
file has more than one style-spec in it and none is selected like in the
|
|||
|
example above, then the first style encountered in the file is selected. For
|
|||
|
ldp.dsl, the print style-spec is first in the file, so it gets selected by
|
|||
|
default. So in the example above, without appending "#html" when specifying
|
|||
|
ldp.dsl as the dsssl stylesheet, the "print" style-spec would be selected and
|
|||
|
used when generating the html output. It will work, but is intended for when
|
|||
|
selecting the print/ldp.dsl and the formatting will be different.
|
|||
|
|
|||
|
To learn more about how the stylesheet customization files are made, read the
|
|||
|
[http://nwalsh.com/docbook/dsssl/doc/] documentation for the Modular DocBook
|
|||
|
Stylesheets. Customization mainly involves setting boolean option parameters
|
|||
|
to toggle style features on and off. Completely new style logic can be
|
|||
|
programmed using the the [http://www.cs.berkeley.edu/~wilensky/CS294/dsssl/
|
|||
|
html/index.htm] DSSSL language.
|
|||
|
|
|||
|
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 [http://www.w3.org/TR/html4/sgml/
|
|||
|
dtd.html] HTML Document Type Definition (DTD), 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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4.2. Generating rtf and tex
|
|||
|
|
|||
|
+---------------------------------------------------------------------------------+
|
|||
|
|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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------------+
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4.3. Generating dvi and ps
|
|||
|
|
|||
|
Figure 4. Running jadetex to generate a Device Independent (dvi) file.
|
|||
|
+----------------------------------------------------------------------------+
|
|||
|
|-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$ |
|
|||
|
| |
|
|||
|
+----------------------------------------------------------------------------+
|
|||
|
|
|||
|
The first time jadetex is run, warnings are printed. They can be ignored.
|
|||
|
Running it a second time, they do not appear again.
|
|||
|
|
|||
|
Figure 5. Running dvips to generate a PostScript (ps) file.
|
|||
|
+-------------------------------------------------------------------------------+
|
|||
|
|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$ |
|
|||
|
| |
|
|||
|
+-------------------------------------------------------------------------------+
|
|||
|
|
|||
|
Figure 6. Running htmldoc to generate a PostScript (ps) file.
|
|||
|
+-----------------------------------------------------------------------------------------+
|
|||
|
|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$ |
|
|||
|
| |
|
|||
|
+-----------------------------------------------------------------------------------------+
|
|||
|
If the ps file doesn't appear as expected, it may be due to bugs in htmldoc.
|
|||
|
Look inside the ldp_print script if you want to use it to make ps.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4.4. Generating pdf
|
|||
|
|
|||
|
Figure 7. Running pdfjadetex to generate a Portable Document Format (pdf)
|
|||
|
file.
|
|||
|
+--------------------------------------------------------------------------------+
|
|||
|
|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] |
|
|||
|
| |
|
|||
|
+--------------------------------------------------------------------------------+
|
|||
|
pdfjadetex must be run up to three times to resolve all internal references
|
|||
|
for things such as TOC page numbers.
|
|||
|
|
|||
|
Figure 8. Running htmldoc to generate a Portable Document Format (pdf) file.
|
|||
|
+-----------------------------------------------------------------------------+
|
|||
|
|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$ |
|
|||
|
| |
|
|||
|
+-----------------------------------------------------------------------------+
|
|||
|
If enabled in the ldp_print script, this would generate a ps file also.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4.5. Using make
|
|||
|
|
|||
|
Repeating the commands to generate the output files is tedious. The make
|
|||
|
command works perfectly to automate the process.
|
|||
|
|
|||
|
Figure 9. Filename: Makefile - automates document generation.
|
|||
|
# 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) -
|
|||
|
|
|||
|
|
|||
|
Usage is just like for most projects:
|
|||
|
|
|||
|
|
|||
|
Figure 10. Invoking make to run Makefile
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
| -- 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 |
|
|||
|
| |
|
|||
|
+---------------------------------------------------------------------------+
|
|||
|
|
|||
|
Notice the commented compile rules for pdf and ps which provide alternative
|
|||
|
means of generating those files.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4.6. Generating a man page
|
|||
|
|
|||
|
During the section on installing everything, we installed the perl version 5
|
|||
|
module SGMLS.pm. Then we installed Docbook2X which provides the spec.pl files
|
|||
|
for transforming DocBook <refentry> documents into nroff (man page) format
|
|||
|
with sgmlspl.
|
|||
|
|
|||
|
An example Docbook <refentry> document, for the foo command, is given below.
|
|||
|
|
|||
|
Figure 11. foo command man page, docbook <refentry> source (foo-ref.sgml)
|
|||
|
+----------------------------------------------------------------------------------+
|
|||
|
|<!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> |
|
|||
|
| |
|
|||
|
+----------------------------------------------------------------------------------+
|
|||
|
|
|||
|
Figure 12. Generating a man page with onsgmls, sgmlspl, and
|
|||
|
docbook2man-spec.pl
|
|||
|
+-------------------------------------------------------------------------------+
|
|||
|
|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 |
|
|||
|
| |
|
|||
|
+-------------------------------------------------------------------------------+
|
|||
|
|
|||
|
The man page, foo.1, is generated as a Section 1 page. The groff command is
|
|||
|
used to give a quick look at its formatted appearance.
|
|||
|
|
|||
|
To install this man page, it belongs in any man/man1 directory, where the
|
|||
|
directory man/ is added to $MANPATH in the environment. The standard location
|
|||
|
is /usr/local/man/man1. The standard sections in the man pages system are 1
|
|||
|
though 9. Each is for holding specific catagories of documentation.
|
|||
|
|
|||
|
|
|||
|
Table 1. Manual Pages Sections
|
|||
|
+-------+----------------------------------------+
|
|||
|
|Section| Purpose |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man1 | User programs |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man2 | System calls |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man3 | Library functions and subroutines |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man4 | Devices |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man5 | File formats |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man6 | Games |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man7 | Miscellaneous |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man8 | System administration |
|
|||
|
+-------+----------------------------------------+
|
|||
|
| man9 |Kernel internal variables and functions |
|
|||
|
+-------+----------------------------------------+
|
|||
|
|
|||
|
Tip The source file for a man page, like foo-ref.sgml, 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 man
|
|||
|
page can be made into html and rtf, tex, pdf, dvi, and ps. This can
|
|||
|
really save a lot of conversion work!
|
|||
|
|
|||
|
Have fun !
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
A. Legal
|
|||
|
|
|||
|
A.1. Copyright and Licenses
|
|||
|
|
|||
|
Copyright (c) 2001, 2002 Robert B. Easter
|
|||
|
|
|||
|
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".
|
|||
|
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
A.2. Disclaimer
|
|||
|
|
|||
|
No liability for the contents of this document can be accepted. Use the
|
|||
|
concepts, examples and other content at your own risk.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
Naming of particular products or brands should not be seen as endorsements.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
B. GNU Free Documentation License
|
|||
|
|
|||
|
Version 1.1, March 2000
|
|||
|
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
0. PREAMBLE
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
1. APPLICABILITY AND DEFINITIONS
|
|||
|
|
|||
|
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".
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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".
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
2. VERBATIM COPYING
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
You may also lend copies, under the same conditions stated above, and you may
|
|||
|
publicly display copies.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
3. COPYING IN QUANTITY
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
4. MODIFICATIONS
|
|||
|
|
|||
|
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:
|
|||
|
|
|||
|
A. 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.
|
|||
|
|
|||
|
B. 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).
|
|||
|
|
|||
|
C. State on the Title page the name of the publisher of the Modified
|
|||
|
Version, as the publisher.
|
|||
|
|
|||
|
D. Preserve all the copyright notices of the Document.
|
|||
|
|
|||
|
E. Add an appropriate copyright notice for your modifications adjacent to
|
|||
|
the other copyright notices.
|
|||
|
|
|||
|
F. 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.
|
|||
|
|
|||
|
G. Preserve in that license notice the full lists of Invariant Sections and
|
|||
|
required Cover Texts given in the Document's license notice.
|
|||
|
|
|||
|
H. Include an unaltered copy of this License.
|
|||
|
|
|||
|
I. 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.
|
|||
|
|
|||
|
J. 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.
|
|||
|
|
|||
|
K. 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.
|
|||
|
|
|||
|
L. 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.
|
|||
|
|
|||
|
M. Delete any section entitled "Endorsements". Such a section may not be
|
|||
|
included in the Modified Version.
|
|||
|
|
|||
|
N. Do not retitle any existing section as "Endorsements" or to conflict in
|
|||
|
title with any Invariant Section.
|
|||
|
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
5. COMBINING DOCUMENTS
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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."
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
6. COLLECTIONS OF DOCUMENTS
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
7. AGGREGATION WITH INDEPENDENT WORKS
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
8. TRANSLATION
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
9. TERMINATION
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
10. FUTURE REVISIONS OF THIS LICENSE
|
|||
|
|
|||
|
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 [http://www.gnu.org/copyleft/] http://
|
|||
|
www.gnu.org/copyleft/.
|
|||
|
|
|||
|
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.
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
How to use this License for your documents
|
|||
|
|
|||
|
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:
|
|||
|
|
|||
|
|
|||
|
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".
|
|||
|
|
|||
|
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.
|
|||
|
|
|||
|
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.
|