refnamediv — The name, purpose, and classification of a reference page
refnamediv ::=
(refdescriptor
?,
refname
+, refpurpose
,
refclass
*)
A refnamediv
is the first mandatory section in
a refentry
. It is a peer to
refsynopsisdiv
and
refsect1
.
The elements in refnamediv
identify the topic
of the reference page (refdescriptor
or
refname
), provide a concise summary
(refpurpose
), and classify the page
(refclass
).
Formatted as a displayed block. A refnamediv
usually generates a section heading, in the same typographic style as
a refsect1
title
, called
“Name.”
The content of this section is traditionally the
refdescriptor
or refname
, and
the refpurpose
, separated by
an em dash.
The refclass
may be presented, or it may be
suppressed and used only to select a group of reference pages to
process. You might use the value of refclass
to
print all the reference pages appropriate to Solaris
UNIX, for example.
Formatting reference pages may require a fairly sophisticated
processing system. Much of the meta-information about a reference page
(its name, type, purpose, title, and classification) is stored in
wrappers near the beginning of the refentry
.
Common presentational features, such as titles and running headers, may require data from several of these wrappers plus some generated text. Other formatting often requires that these elements be reordered.