3.2.2.17 <image>

Use the <image> element to include artwork or images in a DITA
topic.

The <image> element has an optional @placement
attribute that indicates whether the included graphic or artwork is rendered inline (a button or icon) or on a separate line for a larger image.
There also are attributes that indicate the size to which the included graphic or artwork
is scaled.

An image element specifies an @href attribute, a @keyref
attribute, or both. When both @keyref and @href are
specified, the @href is used as a fallback when the key reference cannot be
resolved. The image addressed by the @keyref or @href is
brought into the main flow of the content as rendered.

To make the intent of the image more accessible for users using screen readers or text-only
readers, authors should include a description of the image content in the <alt> element.

Content models

See appendix for information about this element in OASIS document type shells.

Attributes

Provides a reference to the image. See The href attribute for detailed information on supported values and
processing implications.

@scope

The @scope attribute identifies the
closeness of the relationship between the current
document and the target resource. Allowable values
are local, peer, external, and -dita-use-conref-target. See The scope attribute for more
information on values.

@height

Indicates the vertical dimension for the resulting image
display. If necessary, the image SHOULD be scaled to the specified size.
The
value of this attribute is a real number (expressed in
decimal notation) optionally followed by a unit of measure
from the set of pc, pt, px, in, cm, mm, em (picas, points,
pixels, inches, centimeters, millimeters, and ems
respectively). The default unit is px (pixels). Possible
values include: "5", "5in", and "10.5cm". If a height value is specified and no width value
is specified, the width SHOULD be scaled by
the same factor as the height. If both a height value and width
value are specified, implementations MAY ignore one of the
two values when they are unable to scale to each direction
using different factors.

@width

Indicates the horizontal dimension for the resulting
image display. If necessary, the image SHOULD be scaled to the specified size.
The
value of this attribute is a real number (expressed in
decimal notation) optionally followed by a unit of measure
from the set of pc, pt, px, in, cm, mm, em (picas, points,
pixels, inches, centimeters, millimeters, and ems
respectively). The default unit is px (pixels). Possible
values include: "5", "5in", and "10.5cm". If a width value is specified and no height value
is specified, the height SHOULD be scaled by
the same factor as the width. If both a height value and width
value are specified, implementations MAY ignore one of the
two values when they are unable to scale to each direction
using different factors.

@align

Controls the horizontal alignment of an image when
placement is specified as "break". Common
values include left,
right, and
center.

@scale

Specifies a percentage as an unsigned integer by which
to scale the image in the absence of any specified
image height or width; a value of 100 implies that
the image should be presented at its intrinsic size.
If a value has been specified for this image's
@height or @width
attribute (or both), the @scale
attribute is ignored.

It is an error if the value
of this attribute is not an unsigned integer. In
this case, the implementation might give an error
message and might
recover by ignoring this attribute.

@scalefit

Allow an image to be scaled up or down to fit within
available space. Allowable values are yes, no, and
-dita-use-conref-target. If, for a given
image, any one of @height,
@width, or @scale
is specified, those attributes determine the graphic
size, and any setting of @scalefit
is ignored. If none of those attributes are
specified and scalefit="yes", then
the image is scaled (the same factor in both
dimensions) so that the graphic will just fit within
the available height or width (whichever is more
constraining).

The available width would be the
prevailing column (or table cell) width - that is,
the width a paragraph of text would have if the
graphic were a paragraph instead. The available
height is implementation dependent, but if
feasible, it is suggested to be the page (or table
cell) height or some other reasonable value.

@placement

Indicates whether an image should be displayed inline or
separated from the surrounding text. The default is
inline. Allowable values are: inline, break, or and
-dita-use-conref-target.

@alt(DEPRECATED)

Alternative text that describes the image to provide accessibility to page readers or
provides a text description when an image cannot be displayed by the user's
software. The @alt attribute is deprecated; use the alt element instead.

@longdescref(DEPRECATED)

A reference to a textual description of the graphic or
object. This attribute supports creating accessible
content. See The href attribute for detailed information on supported values and
processing implications. For examples of how
this attribute is used in output, see this topic
on long descriptions.
NOTE: This attribute is deprecated in favor of the
longdescref
subelement to this element.