DocBook Annotations

[Norman Walsh <ndw@nwalsh.com>]

Annotations
-----------

This note proposes to add two elements to DocBook for the purpose of
annotations. The first, alt, is intended for simple, inline
annotations. Often these annotations are for accessibility. The
second, annotation, is intended for larger, block annotations.

These elements are "ubiquitous", appearing in almost all contexts
where text can occur.

alt
---

alt - a text-only annotation, often used for accessibility

An alternative text description of an element.

Processing expectations
-----------------------

An alt contains an alternative text description of an element, for example,
a text description of a small graphic, the expansion of an acronym, or
the title of a link. The alt element is never rendered in the normal flow
of the text.

Examples
--------

<para>The <acronym>OASIS<alt>Organization for the Standardization
of Structured Information Standards</alt></acronym> DocBook
<acronym>TC<alt>Technical Committee</alt></acronym> is responsible
for maintaining the DocBook schemas.</para>


annotation
----------

annotation - a comment about, or explanation of, an element

Processing expectations
-----------------------

An annotation contains a comment, explanation, or other description of
an element. Annotations are not intended to be rendered in the normal
flow of the text. In an interactive environment, they may be rendered
as links or popups. In a non-interactive environment such as
traditional printed media, they may be rendered as marginalia, end
notes, footnotes, or even be suppressed entirely.

Examples
--------

<para>Modern browsers display acronym expansions and link titles as
“<phrase>tool tips<annotation>
<title>Tool Tips</title>
<para>A tool tip is a word or short phrase displayed automatically by
an application when the user hovers the mouse over some component in the
user interface.</para></annotation></phrase>”.</para>

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Reason's last step is the
http://www.oasis-open.org/docbook/ | recognition that there are an
Chair, DocBook Technical Committee | infinite number of things which
                                   | are beyond it.-- Pascal

PGP signature