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

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

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


Subject: Inline term definitions


In books and other large documents, it's not uncommon to collect all 
of the important technical terms together in a glossary at the end
of the document.

In shorter documents, especially technical specifications, it's much
more common to simply highlight the definition inline. For example, in
the XML Recommendation, the definition of XML document is presented
in this way:

  [Definition: A data object is an *XML document* if it is well-formed,
  as defined in this specification. A well-formed XML document MAY in
  addition be valid if it meets certain further constraints.]

There are four important characteristics of this definition:

1. It is a delimited span of text.
2. It occurs in, and is rendered in, the running flow of text
3. It contains the defined term, but not necessarily at the very
   beginning or very end of the definition.
4. The word "valid" is, in fact, a cross reference to another inline
   term definition:

The W3C specification style is quite popular these days and if you
wanted to write one in DocBook, I think you'd be hard pressed to find
a good way of writing inline term definitions.

You could use phrase and abuse glossterm a little, I suppose:

  <phrase id="dt-xml-doc" role="definition">A data object is an
  <glossterm>XML document</glossterm> if it is well-formed, as defined
  in this specification. A well-formed XML document MAY in addition be
  <link linkend="dt-valid">valid<link> if it meets certain further
  constraints.</phrase>

But that doesn't seem like very satisfying markup for something that
presumably has so much semantic meaning you want to provide an
explicit declaration for it.

I propose that we add two new inlines to DocBook, termdef and a term
inside it:

  element termdef { common.idreq.attributes,
                    (db.all.inlines* & term?) }
  element term    { common.attributes,
                    attribute baseform { text },
                    db.all.inlines* }

I'd put termdef in the technical.inlines, explicitly excluded from
itself.

Comments?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Just because something doesn't do
http://www.oasis-open.org/docbook/ | what you planned it to do doesn't
Chair, DocBook Technical Committee | mean it's useless.--Thomas A.
                                   | Edison

PGP signature



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