| DocBook: The Definitive Guide 2.0.17 (Alpha)

# area

$Revision: 3046 $

$Date: 2003-08-17 10:31:00 -0400 (Sun, 17 Aug 2003) $

area — A region defined for a `Callout` in a graphic or code example

## Synopsis

### Content Model

    area ::=
    EMPTY

### Attributes

Common attributes

Name | Type | Default
coords | CDATA | Required
otherunits | NMTOKEN | None
label | CDATA | None
units |
Enumeration:
calspair
linecolumn
linecolumnpair
linerange
other
| None
linkends | IDREFS | None

## Description

An `Area` is an empty element holding information about a region in a graphic, program listing, or screen.

The region is generally decorated with a number, symbol, or other distinctive mark. The mark is usually used as the label for the `Callout` in a `CalloutList`, which allows the reader to identify which callouts are associated with which regions. The marks may be generated by the processing application from the `Area`s, or it may be added by some other process. (This is an interchange issue. See Appendix F, Interchanging DocBook Documents.)

For a complete description of callouts, see `Callout`.

### Processing expectations

Suppressed. This element provides data for processing but it is not expected to be rendered directly.

The processing expectations of `Callout`s are likely to deserve special consideration for interchange. See Appendix F, Interchanging DocBook Documents.

The `Coords`, which are required, identify the location of the region. The coordinates are CDATA; how they are interpreted depends on the `Units` specified:

`CALSPair`

  The coordinates are expressed using the semantics of the CALS graphic attributes. The format of the coordinates is “x1,y1 x2,y2”. 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).

`LineColumn`

  The coordinates are expressed using lines and columns. The format of the coordinates is “line column.” In a graphic context, the meaning of this unit is unspecified.

`LineRange`

  The coordinates are expressed using lines. The format of the coordinates is “startingline endingline.” In a graphic context, the meaning of this unit is unspecified.

`LineColumnPair`

  The coordinates are expressed as a continuous flow of characters. The format of the coordinates is “line1 col1 line2 col2”. 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.

`OtherUnits`

  If specified, then the `OtherUnits` attribute is expected to identify the units in some implementation-specific way.

The `Units` attribute is not required, if it is not specified, the semantics of the coordinates must be inherited from the surrounding `AreaSpec` or `AreaSet` element or implied in some implementation-specific manner.

In processing systems in which the mark is inserted automatically, the `Label` attribute is provided as a mechanism for specifying what the mark should be.

The author may point to any relevant information with `Linkends`. DocBook does not specify a semantic for these links. One possible use would be for providing a link back to the appropriate `Callout` in an online environment.

### Parents

These elements contain area: `areaset`, `areaspec`.

## Attributes

coords

  `Coords` provides the coordinates of the `Area`. The coordinates should be interpreted using the `Units` (or `OtherUnits`) specified.

label

  `Label` specifies an identifying number or string that may be used in presentation. The `Area` label might be drawn on top of the figure, for example, at the position indicated by `Coords`.

linkends

  `Linkends` points to the `Callout`(s) which refer to this `Area`. (This provides bidirectional linking, which may be useful in online presentation.)

otherunits

  If none of the `Units` are applicable, set `Units` to `Other` and set `OtherUnits` to some application-specific description of the desired units.

units

  `Units` indicate how the specified `Coords` are to be interpreted. The default units vary according to the type of callout specified; `CALSPair` for graphics and `LineColumn` for line-oriented elements.

## Examples

For examples, see `graphicco`, `mediaobjectco`, `programlistingco`.

application |  | areaset

Copyright © 1999, 2000, 2001, 2002, 2003 O'Reilly & Associates, Inc. All rights reserved.