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

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

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

<para>
A <quote>subject</quote> categorizes or describes the topic of a
document, or section of a document. In DocBook, a <sgmltag>Subject</sgmltag>
is defined by the <sgmltag>SubjectTerm</sgmltag>s that it contains.
</para>
<para>
Subject terms should be drawn from a controlled vocabulary, such
as the <emphasis>Library of Congress Subject Headings</emphasis>. If an outside
vocabulary is not appropriate, a local or institutional subject set
should be created.
</para>
<para>
The advantage of a controlled vocabulary is that it places the document
into a known subject space. Searching the subject space with a particular
subject term will find <emphasis>all</emphasis> of the documents that claim
to have that subject. There's no need to worry about terms that are
synonymous with the search item, or homophones of the search term.
</para>
<para>
All of the <sgmltag>SubjectTerm</sgmltag>s in a <sgmltag>Subject</sgmltag> should
describe the same subject, and be from the <emphasis>same controlled
vocabulary</emphasis>.
</para>

<refsect2><title>Processing expectations</title>
<para>
&format.context; Subjects are rarely displayed to a reader. Usually, they
are reserved for searching and retrieval purposes.
</para>
<para>
Unlike <sgmltag>Keyword</sgmltag>s, which may be chosen freely, 
subject terms should come from a controlled vocabulary.
</para>
<para>
In order to assure that typographic or other errors are not introduced
into the subject terms, they should be compared against the controlled
vocabulary by an external process.
</para>
</refsect2>


&subject.parents.gen;
&subject.children.gen;
</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<varlistentry><term>weight</term>
<listitem>
<para>
<sgmltag class="attribute">Weight</sgmltag> specifies a ranking for this 
<sgmltag>Subject</sgmltag> relative to other subjects in the same set.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&subject.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>

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

