From 505c50f61f74d16e51ea941845d0a9dcc9a4b816 Mon Sep 17 00:00:00 2001
From: gferg <>
Date: Wed, 3 Jan 2001 15:19:49 +0000
Subject: [PATCH] updated
---
LDP/howto/docbook/DocBook-Install.sgml | 407 +++++++++++++++++++++++--
1 file changed, 387 insertions(+), 20 deletions(-)
diff --git a/LDP/howto/docbook/DocBook-Install.sgml b/LDP/howto/docbook/DocBook-Install.sgml
index c11f2b31..6cda6702 100644
--- a/LDP/howto/docbook/DocBook-Install.sgml
+++ b/LDP/howto/docbook/DocBook-Install.sgml
@@ -18,8 +18,8 @@
- v1.1
- 2001-01-01
+ v1.2
+ 2001-01-03rbe
@@ -61,13 +61,20 @@
DocBook tags are used to create books and articles. Within these
documents, the <chapter>, <sect1>, and <para>
tags are used. DocBook SGML files are stored in text files with a sgml
- or gml suffix. When processed, a single DocBook SGML file can
+ or gml suffix.
+
+
+ When processed, a single DocBook SGML file can
output html, pdf, ps, txt and other formats for both
online and printed publication. The processing is governed by
stylesheets that can automatically generate a table of contents,
page numbering, chapter & section numbering, and other
features.
+
+ DocBook is also designed for authoring unix manpages using
+ <refentry>.
+
@@ -134,13 +141,26 @@
- htmldoc
+ HTMLdoc
- HTMLdoc is a free program for converting a website into a
+ 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 manpages. 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.
+
+
+
@@ -241,7 +261,7 @@ In this section, we will locate and download the software on the Internet.
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
+ 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
@@ -265,7 +285,8 @@ In this section, we will locate and download the software on the Internet.
Sgmltools-lite
- Sgmltools is a frontend for openjade, jadetex, pdfjadex, dvips, and other programs. It
+ Sgmltools 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:
@@ -282,10 +303,22 @@ In this section, we will locate and download the software on the Internet.
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.
+ both and see which turns out best for a particular docbook file. See quick links
+ below for download 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
+ 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/
+ Quick Download Links
@@ -335,11 +368,23 @@ In this section, we will locate and download the software on the Internet.
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
+
+
+
+ http://www.cpan.org/authors/id/DMEGG/SGMLSpm-1.03ii.tar.gz
+
+ SGMLS.pm 1.03ii at CPAN. (sgmlspl)
+
+
+
+
+ http://download.sourceforge.net/docbook2x/docbook2X-0.6.0.tar.gz
+
+ DocBook2X 0.6.0 (provides docbook2man-spec.pl for use with sgmlspl above)
+
+
@@ -774,6 +819,63 @@ In this section, we will locate and download the software on the Internet.
+
+ DocBook2X and SGMLS.pm (sgmlspl)
+
+ 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.
+
+ 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.
+
+
+
+
+ docbook2X (docbook2man-spec.pl)
+
+ DocBook2X contains no program to compile or install,
+ though it has some scripts you might want to look at,
+ so all there is to do is unpack it somwhere.
+
+ cd /usr/local/share/sgml
+ tar -xvzf ~/docbook2X-0.6.0.tar.gz
+ cd docbook2X
+
+ In the unpacked directory is the docbook2man-spec.pl and
+ a patch file for it that corrects a few things.
+ Applying the patch is optional but recommended.
+
+ patch docbook2man-spec.pl docbook2man-spec.pl.patch
+
+ Later, in Using DocBook, you will see how to use
+ sgmlspl and docbook2man-spec.pl to generate a manpage from
+ a refentry docbook document.
+
+
+
+
+
$SGML_CATALOG_FILES
@@ -917,6 +1019,7 @@ Test section 2.
For a guide to DocBook and a reference of DocBook elements, go to:
+
DocBook: The Definitive Reference
@@ -1215,10 +1318,7 @@ bash$ ls -l
bash$
- Notice the html filenames. This naming is good in this situation
- because when running htmldoc, the *.html sorts them in the
- proper order. Notice also, the use of htmldoc.dsl, the
- customized dsssl stylesheet for this task.
+ Notice the use of htmldoc.dsl, the customized dsssl stylesheet for this task.
@@ -1286,7 +1386,9 @@ bash$ ls -l
bash$
- This is just like using htmldoc to make a pdf.
+ This is nearly the same command as used to generated a ps file with htmldoc but
+ with just a different filename. Htmldoc understands what you want based on
+ the filename extension.
@@ -1349,7 +1451,8 @@ distclean: clean
package:
rm -f $(BASENAME).tgz
- tar -C .. -czf $(BASENAME).tgz $(BASENAME)
+ tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
+ mv /tmp/$(BASENAME).tgz .
dist: clean package
@@ -1410,15 +1513,279 @@ $(PS_FILE): $(DVI_FILE)
Notice the commented compile rules for pdf and ps which
provide alternative means of generating those files.
+
-
- That's all, folks!
-
+
+ Generating a manpage
+
+ 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.
+
+
+ An example Docbook RefEntry document, for the
+ foo command, is given below.
+
+
+
+
+
+
+
+
+
+ The manpage, 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
+ in the environment. The standard location is
+ /usr/local/man/man1.
+ The standard sections in the manpages system are 1 though 9.
+ Each is for holding specific catagories of documentation.
+
+
+
+
+
+
+ The source file for a manpage, 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!
+
+
+
+
+ Have fun!
+
+
+
Copyright