<refentry id="refdescriptor.element">
<?dbhtml filename="refdescriptor.html"?>
<refentryinfo>
<pubdate>$Date$</pubdate>
<releaseinfo>$Revision$</releaseinfo>
</refentryinfo>

<refmeta>
<indexterm><primary>elements</primary>
<secondary>refdescriptor</secondary></indexterm>
<refentrytitle>refdescriptor</refentrytitle>
<refmiscinfo>Element</refmiscinfo>
</refmeta>
<refnamediv>
<refname>refdescriptor</refname>
<refpurpose>&refdescriptor.purpose;</refpurpose>
</refnamediv>

&refdescriptor.synopsis.gen;
<refsect1 condition='ref.description'><title>Description</title>

<para>
Reference pages (<sgmltag>RefEntry</sgmltag>s) are usually identified
by a short, succinct topic name, such as the name of a function
or command.  The <sgmltag>RefName</sgmltag> (or one of the
<sgmltag>RefName</sgmltag>s, in the case of a reference page that has
several) is generally used as the topic name.  When none of the
<sgmltag>RefName</sgmltag>s is appropriate, <sgmltag>RefDescriptor</sgmltag>
is used to specify the topic name.
</para>

<para>
<sgmltag>RefDescriptor</sgmltag> is unnecessary when an appropriate
<sgmltag>RefName</sgmltag> can be selected automatically.  At least one
<sgmltag>RefName</sgmltag> is required, so <sgmltag>RefDescriptor</sgmltag> cannot
be used in place of a name, only in addition to it.
</para>

<refsect2><title>Processing expectations</title>
<para>
&format.context;
</para>
<para>
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 <sgmltag>RefEntry</sgmltag>.
</para>
<para>
Common presentational features, such as titles and running
heads, may require data from several of these wrappers plus
some generated text. Other formatting often requires that
these elements be reordered.
</para>
<para>
If a <sgmltag>RefDescriptor</sgmltag> is present, it should be used
for the short topic name.  This name usually appears in the running
header along with the <sgmltag>ManVolNum</sgmltag> in print media.
It may also appear in tables of contents and the index.
</para>
</refsect2>

<refsect2 role='fu' revision="4.0"><title>&FutureChanges;</title>
<para>
<!--do not index this occurance-->
&fu.interfacedefinition;
</para>
</refsect2>


&refdescriptor.parents.gen;
&refdescriptor.children.gen;
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&refdescriptor.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>

&refdescriptor.example.seealso.gen;
</refsect1>
</refentry>

