The Basis: SGML

As stated earlier, the basis of this project will be XML. After having drafted a first hierarchical structure of the document², Open Source started to happen: Somebody emailed me informing me that there already exists a DTD for man pages. The DocBook[20] project includes a definition for a ``RefEntry'', which ``is an appropriate wrapper for any small unit of reference documentation describing a single topic''[21].

By using this definition, we can avoid having to re-invent the wheel: clearly, the world does not need yet another DTD for man pages. Since XML is a subset of the Standard Generalized Markup Language (SGML), we do not need to change the projects objective; in fact, this will make it the more portable and useful!

``DocBook'' itself is an SGML type definition used broadly in various Open Source: ``The Linux Documentation Project'' for example strongly recommends DocBook for writing a HOWTO. Various applications are able to read and write ``DocBook'' and conversion tools to other formats exist.

Before we go on, we need to understand how ``DocBook'' in general and RefEntry in particular work, so it is recommended that the readers follow the link in the references to familiarize themselves with SGML and DocBook. A careful study of the examples given in [21] let us almost instantaneously create a template from which we will deduce precise examples. See Listing .

A SGML Template

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

<!--
	``MakeMan'' SGML Template for a man page
	For more Information, please see http://mama.sourceforge.net

	$Author: Jan Schaumann <jschauma@netmeister.org> $
	$Id: man.template.sgml, v 0.2 2001/08/20 16:58:33 jschauma Exp $
-->

<refentry id="name">
	<refmeta>
		<refentrytitle>name.pl</refentrytitle>
		<manvolnum>section</manvolnum>
		<refmiscinfo class="date">Month Day, Year</refmiscinfo>
		<refmiscinfo class="source">Package</refmiscinfo>
		<refmiscinfo class="title">Title</refmiscinfo>
	</refmeta>

	<refnamediv>
		<refname>name</refname>
		<refpurpose>short description</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>name</command>
				<arg choice="opt" rep="repeat">OPTION</arg>
				<arg choice="req">FILE</arg>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>DESCRIPTION</title>
		<para>
			Write a long description in here.  Do not explain the details of
			the options, which will be below, but the general usage.
		</para>
		<para>
			<command>name</command> is usually written in bold when mentioned,
			<emphasis>References\</emphasis> in italics.
        </para>
	</refsect1>
	
	<refsect1>
		<title>USAGE</title>
		<para>
			Detailed usage.  If the program requires certain perparation
			before running, explain what needs to be done here.  Detailed
			explanation of unintuitive options may go here, as well.
		</para>
	</refsect1>
	
	<refsect1>
		<title>OPTIONS</title>
		<para>
			This program follows the usual GNU command line syntax,
            with long options starting with two dashes (`--'). A
            summary of the options supported by <command>name</command>
            is included below.
		</para>
		<variablelist>
			<varlistentry>
				<term>-h, --help</term>
				<listitem>
					<para>Show summary of options and exit.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>-v, --version</term>
				<listitem>
					<para>Show version information and exit.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</refsect1>
	
	<refsect1>
		<title>REQUIRES</title>
		<para>
			Prerequisites that need to be met for this program.
		</para>
	</refsect1>

	<refsect1>
		<title>VERSION</title>
		<para>
			Version Number
		</para>
	</refsect1>

	<refsect1>
		<title>BUGS</title>
		<para>
			Explain known bugs here.
		</para>
	</refsect1>

	<refsect1>
		<title>SEE ALSO</title>
		<para>
			<command>related(1)</command>
		</para>
		<para>
			<ulink url="http://somewhere.else">http://somewhere.else</ulink>
		</para>
	</refsect1>

	<refsect1>
		<title>AUTHOR</title>
		<para>
			<address>
				<firstname>First Name</firstname>
				<surname>Last Name</surname>
				<email>email@address.org</email>
			</address>
		</para>
	</refsect1>
</refentry>

Parsing SGML

Now that we have an SGML template, we can validate it. After all, the template won't do us any good if it is not valid SGML. nsgmls, part of the SG[24] package, is a command-line parser for SGML, which can be used to validate the example:

www:~/xml> nsgml -s man.template.sgml

If we do not get any error messages, we know that the file ``man.template.sgml'' contains valid SGML. For a detailed description of ``nsgmls'', please see nsgmls(1).