Schema Documentation - Book Profile
version 1.0

The block variant of the description element

On this page:

The description element represents an alternate accessible description of an image, video, table, etc.

The Block variant is an adaption for use embedding descriptions in other Block-layer elements and for grouping descriptions in Section-layer elements (for example, in the document head , where they can be referenced globally).

The description element can either contain the text content of the description or reference an external file in which it can be found via the xlink:href attribute. It is not permitted to mix both methods, however.

To ensure the description can be rendered, the description element must not include descendant elements and attributes that require a description.

Usage details available in the Usage Details section.

Usage Example

<object src="mouse.png" desc="mouse-desc" />
<description xml:id="mouse-desc" by="republisher" role="content">
    <p>...</p>
</description>

Allowed parents

address, annotation, m:annotation-xml, aside (block variant), aside (toc variant), backcover, block, caption, description, entry (bibliography variant), entry (glossary variant), flaps, frontcover, head, item, d:longdesc, note (block variant), note (phrase variant), object, sel:otherwise, quote, section, d:simplifiedLanguageDescription, td, th, d:tour and sel:when

Allowed children

This element may contain text.

This element may contain the following children: abbr, address (block variant), address (phrase variant), annoref, annotation (block variant), annotation (phrase variant), aside, block, caption, char, citation (block variant), citation (phrase variant), code (block variant), code (phrase variant), d, definition, description, emph (phrase variant), emph (text variant), expansion, hd, rend:linebreak, list, ln, name, note (block variant), note (phrase variant), noteref, num, object (block variant), object (phrase variant), object (text variant), p, quote (block variant), quote (phrase variant), ref, s, span (phrase variant), span (text variant), sub, sup, table, term, time, transition, verse and w

Content model and additional requirements

optional attributes: @about, @by, @class, @content, @datatype, @desc, @its:dir, @its:translate, @property, @ref, @rel, @resource, @rev, @role, @sel:selid, @typeof,
@xlink:href
, @xml:base, @xml:id, @xml:lang and @xml:space
optionally
@xlink:href
an optional @xlink:type
an optional @xlink:title
an optional @xlink:show
an optional @xlink:actuate
a choice of
either no content
or
one or more of
any of the 17 elements: address, annotation, aside, block, caption, citation, code, description, hd, list, note, object, p, quote, table, transition and verse
or
one or more of
a choice of
either one of the 31 elements: abbr, address, annoref, annotation, char, citation, code, d, definition, emph, emph, expansion, ln, name, note, noteref, num, object, object, quote, ref, rend:linebreak, s, span, span, sub, sup, term, time, w or w
or text
end of choice
end of choice
Note that in addition to restrictions presented in the content model above, use of this element must also respect the following requirements:
  • The description element must either contain text data or point to an external resource using the xlink:href attribute.
  • The description element must not contain text data and also point to an external resource using the xlink:href attribute.
  • The description element must not contain descendant description elements.
  • The description element must not contain descendant object elements.
  • The description element must not contain descendant table elements.
  • The description element must not contain descendant elements from the MathML feature grammar.
  • Every description element must be referenced by at least one element in the document.
  • The object element may contain only one child description.
  • description elements cannot be nested inside the children of an object element.
  • A single description element must be the only child of an object element when used.
Such requirements take precedence over any conflicting statements in the content model or in the lists above of allowed children and parents.

Variants

This element exists in 3 variants. The other 2 variants are:

Namespace

http://www.daisy.org/ns/z3998/authoring/

Usage Details

The description element can be used in one of two ways:

  1. as a direct container for the descriptive text:

    <description by="republisher" xml:id="mouse-desc">
            <p>A picture of a small, grey mouse.</p>
</description>

  2. as a pointer to an external description:

    <description by="republisher" xml:id="mouse-desc2" xlink:href="mouse-desc.xml" />

An element may point to more than one description so long as each description has a unique role attribute value.

A single description element can be the child of an object to provide its accessible description. In this case, an implicit association is made between the two elements (i.e., the desc attribute does not need to be used: 

            <object src="mouse.png">
                <description by="republisher" xlink:href="mouse-desc.xml" />
            </object>

If an object element contains text or other elements as its children, an implicit description is assumed. In the absence of the container element, the object's children represent an implied content description added by an author. The following examples are functionally identical, but highlight the various implicit elements and attributes: 

            <object src="mouse.png">
                <p>A small mouse...</p>
            </object>
            
            <object src="mouse.png">
                <description>
                    <p>A small mouse...</p>
                </description>
            </object>
            
            <object src="mouse.png">
                <description by="author">
                    <p>A small mouse...</p>
                </description>
            </object>
            
            <object src="mouse.png">
                <description by="author" role="content">
                    <p>A small mouse...</p>
                </description>
            </object>
            
            <object src="mouse.png" desc="mouse-desc">
                <description xml:id="mouse-descrip" by="author" role="content">
                    <p>A small mouse...</p>
                </description>
            </object>

The Content Selection feature can additionally be used to tailor the type of description to the output format being generated: 

            <sel:select>
                <sel:when expr="target:format('BRAILLE')">
                    <description sel:selid="mouse-desc" by="republisher" xlink:href="mouse-braille-desc.xml" />
                </sel:when>
                <sel:otherwise>
                    <description sel:selid="mouse-desc" by="republisher" xlink:href="mouse-desc.xml" />
                </sel:otherwise>
            </sel:select>

As each condition in the sel:select contains the same description element but corresponding to a different output, they cannot each have the same xml:id. The sel:selid attribute is instead attached to each description. After the select condition has been evaluated, the remaining sel:selid is converted back to an xml:id.