OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: [docbook-tc] Annotation element: Background/Use cases

This message is in regard to my open action item from last month's
meeting: to put provide a list of use cases to motivate discussion at
the next meeting about the proposal for an new Annotation element[1].

Use cases for the Annotation element

1. Acronym and Abbrev

Currently, DocBook lacks a standard way to associate an Acronym or
Abbrev with a "spelled out" phrase. A general Annotation element could
be used for this purpose, and (in my opinion) would be a better
solution that a specific "spelling out" element just for "expansions"
of Acronym and Abbrev. Note however, that TEI does provides an
specific Expan element[2] for this purpose.

Also note that spelled-out annotations need not necessarily be
rendered as "pop ups". Many documents in the XMLEurope 2001
proceedings[3] contatin acronyms and abbreviations linked to
spelled-out versions in a separate part of the same document in which
the acronyms and abbreviations occur (similar to the way in which
footnotes are usually rendered).
Discussion of the need to associate Acronyms with their spelled-out
versions in rendered HTML output originally came up in a message[4] on
docbooks-apps, which started a related discussion thread[5] on the TC list.

2. Footnotes vs. marginalia

This discussion first came in a thread[6] on the docbook list. In one
message[7] in that thread, Yann Dirson wrote:

  But both marginalia and footnotes are specific layouts for text that
  is, semantically, a note attached to some point in the text. Whether
  the rendering of this note shall produce one or the other layout
  object is a matter style.

  OTOH, I does raise a question about the <footnote> name - it is the
  name of a layout item, not of a semantic item, as already shown by
  the "end notes" rendering.

I believe the proposed Annotation element would be an appropriate
declarative/logical element name for marking up "a note attached to
some point in the text" -- a presentation-neutral name lacking the
implied processing expections of a "footnote" or "marginalia" element.


[1] http://lists.oasis-open.org/archives/docbook-tc/200204/msg00006.html

[2] TEI provides an Expan element:


    As well as "expan" and "abbr" attributes:

      The address is Southmoor <expan abbr="Rd">Road</expan>.
      The address is Southmoor <abbr expan="road">Rd</abbr>.

    But the limitation of that design is the expansion is limited to
    character data (or the abbrev is, depending on how you mark it up).

[3] One example:

[4] http://sources.redhat.com/ml/docbook-apps/2002-q1/msg00224.html

[5] http://lists.oasis-open.org/archives/docbook-tc/200201/msg00015.html

[6] http://lists.oasis-open.org/archives/docbook/200112/msg00113.html

[7] http://lists.oasis-open.org/archives/docbook/200112/msg00122.html

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC