New approach to Terms and Defintions?

[thomasheritage]

Context

My understanding is:

• moving to HTML publication is an opportunity to improve the design of SMPTE standards
• it is not essential to follow all ISO directives or SMPTE AG 16

Therefore we don't need to replicate the traditional approach to Terms and Definitions (see #117)

Idea for consideration

Would an approach like in W3C standards (created with Bikeshed or ReSpec) be helpful?

So, perhaps we would have:

• A Terms and Definitions section in which all the author writes is a list of terms that are defined in other documents but are used in this document
  • Terms are listed with sources but no definitions or notes
  • I assume we wouldn't implement all the auto cross-document linking that Bikeshed and ReSpec do...
• All terms defined by the document itself are defined in-line
  • Therefore there is no need for special Terms and Definitions syntax (and so no need for "notes to entry" etc)
  • Of course the author can always create a custom "definitions important for my topic" section to put these definitions in, should that be sensible for the document being authored
• When rendered, the Terms and Definitions section is auto-populated with the list of externally defined terms as well as a list of all the terms (as links) defined in the document itself
  • So, what is called an "index" in a W3C standard I believe e.g. per https://www.w3.org/TR/webvtt/#index
  • We might want to call it an "index" in SMPTE standards as well, and perhaps move it to the end of the document

This seems helpful because at the moment (in the SMPTE html-pub as currently implemented):

• The Terms and Definitions section lists only some of the terms and definitions... (i.e. those defined in-line are not listed)
• How is the author to decide between defining a term in-line and defining it in the Terms and Definitions section?
• Authors are able to import all the terms from an external document by just listing the document in the Terms and Definitions section -- this seems sub-optimal because there can be accidental clashes in terms, and individual terms cannot be marked-up when used in the body prose.
  • It's a little bit like a Python from ... import * situation

[ERyan71258]

A few comments to start:

• There should be a separate Terms and Definitions clause. Especially in documents with many terms that require definition, it provides an easy-to-access reference, and would eliminate the need to search for the first mention of the term in the document to locate the definition (which could change as the document is written, and add another task for the editor, who would have to relocate the definition). It would also be easier to detect defects, such as circular definitions. I am also a proponent of hierarchical Terms and Definitions where appropriate.
• I agree that a definition can consist of simply a reference to another source. We can use the current ISO formatting.
• In my experience, the loose guide for deciding if a term is defined in the Terms and Definitions clause vs. in line, has been that if the term was used in perhaps only one clause and only once or a few times, then it would be OK to define in line. I don't agree. If a term requires definition, then it should be in the Terms and Definitions. A larger question is which terms should be defined? I encounter many levels of detail. For example, while many documents mention bits and bytes, I believe that I have come across only one that defined both. I questioned why it was needed, and as it turns out, a byte was not always 8 bits. In this document, it was. That leads to another discussion: defining the use of mathematical and logical terms and operators. A few documents include them; most do not. Should we provide a reference, or might there be differences in how some of the operators might be used?
• I would retain the ability to add Notes to entry. They can help to add more information about a definition.
• Interesting point about automatic importation of terms. If a document is used as a normative reference, then importing the terms should not cause a clash. If it does, then it must be addressed. And if multiple normative references are cited, then there might be multiple definitions of the same term. Again, requires management.

[SteveLLamb]

Formatting has been dealt with and conformed 1-1 to ISO in #398, #400, and #406.

Leaving this open for potential documentation on guidance for usages of Terms in general.

There is no provision in the ISO directives for an Index or ToC of Terms (as also mentioned here #117 (comment)), and it cannot go into current Terms clause. I would suggest an informative annex if so desired, but that is a dev effort.

See also #117