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

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

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

<para>
<sgmltag>Title</sgmltag> is widely used in DocBook. It identifies the
titles of documents and parts of documents, and is the required
caption on formal objects.  It is also allowed as an optional
title or caption on many additional block elements.
</para>

<refsect2 id="dbreproc.title"><title>Processing expectations</title>
<para>
&format.block; Titles are often repeated in several locations,
for example, at the location where the object occurs, in the
<emphasis>table of contents</emphasis>, and in running headers and
footers.
</para>
<para>
DocBook does not offer any mechanism for indicating where a line
break should occur in long titles.  Titles are often repeated
and no single line break is likely to be correct in all of the
places where a title is used. Instead, you will have to rely on
your processing system to provide a mechanism, such as a
processing instruction, for identifing the location of forced
line breaks.
</para>

<para>
There are some contexts in which a <sgmltag>Title</sgmltag> can appear more than
once.  For example, it may appear in both <sgmltag>Book</sgmltag> and
<sgmltag>BookInfo</sgmltag>:

<screen>
&lt;book>&lt;title>Some Book Title&lt;/title>
&lt;bookinfo>
  &lt;title>Some Book Title&lt;/title>
  &lt;author>&lt;firstname>Some&lt;/firstname>&lt;surname>Author&lt;/surname>
    &lt;/author>
&lt;/bookinfo>
&hellip;
</screen>
</para>

<para>
In these contexts, if the <sgmltag>Title</sgmltag> occurs more than once,
<emphasis>the same</emphasis> title must be used in both places.
It is an error to use different titles, although DocBook has
no way to detect the error.
</para>
</refsect2>

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


&title.parents.gen;
&title.children.gen;
</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<varlistentry><term>pagenum</term>
<listitem>
<para>
<sgmltag class="attribute">PageNum</sgmltag> identifies the page on which this 
<sgmltag>Title</sgmltag> appears in some version of the printed document.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&title.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>

<informalexample role="example-source">
<programlisting>&title.example.1.txt;</programlisting>
</informalexample>

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

