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-03 rbe @@ -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 + + + + <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) + + @@ -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. + + +
+ foo manpage, docbook refentry source (foo-ref.sgml) + +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<refentry> +<refentryinfo> + <date>2001-01-01</date> +</refentryinfo> +<refmeta> + <refentrytitle> + <application>foo</application> + </refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo>foo 1.0</refmiscinfo> +</refmeta> +<refnamediv> + <refname> + <application>foo</application> + </refname> + <refpurpose> + Does nothing useful. + </refpurpose> +</refnamediv> +<refsynopsisdiv> + <refsynopsisdivinfo> + <date>2001-01-01</date> + </refsynopsisdivinfo> + <cmdsynopsis> + <command>foo</command> +<arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg> +<arg><option>-d<replaceable class="parameter">n</replaceable></option></arg> +<arg rep="repeat"><replaceable class="parameter">file</replaceable></arg> + </cmdsynopsis> +</refsynopsisdiv> +<refsect1> + <refsect1info> + <date>2001-01-01</date> + </refsect1info> + <title>DESCRIPTION</title> + <para> + <command>foo</command> does nothing useful. + </para> +</refsect1> +<refsect1> + <title>OPTIONS</title> + <variablelist> + <varlistentry> + <term>-f <replaceable class="parameter">bar</replaceable></term> + <listitem> + <para> + Takes <filename>bar</filename> as it's run + control file. If this were a real program, + there might be more to say here about what + bar is and how it will be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>-d<replaceable class="parameter">n</replaceable></term> + <listitem> + <para> + Do something, where integer + <replaceable class="parameter">n</replaceable> + specifies how many times. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><replaceable class="parameter">file...</replaceable></term> + <listitem> + <para> + Processes the files in the order listed, + sending all output to stdout. + </para> + </listitem> + </varlistentry> + </variablelist> +</refsect1> +<refsect1> + <title>USAGE</title> + <para> + <command>foo</command> -f foo.conf -d2 foodata.foo + </para> +</refsect1> +<refsect1> + <title>CAVEATS</title> + <para> + Other programs named <command>foo</command> may exist and actually + do something! + </para> +</refsect1> +<refsect1> + <title>BUGS</title> + <para> + None. Program does nothing. + </para> +</refsect1> +<refsect1> + <title>AUTHOR</title> + <para> + <author> + <firstname>Foo</firstname> + <othername role="mi">E</othername> + <surname>Bar</surname> + <contrib>Original author</contrib> + </author> + </para> +</refsect1> +</refentry> + +
+ + +
+ Generating a manpage 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 +onsgmls:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported +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 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. + + -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 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. + + + + Manpage Sections + + + + Section + Purpose + + + + + man1 + User programs + + + man2 + System calls + + + man3 + Library functions and subroutines + + + man4 + Devices + + + man5 + File formats + + + man6 + Games + + + man7 + Miscellaneous + + + man8 + System administration + + + man9 + Kernel internal variables and functions + + + +
+ + + + 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