Using DocBook

DocBook Install mini-HOWTO
Prev |  | Next

# 4. Using DocBook

Now that everything is installed, it's time to test it out and see how to use openjade and the other tools.

Figure 1. Example DocBook SGML file - `test.sgml`

    <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

    <article lang="en">
    <articleinfo>
    	<title>This is a Test</title>

    	<author>
    		<firstname>John</firstname>
    		<surname>Doe</surname>
    		<othername role="mi">L</othername>
    		<affiliation>
    			<address>
    			<email>j.doe@jdoe dot com</email>
    			</address>
    		</affiliation>
    	</author>

    	<revhistory>
    		<revision>
    		<revnumber>v1.0</revnumber>
    		<date>2000-12-30</date>
    		<authorinitials>jld</authorinitials>
    		</revision>
    	</revhistory>

    	<abstract>
    	<para>
    	This is a test DocBook document.
    	</para>
    	</abstract>

    </articleinfo>

    <sect1 id="test1">
    <title>Test 1</title>
    <para>
    Test section 1.
    </para>
    	<sect2>
    	<title>Test 1.1</title>
    	<para>
    	Test section 1.1
    	</para>
    	</sect2>

    	<sect2>
    	<title>Test 1.2</title>
    	<para>
    	<screen>
    		-- Test section 1.2
    		openjade -t sgml -d $DSLFILE test.sgml
    	</screen>
    	</para>
    	</sect2>

    </sect1>

    <sect1 id="test2">
    <title>Test 2</title>
    <para>
    Test section 2.
    </para>

    	<sect2>
    	<title>Test 2.1</title>
    	<para>
    	Test section 2.1
    	</para>
    	</sect2>

    	<sect2>
    	<title>Test 2.2</title>
    	<para>
    	Test section 2.2
    	</para>
    	</sect2>

    </sect1>
    </article>

For a guide to DocBook and a reference of DocBook elements, see:

DocBook: The Definitive Guide. http://www.docbook.org/tdg/en/

## 4.1. Generating HTML

### 4.1.1. `docbook.dsl`

Figure 2. Generating HTML output using `docbook.dsl`

    bash$ ls -l
    total 4
    -rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
    bash$ echo $SGML_SHARE
    /usr/local/share/sgml
    bash$ openjade -t sgml -d $SGML_SHARE/dsssl/docbook/html/docbook.dsl test.sgml
    [snip - DTDDECL catalog entries are not supported, repeats]
    bash$ ls -l
    total 12
    -rw-r--r--   1 reaster  users        1885 Dec 31 17:34 t1.htm
    -rw-r--r--   1 reaster  users        1077 Dec 31 16:25 test.sgml
    -rw-r--r--   1 reaster  users        1544 Dec 31 17:34 x27.htm
    bash$

The warnings about `DTDDECL` can be ignored. They might be a little annoying, but these warnings are normal when using openjade. Other warnings and errors should be looked at and often indicate syntax errors that you should fix.

Two `htm` files are generated, one for each `<sect1>`. The filenames are not very descriptive. Section one appears on the same page as the article information. These are the results of using the default stylesheet that comes with the Modular DocBook Stylesheets, `docbook.dsl`.

Stylesheets can be customized to improve on these defaults. If you downloaded the 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 `<sect1>` is in its own file.

- Filenames are derived from ID attributes of the `<sect1>` elements.

- The file extension has changed to `html`.

- The `<screen>` elements are shaded.

Note how the `ldp.dsl` file is written in the command line: it has "`#html`" appended. `ldp.dsl` contains two `<STYLE-SPECIFICATION>` elements, one with ID="html" and another with ID="print". This selects the `html` style from within ldp.dsl. The DocBook DSSSL contains support for converting DocBook files into `html` and print formats. In Section 3.3, we copied `ldp.dsl` into both the print and `html` directories. When generating `html` output, the `html` style should be selected like above. When generating other types of files, such as `rtf` and `tex`, they fall under the print style and so the print style should be selected from `ldp.dsl`. The alternative is to comment out or delete the print or `html` style in the copy of `ldp.dsl` in the respective directory. If a `dsl` file has more than one style-spec in it and none is selected like in the example above, then the first style encountered in the file is selected. For `ldp.dsl`, the print style-spec is first in the file, so it gets selected by default. So in the example above, without appending "`#html`" when specifying `ldp.dsl` as the dsssl stylesheet, the "print" style-spec would be selected and used when generating the `html` output. It will work, but is intended for when selecting the `print/ldp.dsl` and the formatting will be different.

