Skip to main content

Section 8.2 Notes and Commentary

The <commentary> element is designed primarily for the purpose of adding material to a document to make an enhanced version. It is similar in many ways to a <paragraphs> in that it can be placed within any division and must be titled. The main difference is that it is not displayed by default, so you must set a processing switch to enable its appearance:

xsltproc -stringparam commentary yes ...

Other distinctions are:

  • Since it is elective, you need to be careful about cross-references to and from a <commentary>. It is highly likely that you will want to make cross-references within a <commentary> pointing to other portions of your text, and this is always a good idea. You will want to avoid making cross-references to a <commentary> from other parts of the text, with the exception of a cross-reference that originates within some <commentary>.
  • Numbered items are prohibited within a <commentary>, such as a <figure> or a <theorem>. Doing so would disrupt consecutive numbering in different versions, with or without, <commentary> included. Numbered equations are not prohibited in the schema, but should definitely be avoided anyway.