[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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]