Comments in `path` and `facsimile` constraints

joeytakeda commented 1 year ago

Comments in a <constraint> are serialized and appear on the spec pages for <facsimile> and <path> (these are the only two instances of a comment in a constraint, as far as I, running //constraint[descendant::comment()], can tell).

<facsimile>:

<sch:rule context="tei:facsimile//tei:line | tei:facsimile//tei:zone">
<sch:report test="child::text()[ normalize-space(.) ne '']"> A facsimile element represents a text with images, thus
transcribed text should not be present within it.
</sch:report>
<!-- 
                       What about:
                       * ellipses/supplied/text()
                       * writing
                       * label, formula, app, witDetail, metamark?
                       * notatedMusic?
                       * figure/[all-sorts-of-crazy-stuff-e.g.-entry]
                       * addSpan, damageSpan, delSpan
                       Or the fact that <front> and <back> (but not <body>) are
                       permitted inside <facsimile>, and thus *anything* can be
                       inside ther?
                       -->
</sch:rule>

<path>:
```
<sch:rule context="tei:path[@points]">
```

<sch:let name="firstPair" value="tokenize( normalize-space( @points ), ' ')[1]"/> <sch:let name="lastPair" value="tokenize( normalize-space( @points ), ' ')[last()]"/> <sch:let name="firstX" value="xs:float( substring-before( $firstPair, ',') )"/> <sch:let name="firstY" value="xs:float( substring-after( $firstPair, ',') )"/> <sch:let name="lastX" value="xs:float( substring-before( $lastPair, ',') )"/> <sch:let name="lastY" value="xs:float( substring-after( $lastPair, ',') )"/>

The first and last elements of this path are the same. To specify a closed polygon, use the zone element rather than the path element. ``` I like both comments, but IMO the `facsimile` comment should be moved above the `` (cf. #2363) and, for `path`, the comment should become a `` for the ``—maybe something like "Since a `` represents a line with distinct start and end points, the last coordinate must not repeat the first coordinate"

sydb commented 1 year ago

I think this also presents a reasonable processing (i.e., Stylesheets/ and ATOP) question: should comment nodes inside a <constraint> either be weaved into the documentation (e.g. to the specification pages of the Guidelines as noted here, the PDF, or the customized documentation generated from an ODD) or tangled into the schemas? My instinct is there should be (at least) two places for an ODD author to place annotations: someplace that makes it into end-user documentation, and someplace that does not. Given that the <desc> element and XPath comments will be weaved into the end-user documentation, XML comments should not. They should be dropped. As to whether XML comments inside <constraint> should be tangled into the schemas, my instincts are “no” and “it does’t matter much”, but I have not made up my mind, yet.

joeytakeda commented 1 year ago

Thanks @sydb!

Re: comments in the schematron: I have a feeling there may be some cases where comments for the code may be useful/necessary, but aren’t descriptions of the constraint (complex xpath, regular expressions, and embedded XSLT come to mind), so I’d vote keeping the processing as it is now and not dropping comments from the output documentation.

Re: comments in the schema: I’m also in the “it doesn’t matter much” camp, since one ought to always look at the ODD and documentation for any full info, no?

sydb commented 1 year ago

Re: comments in the Schematron: Well the complex XPath or regular expression case can be handled by embedded XPath comments. I had not thought about embedded XSLT; have never used it in an ODD. I am now wondering (aloud) if a rule that said “elements that match //sch:*//tei:* need to be processed, with the default processing being stripped out, during either tangle or weave processing” would solve both #1582 and the need for annotations that are dropped during tangle, or weave, or both?

Re: comments in the schema: Yeah. I have occasionally toyed with the idea that the schemas should be “minimized” both to make them smaller for download and to emphasize that the ODD is the human-readable version.

TEIC / TEI

Comments in `path` and `facsimile` constraints #2414