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, go to:

DocBook: The Definitive Reference. http://www.docbook.org/tdg/html/docbook.html

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
openjade:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported
[snip - DTDDECL catalog entries are not supported, repeats]
openjade:/usr/local/share/sgml/docbook/4.1/catalog:22:0:W: DTDDECL catalog entries are not supported
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 jade. 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 DSSSL's Core Programming Language, as mentioned in Section 2.4.

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

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

Figure 11. 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>

Figure 12. 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 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                     2025-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.

Table 1. 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

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