To learn more about how the stylesheet customization files are made, read the 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.0.46] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
    (test.aux)

    LaTeX Warning: There were undefined references.

     )
    Output written on test.dvi (3 pages, 34984 bytes).
    Transcript written on test.log.
    bash$ ls -l
    total 80
    -rw-r--r--   1 reaster  users         771 Dec 31 20:55 test.aux
    -rw-r--r--   1 reaster  users       34984 Dec 31 20:55 test.dvi
    -rw-r--r--   1 reaster  users        5072 Dec 31 20:55 test.log
    -rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    -rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
    bash$ jadetex test.tex
    This is TeX, Version 3.14159 (Web2C 7.3.1)
    (test.tex
    JadeTeX 1999/06/29: 2.7
    (/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
    (/usr/share/texmf/tex/jadetex/isoents.tex)
    Elements will be labelled
    Jade begin document sequence at 19
    (test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
    (/usr/share/texmf/tex/latex/base/ts1cmr.fd)
    (/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
    (/usr/share/texmf/tex/latex/hyperref/nameref.sty)
    (/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46]
    (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46] (test.aux) )
    Output written on test.dvi (3 pages, 34148 bytes).
    Transcript written on test.log.
    You have new mail in /var/spool/mail/reaster
    bash$ ls -l
    total 80
    -rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
    -rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
    -rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
    -rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    -rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
    bash$

The first time jadetex is run, warnings are printed. They can be ignored. Running it a second time, they do not appear again.

Figure 5. Running dvips to generate a PostScript (ps) file.

    bash$ ls -l
    total 80
    -rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
    -rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
    -rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
    -rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    -rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
    bash$ dvips test.dvi
    This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com)
    ' TeX output 2000.12.31:2058' -> test.ps
    <texc.pro><8r.enc><texps.pro><special.pro><color.pro>. [1] [2] [3]
    bash$ ls -l
    total 116
    -rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
    -rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
    -rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
    -rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
    -rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    -rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
    bash$

Figure 6. Running htmldoc to generate a PostScript (`ps`) file.

    bash$ ls -l
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
    bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml | htmldoc -f test-htmldoc.ps -
    bash$ ls -l
    -rw-r--r--   1 reaster  users        9050 Jan  1 00:44 test-htmldoc.ps
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    bash$

If the `ps` file doesn't appear as expected, it may be due to bugs in htmldoc. Look inside the ldp_print script if you want to use it to make `ps`.

## 4.4. Generating pdf

Figure 7. Running pdfjadetex to generate a Portable Document Format (`pdf`) file.

    bash$ ls -l
    -rw-r--r--   1 reaster  users         753 Dec 31 20:58 test.aux
    -rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
    -rw-r--r--   1 reaster  users        4433 Dec 31 20:58 test.log
    -rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
    -rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    -rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
    bash$ pdfjadetex test.tex
    This is pdfTeX, Version 3.14159-13d (Web2C 7.3.1)
    (test.tex[/usr/share/texmf/pdftex/config/pdftex.cfg]
    JadeTeX 1999/06/29: 2.7
    (/usr/share/texmf/tex/latex/psnfss/t1ptm.fd)
    (/usr/share/texmf/tex/jadetex/isoents.tex)
    Elements will be labelled
    Jade begin document sequence at 19
    (test.aux) (/usr/share/texmf/tex/latex/cyrillic/ot2cmr.fd)
    (/usr/share/texmf/tex/latex/base/ts1cmr.fd)
    (/usr/share/texmf/tex/latex/lucidabr/lmrhlcm.fd)
    (/usr/share/texmf/tex/context/base/supp-pdf.tex
    (/usr/share/texmf/tex/context/base/supp-mis.tex
    loading : Context Support Macros / Missing
    )
    loading : Context Support Macros / PDF
    ) (/usr/share/texmf/tex/latex/hyperref/nameref.sty)
    (/usr/share/texmf/tex/latex/psnfss/t1phv.fd) [1.0.46[/usr/share/texmf/dvips/con
    fig/pdftex.map]] (/usr/share/texmf/tex/latex/psnfss/t1pcr.fd) [2.0.46] [3.0.46]
     (test.aux) )<8r.enc>
    Output written on test.pdf (3 pages, 9912 bytes).
    Transcript written on test.log.
    bash$ ls -l
    total 128
    -rw-r--r--   1 reaster  users         753 Dec 31 21:13 test.aux
    -rw-r--r--   1 reaster  users       34148 Dec 31 20:58 test.dvi
    -rw-r--r--   1 reaster  users        5075 Dec 31 21:13 test.log
    -rw-r--r--   1 reaster  users        9912 Dec 31 21:13 test.pdf
    -rw-r--r--   1 reaster  users       34817 Dec 31 21:06 test.ps
    -rw-r--r--   1 reaster  users        4584 Dec 31 20:51 test.rtf
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    -rw-r--r--   1 reaster  users       18719 Dec 31 20:51 test.tex
    bash$
    bash$ pdfjadetex test.tex
    [snip]
    bash$ pdfjadetex test.tex
    [snip]

pdfjadetex must be run up to three times to resolve all internal references for things such as TOC page numbers.

Figure 8. Running htmldoc to generate a Portable Document Format (`pdf`) file.

    bash$ ls -l
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    bash$ export DSL_HTML=$SGML_SHARE/dsssl/docbook/html/ldp.dsl\#html
    bash$ openjade -t sgml -V nochunks -d $DSL_HTML test.sgml > test-htmldoc.htm
    bash$ ldp_print test-htmldoc.htm
    bash$ ls -l
    -rw-r--r--   1 reaster  users        9050 Jan  1 01:17 test-htmldoc.pdf
    -rw-r--r--   1 reaster  users        1143 Dec 31 18:18 test.sgml
    bash$

If enabled in the ldp_print script, this would generate a `ps` file also.

## 4.5. Using make

Repeating the commands to generate the output files is tedious. The make command works perfectly to automate the process.

Figure 9. Filename: `Makefile` - automates document generation.

    # Generates online and print versions of SGML source file.

    BASENAME=DocBook-Install

    # SGML source file.
    SGML_FILE=$(BASENAME).sgml

    # Stylesheets
    DSL_PRINT=$(SGML_SHARE)/dsssl/docbook/print/ldp.dsl\#print
    DSL_HTML=$(SGML_SHARE)/dsssl/docbook/html/ldp.dsl\#html

    # Generated files.
    HTML_FILE=index.html
    HTM_FILE=$(BASENAME).htm
    TEX_FILE=$(BASENAME).tex
    RTF_FILE=$(BASENAME).rtf
    PDF_FILE=$(BASENAME).pdf
    DVI_FILE=$(BASENAME).dvi
    PS_FILE=$(BASENAME).ps

    # Build rules.

    html: $(HTML_FILE)

    htm: $(HTM_FILE)

    tex: $(TEX_FILE)

    rtf: $(RTF_FILE)

    pdf: $(PDF_FILE)

    dvi: $(DVI_FILE)

    ps: $(PS_FILE)

    all: html htm tex rtf pdf dvi ps

    clean:
    	rm -f $(BASENAME).{htm,log,aux,ps,pdf,tex,dvi,rtf,fot}
    	rm -f *.html

    distclean: clean
    	rm -f $(BASENAME).tgz

    package:
    	rm -f $(BASENAME).tgz
    	tar -C .. -czf /tmp/$(BASENAME).tgz $(BASENAME)
    	mv /tmp/$(BASENAME).tgz .

    dist: clean package

    distall: all package

    # Compile rules.

    $(HTML_FILE): $(SGML_FILE)
    	openjade -t sgml -d $(DSL_HTML) $(SGML_FILE)

    $(HTM_FILE): $(SGML_FILE)
    	openjade -t sgml -V nochunks -d $(DSL_HTML) \
    	$(SGML_FILE) > $(HTM_FILE)

    $(TEX_FILE): $(SGML_FILE)
    	openjade -t tex -d $(DSL_PRINT) $(SGML_FILE)

    $(RTF_FILE): $(SGML_FILE)
    	openjade -t rtf -d $(DSL_PRINT) $(SGML_FILE)

    # [pdf]jadetex is run 3 times to resolve references.
    #$(PDF_FILE): $(TEX_FILE)
    #	pdfjadetex $(TEX_FILE)
    #	pdfjadetex $(TEX_FILE)
    #	pdfjadetex $(TEX_FILE)

    # This *should* work, but htmldoc has bugs ...
    #$(PDF_FILE): $(SGML_FILE)
    #	openjade -t sgml -V nochunks -d $(DSL_HTML) \
    #	$(SGML_FILE) | htmldoc -f $(PDF_FILE) -

    # Have to use ldp_print to work around htmldoc bugs
    # ldp_print can also do the ps file - see script
    $(PDF_FILE): $(HTM_FILE)
    	ldp_print $(HTM_FILE)

    $(DVI_FILE): $(TEX_FILE)
    	jadetex $(TEX_FILE)
    	jadetex $(TEX_FILE)
    	jadetex $(TEX_FILE)

    $(PS_FILE): $(DVI_FILE)
    	dvips $(DVI_FILE)

    #$(PS_FILE): $(SGML_FILE)
    #	openjade -t sgml -V nochunks -d $(DSL_HTML) \
    #	$(SGML_FILE) | htmldoc -f $(PS_FILE) -

Usage is just like for most projects:

Figure 10. Invoking make to run `Makefile`

    		-- generate html (default)
    		make
    		-- generate just pdf
    		make pdf
    		-- generate all files
    		make all
    		-- delete all generated files
    		make clean
    		-- create tgz distribution
    		-- with no generated files
    		make dist
    		-- create tgz distribution
    		-- containing all generated files
    		make distall

Notice the commented compile rules for `pdf` and `ps` which provide alternative means of generating those files.

## 4.6. Generating a man page

During the section on installing everything, we installed the perl version 5 module `SGMLS.pm`. Then we installed Docbook2X which provides the `spec.pl` files for transforming DocBook `<refentry>` documents into nroff (man page) format with sgmlspl.

An example Docbook `<refentry>` document, for the foo command, is given below.

Figure 11. foo command man page, docbook `<refentry>` source (`foo-ref.sgml`)

    <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
    <refentry>
    <refentryinfo>
    	<date>2001-01-01</date>
    </refentryinfo>
    <refmeta>
    	<refentrytitle>
    		<application>foo</application>
    	</refentrytitle>
    	<manvolnum>1</manvolnum>
    	<refmiscinfo>foo 1.0</refmiscinfo>
    </refmeta>
    <refnamediv>
    	<refname>
    		<application>foo</application>
    	</refname>
    	<refpurpose>
    	Does nothing useful.
    	</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
    	<refsynopsisdivinfo>
    		<date>2001-01-01</date>
    	</refsynopsisdivinfo>
    	<cmdsynopsis>
    	<command>foo</command>
    <arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
    <arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
    <arg rep="repeat"><replaceable class="parameter">file</replaceable></arg>
    	</cmdsynopsis>
    </refsynopsisdiv>
    <refsect1>
    	<refsect1info>
    		<date>2001-01-01</date>
    	</refsect1info>
    	<title>DESCRIPTION</title>
    	<para>
    	<command>foo</command> does nothing useful.
    	</para>
    </refsect1>
    <refsect1>
    	<title>OPTIONS</title>
    	<variablelist>
    	<varlistentry>
    		<term>-f <replaceable class="parameter">bar</replaceable></term>
    		<listitem>
    			<para>
    			Takes <filename>bar</filename> as it's run
    			control file. If this were a real program,
    			there might be more to say here about what
    			bar is and how it will be used.
    			</para>
    		</listitem>
    	</varlistentry>
    	<varlistentry>
    		<term>-d<replaceable class="parameter">n</replaceable></term>
    		<listitem>
    			<para>
    			Do something, where integer
    			<replaceable class="parameter">n</replaceable>
    			specifies how many times.
    			</para>
    		</listitem>
    	</varlistentry>
    	<varlistentry>
    		<term><replaceable class="parameter">file...</replaceable></term>
    		<listitem>
    			<para>
    			Processes the files in the order listed,
    			sending all output to stdout.
    			</para>
    		</listitem>
    	</varlistentry>
    	</variablelist>
    </refsect1>
    <refsect1>
    	<title>USAGE</title>
    	<para>
    	<command>foo</command> -f foo.conf -d2 foodata.foo
    	</para>
    </refsect1>
    <refsect1>
    	<title>CAVEATS</title>
    	<para>
    	Other programs named <command>foo</command> may exist and actually
    	do something!
    	</para>
    </refsect1>
    <refsect1>
    	<title>BUGS</title>
    	<para>
    	None.  Program does nothing.
    	</para>
    </refsect1>
    <refsect1>
    	<title>AUTHOR</title>
    	<para>
    	<author>
    		<firstname>Foo</firstname>
    		<othername role="mi">E</othername>
    		<surname>Bar</surname>
    		<contrib>Original author</contrib>
    	</author>
    	</para>
    </refsect1>
    </refentry>

Figure 12. Generating a man page with onsgmls, sgmlspl, and `docbook2man-spec.pl`

    bash$ ls -l
    -rw-r--r--   1 reaster  users        2434 Jan  3 03:51 foo-ref.sgml
    bash$ onsgmls foo-ref.sgml | sgmlspl $SGML_SHARE/docbook2X/docbook2man-spec.pl
    bash$ ls -l
    -rw-r--r--   1 reaster  users        2434 Jan  3 03:51 foo-ref.sgml
    -rw-r--r--   1 reaster  users        1129 Jan  3 04:03 foo.1
    -rw-r--r--   1 reaster  users           0 Jan  3 04:03 manpage.links
    -rw-r--r--   1 reaster  users           0 Jan  3 04:03 manpage.log
    -rw-r--r--   1 reaster  users          15 Jan  3 04:03 manpage.refs
    bash$ groff -mandoc -Tascii foo.1

    FOO(1)                                                     FOO(1)

    NAME
           foo - Does nothing useful.

    SYNOPSIS
           foo [ -f bar ]  [ -dn ]  [ file... ]

    DESCRIPTION
           foo does nothing useful.

    OPTIONS
           -f bar Takes  bar as its run control file. If this were a
                  real program, there might be more to say here about
                  what bar is and how it will be used.

           -dn    Do  something,  where  integer n specifies how many
                  times.

           file...
                  Processes the files in the  order  listed,  sending
                  all output to stdout.

    USAGE
           foo -f foo.conf -d2 foodata.foo

    CAVEATS
           Other  programs  named foo may exist and actually do some-
           thing!

    BUGS
           None. Program does nothing.

    AUTHOR
           Foo E Bar (Original author)

    [snip - several extra blank lines that man would not show]
    foo 1.0                     2001-01-01                          1
    bash$ groff -mandoc -Tascii foo.1 | less
    bash$ less foo.1

The man page, `foo.1`, is generated as a Section 1 page. The groff command is used to give a quick look at its formatted appearance.

To install this man page, it belongs in any `man/man1` directory, where the directory `man/` is added to `$MANPATH` in the environment. The standard location is `/usr/local/man/man1`. The standard sections in the man pages system are 1 though 9. Each is for holding specific catagories of documentation.

Table 1. Manual Pages Sections

Section | Purpose
--- | ---
man1 | User programs
man2 | System calls
man3 | Library functions and subroutines
man4 | Devices
man5 | File formats
man6 | Games
man7 | Miscellaneous
man8 | System administration
man9 | Kernel internal variables and functions

| 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 !

Prev | Home | Next
Install the Packages |  | Legal