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

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

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

<para>
An <sgmltag>Area</sgmltag> is an empty element holding information about a
region in a graphic, program listing, or screen. 
</para>

<para>
The region is generally decorated with a number, symbol, or other
distinctive mark.  The mark is usually used as the label for the
<sgmltag>Callout</sgmltag> in a <sgmltag>CalloutList</sgmltag>, which allows the
reader to identify which callouts are associated with which regions.
The marks may be generated by the processing application from the
<sgmltag>Area</sgmltag>s, or it may be added by some other process.  (This is
an interchange issue. See <xref linkend="app-interchange"/>.)
</para>

<para>
For a complete description of callouts, see <sgmltag>Callout</sgmltag>.
</para>

<refsect2><title>Processing expectations</title>
<para>
&format.suppress; This element provides data for processing but it
is not expected to be rendered directly.
</para>

<para>
The processing expectations of <sgmltag>Callout</sgmltag>s are likely to deserve
special consideration for interchange.  See <xref linkend="app-interchange"/>.
</para>

<para>
The <sgmltag class='attribute'>Coords</sgmltag>, which are required, identify
the location of the region.  The coordinates are <acronym>CDATA</acronym>;
how they are interpreted depends on the 
<sgmltag class='attribute'>Units</sgmltag> specified:

<variablelist>
<varlistentry><term><sgmltag class='attvalue'>CALSPair</sgmltag></term>
<listitem>
<para>The coordinates are expressed using the semantics of the &CALS; 
graphic attributes.  The format of the coordinates is &ldquo;x1,y1 x2,y2&rdquo;.
This identifies a rectangle with the lower-left corner at (x1,y1) and
the upper-right corner at (x2,y2).  The X and Y coordinates are 
integers in the range 0 to 10000; they express a percentage of the
total distance from 0.00 to 100.00%. The lower-left corner is (0,0).
</para>
</listitem>
</varlistentry>
<varlistentry><term><sgmltag class='attvalue'>LineColumn</sgmltag></term>
<listitem>
<para>
The coordinates are expressed using lines and columns.
The format of the coordinates is &ldquo;line column.&rdquo;
In a graphic context, the meaning of this unit is unspecified.
</para>
</listitem>
</varlistentry>
<varlistentry><term><sgmltag class='attvalue'>LineRange</sgmltag></term>
<listitem>
<para>
The coordinates are expressed using lines.
The format of the coordinates is &ldquo;startingline endingline.&rdquo;
In a graphic context, the meaning of this unit is unspecified.
</para>
</listitem>
</varlistentry>
<varlistentry><term><sgmltag class='attvalue'>LineColumnPair</sgmltag></term>
<listitem>
<para>
The coordinates are expressed as a continuous flow of characters.
The format of the coordinates is &ldquo;line1 col1 line2 col2&rdquo;.
This identifies a flow of characters that begins at col1 of line1 and
extends to col2 of line2.  If line1 and line2 are different, then the
region includes all of the intervening lines (including text that
occurs before col1 and after col2).  In other words, this unit 
does not specify a rectangle.
In a graphic context, the meaning of this unit is unspecified.
</para>
</listitem>
</varlistentry>
<varlistentry><term><sgmltag class='attvalue'>OtherUnits</sgmltag></term>
<listitem>
<para>
If specified, then the <sgmltag class='attribute'>OtherUnits</sgmltag>
attribute is expected to identify the units in some 
implementation-specific way.
</para>
</listitem>
</varlistentry>
</variablelist>
The <sgmltag class='attribute'>Units</sgmltag> attribute is not required, if it
is not specified, the semantics of the coordinates must be inherited from
the surrounding <sgmltag>AreaSpec</sgmltag> or <sgmltag>AreaSet</sgmltag> element
or implied in
some implementation-specific manner.
</para>

<para>
In processing systems in which the mark is inserted automatically, the
<sgmltag class='attribute'>Label</sgmltag> attribute is provided as a mechanism
for specifying what the mark should be.
</para>

<para>
The author may point to any relevant information with <sgmltag
class='attribute'>Linkends</sgmltag>.  DocBook does not specify a semantic for
these links.  One possible use would be for providing a link back to
the appropriate <sgmltag>Callout</sgmltag> in an online environment.
</para>

</refsect2>


&area.parents.gen;
</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<varlistentry><term>coords</term>
<listitem>
<para>
<sgmltag class="attribute">Coords</sgmltag> provides the coordinates of the
<sgmltag>Area</sgmltag>. The coordinates should be interpreted using the
<sgmltag class="attribute">Units</sgmltag> (or <sgmltag class="attribute">OtherUnits</sgmltag>)
specified.
</para>
</listitem>
</varlistentry>
<varlistentry><term>label</term>
<listitem>
<para>
<sgmltag class='attribute'>Label</sgmltag> specifies an identifying number or string
that may be used in presentation. The <sgmltag>Area</sgmltag> label might be drawn
on top of the figure, for example, at the position indicated by
<sgmltag class='attribute'>Coords</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>linkends</term>
<listitem>
<para>
<sgmltag class="attribute">Linkends</sgmltag> points to the <sgmltag>Callout</sgmltag>(s) which refer
to this <sgmltag>Area</sgmltag>. (This provides bidirectional linking, which
may be useful in online presentation.)
</para>
</listitem>
</varlistentry>
<varlistentry><term>otherunits</term>
<listitem>
<para>
If none of the <sgmltag class="attribute">Units</sgmltag> are applicable, set
<sgmltag class="attribute">Units</sgmltag> to <literal>Other</literal> and set 
<sgmltag class="attribute">OtherUnits</sgmltag> to some application-specific
description of the desired units.
</para>
</listitem>
</varlistentry>
<varlistentry><term>units</term>
<listitem>
<para>
<sgmltag class="attribute">Units</sgmltag> indicate how the specified
<sgmltag class="attribute">Coords</sgmltag> are to be interpreted. The default
units vary according to the type of callout specified; <literal>CALSPair</literal>
for graphics and <literal>LineColumn</literal> for line-oriented elements.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Examples</title>

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

