Differences between current version and predecessor to the previous major change of HowToDocBookInstall.
Other diffs: Previous Revision, Previous Author, or view the Annotated Edit History
| Newer page: | version 3 | Last edited on Monday, October 25, 2004 2:21:26 am | by StuartYeates | |
| Older page: | version 2 | Last edited on Friday, June 7, 2002 1:06:30 am | by perry | Revert |
@@ -1,2265 +1 @@
-!DocBook Install mini-HOWTO
-!!!!DocBook Install mini-HOWTO
-!Robert B Easter
-
- reaster@reaster.com
-
-
-
-__Revision History__Revision v1.82002-02-04Revised 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
-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.
-
-
-
-
-
-
-----; __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: ; . 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/
-
-
-
-
- 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 `bookb
-and `articleb
-!DocBook tags are used to create books and articles. Within these
-documents, the `chapterb,
-`sect1b, and `parab
-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 8 section numbering, and other
-features.
-
-
-
-
- !DocBook is also designed for authoring unix __man__ pages by writing
-`refentryb 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
-"8amp;"='8', "8gt;"='b', and "8lt;"='`'.
-
-
-
-
-__!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 James Clark.
-Download the lastest stable release at:
-
-
-
-
- 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:
-
-
-
-
-
-
-
-*
-
-openjade
-
-
-*
-*
-
-onsgmls
-
-
-*
-*
-
-osgmlnorm
-
-
-*
-*
-
-ospam
-
-
-*
-*
-
-ospent
-
-
-*
-*
-
-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/
-
-
-----
-!!2.2. !DocBook SGML DTD
-
-The !DocBook DTD for SGML and XML are maintained by a technical committee at
-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
-
-
-----
-!!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.
-
-
-
-
-
-
-
-*
-
-Resources at OASIS:
-
-
-
-
-
-**
-
-http://www.oasis-open.org/cover/topics.html#entities
-
-
-**
-**
-
-http://www.oasis-open.org/cover/ISOEnts.zip
-
-
-**
-**
-
-http://www.oasis-open.org/cover/isoENT-tar.gz
-
-
-**
-
-
-
-*
-
- ISOEnts.zip can simply be __unzip__ped into the directory where the !DocBook DTD
-is __unzip__ped without requiring anything else but
-the files in isoENT-tar.gz are also needed. Again, the files in isoENT-tar.gz
-are to be __unzip__ped 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
-
-
-----
-!!2.4. !DocBook DSSSL
-
- Norman Walsh's Document Style Semantics and Specification
-Language (DSSSL) files for the !DocBook DTD (SGML/XML) are maintained at the
-!DocBook Open Repository
-at !SourceForge.
-These files, also known as the 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
-DSSSL language. The DSSSL
-language is decomposed into a group of different languages, but running through it all is the
-Core Expression Language
-which is based on Scheme.
-
-
-
-
- The !DocBook DSSSL package and documentation can be downloaded from the
-!DocBook DSSSL Stylesheets Project
-
-
-
-
- The 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
-
-
-----
-!!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/
-
-
-
- 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 Easy Software Products'
-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://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 8 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
-
-
-
-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 8 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
[[
]
-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./ 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 __unzip__ping 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..2.tar.gz
-cd sgmltools-lite-3..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/
-
-
-
-
- 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
-(ldp_print)
-is available from !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.
-
-
-
-
-
-
-
-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-.6..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 `refentryb
-!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,
-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./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"b
-`article lang="en"b
-`articleinfob
-`titlebThis is a Test`/titleb
-`authorb
-`firstnamebJohn`/firstnameb
-`surnamebDoe`/surnameb
-`othername role="mi"bL`/othernameb
-`affiliationb
-`addressb
-`emailbj.doe@jdoe dot com`/emailb
-`/addressb
-`/affiliationb
-`/authorb
-`revhistoryb
-`revisionb
-`revnumberbv1.`/revnumberb
-`dateb2000-12-30`/dateb
-`authorinitialsbjld`/authorinitialsb
-`/revisionb
-`/revhistoryb
-`abstractb
-`parab
-This is a test !DocBook document.
-`/parab
-`/abstractb
-`/articleinfob
-`sect1 id="test1"b
-`titlebTest 1`/titleb
-`parab
-Test section 1.
-`/parab
-`sect2b
-`titlebTest 1.1`/titleb
-`parab
-Test section 1.1
-`/parab
-`/sect2b
-`sect2b
-`titlebTest 1.2`/titleb
-`parab
-`screenb
--- Test section 1.2
-openjade -t sgml -d $DSLFILE test.sgml
-`/screenb
-`/parab
-`/sect2b
-`/sect1b
-`sect1 id="test2"b
-`titlebTest 2`/titleb
-`parab
-Test section 2.
-`/parab
-`sect2b
-`titlebTest 2.1`/titleb
-`parab
-Test section 2.1
-`/parab
-`/sect2b
-`sect2b
-`titlebTest 2.2`/titleb
-`parab
-Test section 2.2
-`/parab
-`/sect2b
-`/sect1b
-`/articleb
-
-For a guide to !DocBook and a reference of !DocBook elements, see:
-
-
-
-
-__!DocBook: The Definitive Guide. __ 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 `sect1b.
-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
-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:
-
-
-
-
-
-*
-
- An index file has been created that contains the article information.
-
-
-
-*
-*
-
- A table of contents has been automatically generated.
-
-
-
-*
-*
-
- Each `sect1b is in its own file.
-
-
-
-*
-*
-
- Filenames are derived from ID attributes of the `sect1b elements.
-
-
-
-*
-*
-
- The file extension has changed to html.
-
-
-
-*
-*
-
- The `screenb elements are shaded.
-
-
-
-*
-
-
-
-
- Note how the ldp.dsl file is written in the command line:
-it has "#html" appended. ldp.dsl
-contains two `STYLE-SPECIFICATIONb 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
-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 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
-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..46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [[2..46] [[3..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..46]
-(/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [[2..46] [[3..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' -b test.ps
-`texc.prob`8r.encb`texps.prob`special.prob`color.prob. [[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..46[[/usr/share/texmf/dvips/con
-fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [[2..46] [[3..46]
-(test.aux) )`8r.encb
-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 b 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) b $(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 `refentryb documents into
-__nroff__ (__man__ page) format
-with __sgmlspl__.
-
-
-
-
- An example Docbook `refentryb document, for the
-__foo__ command, is given below.
-
-
-
-
-
-
-__Figure 11. __foo__ command __man__ page, docbook `refentryb source (foo-ref.sgml)__
-
-
-`!DOCTYPE refentry PUBLIC "-//OASIS//DTD !DocBook V4.1//EN"b
-`refentryb
-`refentryinfob
-`dateb2001-01-01`/dateb
-`/refentryinfob
-`refmetab
-`refentrytitleb
-`applicationbfoo`/applicationb
-`/refentrytitleb
-`manvolnumb1`/manvolnumb
-`refmiscinfobfoo 1.`/refmiscinfob
-`/refmetab
-`refnamedivb
-`refnameb
-`applicationbfoo`/applicationb
-`/refnameb
-`refpurposeb
-Does nothing useful.
-`/refpurposeb
-`/refnamedivb
-`refsynopsisdivb
-`refsynopsisdivinfob
-`dateb2001-01-01`/dateb
-`/refsynopsisdivinfob
-`cmdsynopsisb
-`commandbfoo`/commandb
-`argb`optionb-f `/optionb`replaceable class="parameter"bbar`/replaceableb`/argb
-`argb`optionb-d`replaceable class="parameter"bn`/replaceableb`/optionb`/argb
-`arg rep="repeat"b`replaceable class="parameter"bfile`/replaceableb`/argb
-`/cmdsynopsisb
-`/refsynopsisdivb
-`refsect1b
-`refsect1infob
-`dateb2001-01-01`/dateb
-`/refsect1infob
-`titlebDESCRIPTION`/titleb
-`parab
-`commandbfoo`/commandb does nothing useful.
-`/parab
-`/refsect1b
-`refsect1b
-`titlebOPTIONS`/titleb
-`variablelistb
-`varlistentryb
-`termb-f `replaceable class="parameter"bbar`/replaceableb`/termb
-`listitemb
-`parab
-Takes `filenamebbar`/filenameb 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.
-`/parab
-`/listitemb
-`/varlistentryb
-`varlistentryb
-`termb-d`replaceable class="parameter"bn`/replaceableb`/termb
-`listitemb
-`parab
-Do something, where integer
-`replaceable class="parameter"bn`/replaceableb
-specifies how many times.
-`/parab
-`/listitemb
-`/varlistentryb
-`varlistentryb
-`termb`replaceable class="parameter"bfile...`/replaceableb`/termb
-`listitemb
-`parab
-Processes the files in the order listed,
-sending all output to stdout.
-`/parab
-`/listitemb
-`/varlistentryb
-`/variablelistb
-`/refsect1b
-`refsect1b
-`titlebUSAGE`/titleb
-`parab
-`commandbfoo`/commandb -f foo.conf -d2 foodata.foo
-`/parab
-`/refsect1b
-`refsect1b
-`titlebCAVEATS`/titleb
-`parab
-Other programs named `commandbfoo`/commandb may exist and actually
-do something!
-`/parab
-`/refsect1b
-`refsect1b
-`titlebBUGS`/titleb
-`parab
-None. Program does nothing.
-`/parab
-`/refsect1b
-`refsect1b
-`titlebAUTHOR`/titleb
-`parab
-`authorb
-`firstnamebFoo`/firstnameb
-`othername role="mi"bE`/othernameb
-`surnamebBar`/surnameb
-`contribbOriginal author`/contribb
-`/authorb
-`/parab
-`/refsect1b
-`/refentryb
-
-
-
-
-
-
-
-__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__
-
-
-SectionPurposeman1User programsman2System callsman3Library functions and subroutinesman4Devicesman5File formatsman6Gamesman7Miscellaneousman8System administrationman9Kernel internal variables and functions
-
-
-
-
-
-
- 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.
-
-----
-!!!. 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:
-
-
-
-
-
-
-#
-
-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.
-
-
-#
-#
-
-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).
-
-
-#
-#
-
-State on the Title page
-the name of the publisher of the Modified Version, as the
-publisher.
-
-
-#
-#
-
-Preserve all the
-copyright notices of the Document.
-
-
-#
-#
-
-Add an appropriate
-copyright notice for your modifications adjacent to the other
-copyright notices.
-
-
-#
-#
-
-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.
-
-
-#
-#
-
-Preserve in that license
-notice the full lists of Invariant Sections and required Cover
-Texts given in the Document's license notice.
-
-
-#
-#
-
-Include an unaltered
-copy of this License.
-
-
-#
-#
-
-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.
-
-
-#
-#
-
-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.
-
-
-#
-#
-
-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.
-
-
-#
-#
-
-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.
-
-
-#
-#
-
-Delete any section
-entitled "Endorsements". Such a section may not be included in
-the Modified Version.
-
-
-#
-#
-
-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/.
-
-
-
-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
.
+Describe
[HowToDocBookInstall
] here.
