[xslt4] xsl:note for structured documentation #109
Description
I propose that we add an element xsl:note whose intended use is for structured documentation.
The element may appear anywhere and may have any attributes and content, including elements in the XSLT namespace. Any xsl:note elements in the stylesheet are stripped (together with their attributes and descendants) at the same time as comments and processing instructions are stripped. (Rules such as "xsl:param must come first" or "xsl:apply-imports must be empty" thus apply to the stylesheet AFTER xsl:note elements are stripped.)
Traditionally, structured documentation comments have been written in a third-party namespace. This approach has two disadvantages:
(a) they can only appear in a limited number of places (typically as children of xsl:stylesheet)
(b) they require an extra namespace to appear on the xsl:stylesheet element, and this namespace has semantics that affect the stylesheet execution. It even needs to be carried through to run-time, in case someone (for example) tries to cast a dynamic string to a QName.
The spec would say very little about xsl:note, except that it is permitted and ignored by the XSLT processor. It might offer some usage suggestions:
(a) an xsl:note appearing as the first child of xsl:package or xsl:stylesheet should be taken as pertaining to the package or stylesheet as a whole; an xsl:note appearing anywhere else should be taken as pertaining to the first following sibling element that is not an xsl:note (if there is one)
(b) third party software that takes account of xsl:note (for example, a tool that generates documentation) should only recognise xsl:note elements that specify target=XXX where XXX is a string that they decide upon.
(c) XSLT processors are discouraged from using xsl:note elements to modify the behaviour of the processor in any way, for example in ways that change the output or the performance; they are expressly not allowed to use xsl:note elements to trigger non-conformant behaviour.