This article describes the image element from a DITA XML perspective and also identiifes best practices for using images in a Vasont CMS\Oxygen environment.
Note: This article is intended as guidelines to the development of an image usage best practice; it does not supercede the articles written in this section (Formatting, Scale Attribute, Size Attribute). Those articles are valid for current state file system usage.
About the <image> element
Reference: http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/image.html
The image element is used as a container for artwork (graphics, screen captures, image files) in a DITA topic. An image element is contained by a mojority of elements in task, concept, reference, and topic types. Most notably it can be contained within a the body/conbody/taskbody/refbody elements in general and specifically within a shortdesc, p, note, ul, cmd (step), info, et al. Generally you can place an image element almost anywhere.
The element suppports 8 attributes; only one of which "href" is required. Here is an example image element:
<image href="bike.gif" placement="break"><alt>Two-wheeled bicycle</alt></image>
Note the alt attribute is supported but the best practice is to use the alt element.
<image href="bike.gif" placement="break" alt="Two-wheeled bicycle"/> <image href="bike.gif" placement="break"><alt>Two-wheeled bicycle</alt></image>
Note the placement attribute, while optional, is very important in terms of the presentation of the image.
Attributes
| Attribute | Description |
|---|---|
| href | The relative path or URL to the image |
| longdescref | A reference to a textual description of the graphic or object. This attribute supports creating accessible content. |
| height | Indicates the vertical dimension for the resulting image display and scales the image to the specified size. Real number and unit of measure pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). |
| width | Indicates the horizontal dimension for the resulting image display and scales the image to the specified size. Real number and unit of measure pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). |
| align | Controls the horizontal alignment of an image when placement is specified as "break." Allowable values (processor-validated) are: left, right, center, and current. |
| scale | Specifies a percentage 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. |
| placement | Indicates whether an image should be displayed inline or separated from the surrounding text. The processing default is inline. Allowable values are: inline or break. |
| 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. |
About the <imagemap> element
The imagemap element is used to define "hotspots" in an image and make those hyperlinks. We don't currently have a use case for this element but are not prevented from implementing the element.
Captions
There is no literal <caption> element defined in the DITA schema. If an author desires a caption associated with an image, the best practice is to use a <fig> element.
The figure (<fig>) element is used to display context (sometimes called an "exhibit") with an optional title for a wide variety of content. Most commonly, the figure element contains an image element (a graphic or artwork), but it can contain several kinds of text objects as well. A title is placed inside the figure element to provide a caption to describe the content, as follows.
<fig>
<title>This is the caption for the image.</title>
<image/>
</fig>