Allow XSLT documentation element xd:doc as first preceding sibling of a named top-level XSLT construct

[dmj]

The current Schematron for XSLT mandates a XSLT documentation element with an explicit reference (xd:ref) for named XSLT constructs (rule: root-children-must-have-documentation). This makes it awkward to write documentation strings. I think an explicit pointer to the top-level construct is not necessary iff the xd:doc is preceds the top-level construct.

Example:

<xsl:stylesheet>
  <xd:doc>
    <xd:desc>The TEI namespace URI is defined as a global variable to avoid using magic strings in functions and templates that use it as fallback or default value.</xd:desc>
  </xd:doc>
  <xsl:variable name="atop:vTEINamespaceUri" as="xs:string"><xsl:text>http://www.tei-c.org/ns/1.0</xsl:text></xsl:variable>
</xsl:stylesheet>

[martindholmes]

The idea is to enable us to generated documentation which automatically links variables to their explanations, but if we're OK with using contiguity for that, then no problem. However, @sydb wants to be able to provide a single documentation block which applies to a subsequence series of e.g. vars or params, and that will make contiguity slightly more of an issue. I guess decisions on this should depend on whether we're going to write our own document processor or depend on Oxygen's.

[sydb]

I’m confused. I thought our rule was pretty simple: Every named top-level thingamabob (i.e., /xsl:*/xsl:*[@name]) has to have an <xd:doc> associated with it. Either its closest preceding sibling is an <xd:doc>, or there exists an <xd:doc> that refers to it via an <xd:ref>. Is that not what the Schematron seeks to enforce? (Yes, I could and probably should just go read it, but it is past my bedtime!)

[dmj]

@sydb The schematron only looks for a reference to the name in xd:ref.

[martindholmes]

I don't think we finished deciding what we wanted, so the Schematron isn't finished yet.