From c781a0394ddbd1ea543ef3c69f8195dddb3f66a3 Mon Sep 17 00:00:00 2001 From: gferg <> Date: Tue, 5 Feb 2002 14:33:23 +0000 Subject: [PATCH] updated --- LDP/howto/docbook/DocBook-Install.sgml | 563 ++++++++++---------- LDP/howto/docbook/HOWTO-INDEX/miniChap.sgml | 2 +- LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml | 2 +- 3 files changed, 285 insertions(+), 282 deletions(-) diff --git a/LDP/howto/docbook/DocBook-Install.sgml b/LDP/howto/docbook/DocBook-Install.sgml index b7b83375..e81af338 100644 --- a/LDP/howto/docbook/DocBook-Install.sgml +++ b/LDP/howto/docbook/DocBook-Install.sgml @@ -11,15 +11,15 @@ B
- reaster@comptechnews.com + reaster@reaster.com
- v1.7 - 2001-03-28 + v1.8 + 2002-02-04 rbe @@ -27,8 +27,10 @@ DocBook-Install-mini-HOWTO is a detailed practical guide for novices to - quickly getting DocBook installed and processing sgml files into html, - ps, and pdf on a GNU/Linux system - other systems may be similar. Since + 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. @@ -68,23 +70,27 @@ 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> + 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. + 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 + 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 manpages using - <refentry>. + 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. @@ -97,21 +103,24 @@ OpenJade - OpenJade is an Standard Generalized Markup Language (SGML) - and Document Style Semantics and Specification Language - (DSSSL) processor. It processes DocBook sgml source - files into html, tex, rtf, txt and others. Openjade is - the essential engine for converting a DocBook file into - other formats. The tex out format is used mostly as an - intermediate format to obtain dvi, pdf, and ps via - TeX macros and dvi converters. + 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 Document Type Definition (DTD) files are SGML files + 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 @@ -130,24 +139,30 @@ - DocBook DSSSL + DocBook DSSSL (Modular DocBook Stylesheets) - Document Style Semantics and Specification Language (DSSSL) - files (dsl suffix) for a particular DTD, in this case DocBook, - specify how to convert DocBook into html, rtf, tex etc. + 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 - Sgmltools is a frontend wrapper for running openjade and the - TeX macros jadetex and pdfjadetex, macros included with openjade. - Converting a DocBook file to ps or pdf is a two or three-step - process. OpenJade outputs a tex file which is the input of jadetex, to - produce a dvi, and pdfjadetex, to produce a pdf. A ps file is obtained - by passing the dvi file through dvips. The sgmltools script provides - a single command to perform these tasks. + 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. @@ -155,20 +170,20 @@ HTMLdoc HTMLdoc is a free program for converting html files into a - pdf or ps file. + pdf or ps file. SGMLSpm and docbook2X - Together, these two are used to generate manpages. SGMLSpm is a perl5 module + 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 manpages. + provides the spec files for transforming DocBook files into man pages. @@ -190,14 +205,14 @@ In this section, we will locate and download the software on the Internet. OpenJade is an actively maintained open-source software project based on the Jade package by James Clark. - Download the lastest stable release (1.3?) at: + 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 + 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: @@ -210,8 +225,9 @@ In this section, we will locate and download the software on the Internet. - 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 + 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: @@ -230,7 +246,7 @@ In this section, we will locate and download the software on the Internet. - http://www.oasis-open.org/docbook/sgml/index.html + http://www.oasis-open.org/docbook/sgml/index.shtml @@ -255,14 +271,16 @@ In this section, we will locate and download the software on the Internet. - 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: + 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://www.comptechnews.com/~reaster/iso8879-entities.tar.gz + http://reaster.com/iso8879-entities.tar.gz @@ -270,18 +288,23 @@ In this section, we will locate and download the software on the Internet. DocBook DSSSL - The Document Style Semantics and Specification Language (DSSSL) files for the DocBook DTD (SGML/XML) - is provided by Norm Walsh. These files, called the - Modular DocBook Stylesheets, tell openjade what + 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 a - language called the Core Expression Language which is derived from - Scheme. - The DocBook DSSSL package and documentation can be downloaded from Norm Walsh: + 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. - http://nwalsh.com/docbook/dsssl/ + The DocBook DSSSL package and documentation can be downloaded from the + DocBook DSSSL Stylesheets Project @@ -294,14 +317,13 @@ In this section, we will locate and download the software on the Internet. - Sgmltools-lite + SGMLtools-Lite - Sgmltools is a frontend for openjade, jadetex, pdfjadex, + 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, v1.3 as of writing, can be downloaded at: + lastest release can be downloaded at: - http://www.sgmltools.org/ http://sourceforge.net/projects/sgmltools-lite/ This package is optional, but does make things easier sometimes. @@ -311,19 +333,28 @@ In this section, we will locate and download the software on the Internet. 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 + 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. + + DocBook2X - DocBook2X requires perl5 and the SGMLS.pm perl module, available at CPAN. SGMLS.pm - provides libraries and a program called sgmlspl which translates DocBook files into other + 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. @@ -331,77 +362,29 @@ In this section, we will locate and download the software on the Internet. http://docbook2x.sourceforge.net/ - - Quick Download Links - - The files below are the latest versions as of this writing: - - - <ulink url="http://download.sourceforge.net/openjade/openjade-1.3.tar.gz">openjade-1.3.tar.gz</ulink> - - OpenJade, release version 1.3. - - - - - <ulink url="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip">docbk41.zip</ulink> - - DocBook SGML DTD, version 4.1. - - - - - <ulink url="http://www.comptechnews.com/~reaster/iso8879-entities.tar.gz">iso8879-entities.tar.gz</ulink> - - ISO 8879 SGML entities. It's easier to just use this file. You can download the two other files - if you want and then rename filename extensions to gml. - - - - - <ulink url="http://nwalsh.com/docbook/dsssl/db160.zip">db160.zip</ulink> & <ulink url="http://nwalsh.com/docbook/dsssl/db160d.zip">db160d.zip</ulink> - - Norm Walsh Modular DocBook DSSSL stylesheets, version 1.60 and its documentation. - - - - - <ulink url="http://download.sourceforge.net/sgmltools-lite/sgmltools-lite-3.0.2.tar.gz">sgmltools-lite-3.0.2.tar.gz</ulink> - - Sgmltools-lite release version 3.0.2. Again, this is optional. - - - - - <ulink url="ftp://ftp.easysw.com/pub/htmldoc/1.8.9/">ftp://ftp.easysw.com/pub/htmldoc/1.8.9/</ulink> - - Htmldoc 1.8.9. Binaries and source are available. Choose what you - need for your platform. Binaries are recommended. To find a binary, - you can download it directly from ftp with the link above. If which to choose - is not obvious, then try to going to the EasySw website: - http://www.easysw.com/software.html - - - - - <ulink url="http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz">http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz</ulink> - - SGMLS.pm 1.03ii at CPAN. (sgmlspl) - - - - - <ulink url="http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz">http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz</ulink> - - DocBook2X 0.6.0 (provides docbook2man-spec.pl for use with sgmlspl above) - - - Install the Packages + + 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. + + Install OpenJade @@ -426,12 +409,18 @@ In this section, we will locate and download the software on the Internet. 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. + jadetex & pdfjadetex - As mentioned, jadetex and pdfjadetex are TeX macros that are packaged with + 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 @@ -444,19 +433,20 @@ In this section, we will locate and download the software on the Internet. and can be found at: ftp://ftp.dante.de/tex-archive/macros/jadetex/install.pdf - http://www.comptechnews.com/~reaster/installjadetex.pdf + http://reaster.com/installjadetex.pdf - The following, is based on the instructions in install.pdf: + The following is based on the instructions in install.pdf: 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). + 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: @@ -469,13 +459,13 @@ In this section, we will locate and download the software on the Internet. - Using which should find the location of the tex program. If its not + 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 + 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: + Now that the texmf directory is known, installation can begin: cd /usr/share/texmf cd tex/latex @@ -490,8 +480,8 @@ In this section, we will locate and download the software on the Internet. 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 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: @@ -535,13 +525,13 @@ In this section, we will locate and download the software on the Internet. stack_size.pdfjadetex = 15000 Here, we've gone ahead and added entries for - jadetex and pdfjadetex, which we'll be setting + 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: + 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... @@ -555,7 +545,8 @@ In this section, we will locate and download the software on the Internet. jadetex & pdfjadetex - Setting up jadetex and pdfjadetex is similar to hugelatex. + Setting up jadetex and pdfjadetex + is similar to hugelatex. cd /usr/local/openjade-1.3/dsssl make -f Makefile.jadetex install @@ -570,19 +561,22 @@ In this section, we will locate and download the software on the Internet. # 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 + 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. - Jadetex takes a tex file generated from - openjade, and outputs a dvi. pdfjadetex takes a tex file - generated from openjade, and outputs a pdf. The dvips - program takes the dvi and outputs a postscript ps file. + 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. @@ -593,8 +587,8 @@ In this section, we will locate and download the software on the Internet. Unpack the DocBook SGML DTD - The DocBook DTD is just some sgml text files, so there is nothing to compile. - Just unzip them somewhere: + 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 @@ -605,20 +599,20 @@ In this section, we will locate and download the software on the Internet. 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. + 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 + 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. + a good idea to get it and install it in a 3.1/ subdirectory. @@ -626,14 +620,14 @@ In this section, we will locate and download the software on the Internet. Unpack the ISO8879 Entities For each DocBook DTD version unpacked, go into its directory and unpack - the iso8879-entities.tar.gz file: + 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 + 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 ... @@ -648,7 +642,7 @@ In this section, we will locate and download the software on the Internet. DocBook DSSSL Installation of the DocBook DSSSL, which works for all versions of DocBook, is - just a matter of unzipping it somwhere. + just a matter of unzipping it somwhere. cd /usr/local/share/sgml mkdir dsssl; cd dsssl @@ -669,9 +663,9 @@ In this section, we will locate and download the software on the Internet. - sgmltools-lite + SGMLtools-Lite - If you like it, you can install the sgmltools-lite, but it is optional. + If you like it, you can install the SGMLtools-Lite, but it is optional. Its installation is the standard: cd /usr/src @@ -680,14 +674,14 @@ In this section, we will locate and download the software on the Internet. ./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. + 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. + 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. @@ -697,7 +691,7 @@ In this section, we will locate and download the software on the Internet. binary - Preferrably you downloaded a binary distribution of htmldoc for + 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. @@ -706,7 +700,7 @@ In this section, we will locate and download the software on the Internet. source - If you downloaded the source, you will also need the Fast Light Tool Kit + If you downloaded the source, you will also need the Fast Light Tool Kit or else it will not link: @@ -714,25 +708,27 @@ In this section, we will locate and download the software on the Internet. - Installation is autoconf style. - Just run the configure script, make, make install. If all goes - well, it will install in /usr/bin. + Installation is autoconf style. + Just run the configure script, make, + make install. If all goes well, it will install in + /usr/bin. ldp_print - The htmldoc program has a few glitches when generating output from - html files from openjade. For instance, bullet items are not + 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 + To fix this problem, a perl script (ldp_print) is available from LinuxDoc.org. - The script processes a nochunks html file from openjade and then runs htmldoc on it - to produce correctly rendered pdf and ps. + 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! @@ -746,7 +742,7 @@ In this section, we will locate and download the software on the Internet. 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 + to change for your system. Perhaps someday htmldoc's bugs will be fixed and this script will not be needed anymore. @@ -758,11 +754,12 @@ In this section, we will locate and download the software on the Internet. sgmlspl - Before the spec files from DocBook2X are of any use, the SGMLS.pm module - for perl5 has to be installed, assuming that perl5 is installed. The - installation of this module is not as automated as most perl module - installs. It uses a Makefile that has to be edited first before - running make. + 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 @@ -790,7 +787,7 @@ In this section, we will locate and download the software on the Internet. docbook2X (docbook2man-spec.pl) - DocBook2X contains no program to compile or install, + 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. @@ -798,15 +795,16 @@ In this section, we will locate and download the software on the Internet. tar -xvzf ~/docbook2X-0.6.0.tar.gz cd docbook2X - In the unpacked directory is the docbook2man-spec.pl and + 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 manpage from - a refentry docbook document. + 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. @@ -817,10 +815,10 @@ In this section, we will locate and download the software on the Internet. $SGML_CATALOG_FILES The $SGML_CATALOG_FILES environment variable is used by - openjade (and other SGML software) to locate DTDs and DSL (stylesheets). + 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: + here is how $SGML_CATALOG_FILES can be set in /etc/profile: ########################################################################################## # SGML DocBook - openjade sgmltools-lite @@ -830,7 +828,7 @@ SGML_SHARE=/usr/local/share/sgml PATH=$PATH:$JADE_HOME/bin # DSSSL stylesheets -# Norm Walsh's Modular DocBook 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 @@ -851,11 +849,11 @@ 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. + 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. + and convert some test DocBook files. @@ -865,12 +863,12 @@ export JADE_HOME SGML_SHARE PATH SGML_CATALOG_FILES Using DocBook Now that everything is installed, it's time to test it out - and see how to use openjade and the other tools. + and see how to use openjade and the other tools.
- Example DocBook SGML file - test.sgml + Example DocBook SGML file - <filename>test.sgml</filename> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> @@ -953,23 +951,23 @@ Test section 2. </article>
- For a guide to DocBook and a reference of DocBook elements, go to: + For a guide to DocBook and a reference of DocBook elements, see: - DocBook: The Definitive Reference + DocBook: The Definitive Guide - http://www.docbook.org/tdg/html/docbook.html + http://www.docbook.org/tdg/en/ Generating HTML - docbook.dsl + <filename>docbook.dsl</filename>
- Generating HTML output using docbook.dsl + Generating HTML output using <filename>docbook.dsl</filename> bash$ ls -l total 4 @@ -986,16 +984,16 @@ total 12 bash$
- The warnings about DTDDECL can be ignored. They might be a little annoying, - but these warnings are normal when using jade. Other warnings and errors + 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. + 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. + Modular DocBook Stylesheets, docbook.dsl. @@ -1008,10 +1006,10 @@ bash$ - ldp.dsl + <filename>ldp.dsl</filename>
- Generating HTML output using ldp.dsl + Generating HTML output using <filename>ldp.dsl</filename> bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/ldp.dsl#html test.sgml bash$ ls -l @@ -1025,7 +1023,7 @@ bash$
- Using ldp.dsl, the output looks better: + Using ldp.dsl, the output looks better: @@ -1039,45 +1037,46 @@ bash$ - Each <SECT1> is in its own file. + Each sect1 is in its own file. - Filenames are derived from ID attributes of the <SECT1> elements. + Filenames are derived from ID attributes of the sect1 elements. - The file extension has changed to html. + The file extension has changed to html. - The <SCREEN> elements are shaded. + 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 + 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 + 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 + 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" + 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. @@ -1085,20 +1084,20 @@ bash$ 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 - DSSSL's Core Programming Language, - as mentioned in Section 2.4. + 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 + 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. + later as an intermediate format for the generation of pdf and ps + formats. The dsssl_spec must specify a dsl file, not a directory. @@ -1206,12 +1205,12 @@ bash$ - The first time jadetex is run, warnings are printed. They can + The first time jadetex is run, warnings are printed. They can be ignored. Running it a second time, they do not appear again.
- Running dvips to generate a Postscript (ps) file. + Running <command>dvips</command> to generate a <ProductName>PostScript</ProductName> (ps) file. bash$ ls -l total 80 @@ -1241,7 +1240,7 @@ bash$
- Running htmldoc to generate a Postscript (ps) file. + Running <command>htmldoc</command> to generate a <ProductName>PostScript</ProductName> (<filename>ps</filename>) file. bash$ ls -l -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml @@ -1253,8 +1252,9 @@ bash$ ls -l bash$
- If the ps doesn't appear as expected, it is due to bugs in htmldoc. - Look inside the ldp_print script if you want to use it to make ps. + 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. @@ -1262,7 +1262,7 @@ bash$ Generating pdf
- Running pdfjadetex to generate a Portable Document Format (pdf) file. + Running <command>pdfjadetex</command> to generate a Portable Document Format (<filename>pdf</filename>) file. bash$ ls -l -rw-r--r-- 1 reaster users 753 Dec 31 20:58 test.aux @@ -1311,13 +1311,13 @@ bash$ pdfjadetex test.tex [snip]
- Pdfjadetex must be run up to three times to resolve all + pdfjadetex must be run up to three times to resolve all internal references for things such as TOC page numbers.
- Running htmldoc to generate a Portable Document Format (pdf) file. + Running <command>htmldoc</command> to generate a Portable Document Format (<filename>pdf</filename>) file. bash$ ls -l -rw-r--r-- 1 reaster users 1143 Dec 31 18:18 test.sgml @@ -1330,22 +1330,22 @@ bash$ ls -l bash$
- If enabled in the ldp_print script, this would generate a ps file + If enabled in the ldp_print script, this would generate a ps file also. - Using make + Using <command>make</command> Repeating the commands to generate the output files is tedious. - The make command works perfectly to automate the process. + The make command works perfectly to automate the process.
- Filename: Makefile - automates document generation. + Filename: <filename>Makefile</filename> - automates document generation. # Generates online and print versions of SGML source file. @@ -1453,7 +1453,7 @@ $(PS_FILE): $(DVI_FILE) Usage is just like for most projects:
- Invoking make to run Makefile + Invoking <command>make</command> to run <filename>Makefile</filename> -- generate html (default) make @@ -1473,27 +1473,28 @@ $(PS_FILE): $(DVI_FILE)
- Notice the commented compile rules for pdf and ps which + Notice the commented compile rules for pdf and ps which provide alternative means of generating those files. - Generating a manpage + Generating a <command>man</command> page During the section on installing everything, we installed - the perl5 module SGMLSpm. Then we installed docbook2X - which provides the spec.pl files for transforming - DocBook RefEntry documents into nroff (manpage) format - with sgmlspl. + 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. + An example Docbook refentry document, for the + foo command, is given below.
- foo manpage, docbook refentry source (foo-ref.sgml) + <command>foo</command> command <command>man</command> page, docbook <SGMLTag class="StartTag">refentry</SGMLTag> source (<filename>foo-ref.sgml</filename>) <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> <refentry> @@ -1607,7 +1608,7 @@ $(PS_FILE): $(DVI_FILE)
- Generating a manpage with onsgmls, sgmlspl, and docbook2man-spec.pl + Generating a <command>man</command> page with <command>onsgmls</command>, <command>sgmlspl</command>, and <filename>docbook2man-spec.pl</filename> bash$ ls -l -rw-r--r-- 1 reaster users 2434 Jan 3 03:51 foo-ref.sgml @@ -1666,21 +1667,21 @@ bash$ less foo.1 - The manpage, foo.1, is generated as a Section 1 page. The - groff command is used to give a quick look at its formatted + 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 manpage, it belongs in any man/man1 directory, - where the directory man/ is added to $MANPATH + 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 manpages system are 1 though 9. + The standard sections in the man pages system are 1 though 9. Each is for holding specific catagories of documentation. - Manpage Sections + Manual Pages Sections @@ -1731,16 +1732,18 @@ bash$ less foo.1 - The source file for a manpage, like foo-ref.sgml, + 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 manpage can be made into html and rtf, tex, - pdf, dvi, and ps. This can really save a lot of conversion work! + 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! + Have fun ! @@ -1752,7 +1755,7 @@ bash$ less foo.1
- Copyright (c) 2001 Robert B. Easter + Copyright (c) 2001, 2002 Robert B. Easter Permission is granted to copy, distribute and/or modify this document @@ -1769,7 +1772,7 @@ bash$ less foo.1 Disclaimer - No liability for the contents of this documents can be accepted. + No liability for the contents of this document can be accepted. Use the concepts, examples and other content at your own risk. diff --git a/LDP/howto/docbook/HOWTO-INDEX/miniChap.sgml b/LDP/howto/docbook/HOWTO-INDEX/miniChap.sgml index cb18df6a..fb36c656 100644 --- a/LDP/howto/docbook/HOWTO-INDEX/miniChap.sgml +++ b/LDP/howto/docbook/HOWTO-INDEX/miniChap.sgml @@ -352,7 +352,7 @@ DocBook-Install, DocBook Install mini-HOWTO -Updated: March 2001. +Updated: February 2002. A detailed practical guide for novices to quickly getting DocBook installed and processing SGML files into HTML, PostScript and PDF on a GNU/Linux system. diff --git a/LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml b/LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml index a3985639..78c63a5e 100644 --- a/LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml +++ b/LDP/howto/docbook/HOWTO-INDEX/miscSect.sgml @@ -23,7 +23,7 @@ DocBook-Install, DocBook Install mini-HOWTO -Updated: March 2001. +Updated: February 2002. A detailed practical guide for novices to quickly getting DocBook installed and processing SGML files into HTML, PostScript and PDF on a GNU/Linux system.