The reference page or manual page in DocBook was inspired by, and in fact designed to reproduce, the common UNIX “manpage” concept. (We use the word “page” loosely here to mean a document of variable length containing reference material on a specific topic.) DocBook is rich in markup tailored for such documents, which often vary greatly in content, however well structured they may be. To reflect both the structure and the variability of such texts, DocBook specifies that reference pages have a strict sequence of parts, even though several of them are actually optional.
Of the following sequence of elements that may appear in a
refentry
, only two are obligatory:
refnamediv
and either refsect1
or refsection
.
info
The info
element
contains meta-information about the reference page (which should not
be confused with refmeta
, which
it precedes). It marks up information about the author of the
document, or the product to which it pertains, or the document’s
revision history, or other such information.
refmeta
refmeta
contains a
title for the reference page (which may be inferred if the
refmeta
element is not present) and an indication
of the volume number in which this reference page occurs. The
manvolnum
is a very
UNIX-centric concept. In traditional
UNIX documentation, the subject of a reference
page is typically identified by name and volume number; this allows
you to distinguish between the uname command,
“uname(1)” in volume 1 of the documentation, and the
uname
function, “uname(3)” in
volume 3.
Additional information of this sort, such as
conformance or vendor information specific to the particular
environment you are working in, may be stored in
refmiscinfo
.
refnamediv
The first obligatory element is refnamediv
, which is a wrapper for
information about whatever you’re documenting, rather than the
document itself. It can begin with a refdescriptor
if several items are being
documented as a group and the group has a name. The refnamediv
must contain at least one
refname
, that is, the name of
whatever you’re documenting, and a single short statement that sums
up the use or function of the item(s) at a glance: its refpurpose
. Also available is the refclass
, intended to detail the operating
system configurations that the software element in question
supports.
If no refentrytitle
is given in the
refmeta
, the title of the reference page is the
refdescriptor
, if present, or the first
refname
.
refsynopsisdiv
A refsynopsisdiv
is
intended to provide a quick synopsis of the topic covered by the
reference page. For commands, this is generally a syntax summary of
the command, and for functions, the function prototype, but other
options are possible. A title
is
allowed, but not required, presumably because the application that
processes reference pages will generate the appropriate title if it
is not given. In traditional UNIX documentation,
its title is always “Synopsis.”
refsect1
…refsect3
Within refentry
s, there are only
three levels of sectioning elements: refsect1
,
refsect2
, and refsect3
.
refsection
As with sect1
,
sect2
, etc., there is a recursive version of the
reference section elements:
refsection
.
Example 2-4 shows the beginning of a refentry
that illustrates one possible reference
page.
Example 2-4. A sample reference page
<refentry xml:id="printf"> <refmeta> <refentrytitle>printf</refentrytitle> <manvolnum>3S</manvolnum> </refmeta> <refnamediv> <refname>printf</refname> <refname>fprintf</refname> <refname>sprintf</refname> <refpurpose>print formatted output</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> <funcsynopsisinfo> #include <stdio.h> </funcsynopsisinfo> <funcprototype> <funcdef>int <function>printf</function></funcdef> <paramdef>const char *<parameter>format</parameter></paramdef> <varargs/> </funcprototype> <funcprototype> <funcdef>int <function>fprintf</function></funcdef> <paramdef>FILE *<parameter>strm</parameter></paramdef> <paramdef>const char *<parameter>format</parameter></paramdef> <varargs/> </funcprototype> <funcprototype> <funcdef>int <function>sprintf</function></funcdef> <paramdef>char *<parameter>s</parameter></paramdef> <paramdef>const char *<parameter>format</parameter></paramdef> <varargs/> </funcprototype> </funcsynopsis> </refsynopsisdiv> <refsect1><title>Description</title> <para><indexterm><primary>functions</primary> <secondary>printf</secondary></indexterm> <indexterm><primary>printing function</primary></indexterm> <function>printf</function> places output on the standard output stream stdout. </para> </refsect1> </refentry>