TD section on schematron constraints needs work

[lb42]

Here are some things thatoccurred to me when re-reading section TDTAGCONS (22.5.2)

[For dispositions as of 2023-11-10 see #issuecomment-1711937223; short notes appended to each point here.]

1. The first four paras repeat each other. — DONE, per PR improvements to discussion of constraints in TD #2500.
2. The content model for constraintSpec shows that <constraint> is optional within it. What does it mean to have a constraintSpec with no constraint? — DONE
3. It would be helpful to explain why namespace prefixes are necessary within <constraint> (an analogy with xslt might help); where is the prefix s: defined? — deferred to schemaSpec should provide a mechanism for specifing Schematron query language binding  #2330
4. The language used by constraint messages varies wildly between formal passives ("x should be,,,") and hortatory ("you should...") : either be consistent or thematize that this is a project choice — discussion needed
5. The phrase " note here the use of a report and an assertion within one pattern:" is not very informative. This section doesn't have to provide a full schematron tutorial (though it might be useful to reference one) but gnomic remarks like this don't help. — discussion needed
6. That last example is the only place where I see a <s:rule> with a @context : this really needs to be explained more fully (e.g. to explain that most schematron constraints in TEI assume a default context and what that is) — will probably become irrelevant as we will likely require an <sch:rule> (with a @context, it is a required attribute) in every Schematron <constraint>.

[sydb]

Thanks, @lb42. I think this is mostly spot-on, and at least 2, 3, 4, & 6 should be addressed toot sweet. (I don’t really see much problematic repetitiveness in 1st 4 paras, and think 5 requires some thought or discussion. And as for namespaces, I think it is a bit worse than you describe, as a TEI customizer does not have to declare the TEI namespace. (It is declared in P5 in the definition of <TEI> — which brings up another question, for which if no one has a good answer here, I will create a new ticket: why are tei: and xs: defined separately from rng:?))

[martindholmes]

@lb42 @sydb and I have already been talking about the question of Schematron with and without @context. Since there are contexts in a <schemaSpec> in which it's not possible for the processing to usefully infer what @context should be, I personally think that @context should be mandatory, enforced through Schematron itself, but at the very least we should explain clearly in what contexts it's necessary and not necessary, and why.

[sydb]

And, BTW, I completely disagree, and think that best practice would be to use @context only when necessary. That said, when there are contexts for which we can predict @context is necessary, it should be required by the schema (whether RNG or SCH).

[sydb]

Based entirely on my own thoughts setting this to “Go” for (2), (4), and (6); and to “Needs Discussion” for (1) and (5).
I think (3) is also probably “Go”, but am a little less confident.

[sydb]

Note: bb4fbae was to wrong branch, and has been deleted. (Thanks, @hcayless!) 8858d0d fixes (2).

[peterstadler]

8858d0d broke the build so I was looking into this a little bit. I think the problem lies here:

TEI/P5/Test/detest.odd

Line 457 in 9b39687

<constraintSpec ident="activepassive" mode="delete" scheme="schematron"/>

yet I find this a very valid example for an empty <constraintSpec>

[sydb]

Good point. So <constraintSpec> should be empty iff @mode is "delete", right? Kinda like <elementSpec>; but is it enough like it that we can use the same constraint? Here it is:

<constraintSpec scheme="schematron" ident="child-constraint-based-on-mode">
  <constraint>
    <sch:rule context="tei:elementSpec[ @mode eq 'delete' ]">
      <sch:report test="child::*">This elementSpec element has a mode= of "delete" even though it has child elements. Change the mode= to "add", "change", or "replace", or remove the child elements.</sch:report>
    </sch:rule>
    <sch:rule context="tei:elementSpec[ @mode = ('add','change','replace') ]">
      <sch:assert test="child::* | (@* except (@mode, @ident))">This elementSpec element has a mode= of "<sch:value-of select="@mode"/>", but does not have any child elements or schema-changing attributes. Specify child elements, use validUntil=, predeclare=, ns=, or prefix=, or change the mode= to "delete".</sch:assert>
    </sch:rule>
  </constraint>
</constraintSpec>

[sydb]

So, (2) has been done. Looking more carefully at (1), I think the prose is a bit repetitive and does need some attention. Thus I am going to commit some suggestions in the branch to see what other folks think (I am thinking of @ebeshero, @hcayless, and @lb42 here). Hopefully will push that up in a few hours.

[sydb]

OK, that took longer than expected. See the source file starting at line 844, or see the HTML output.

[sydb]

I am not sure, but I think this is where we are on this issue:

1. Addressed, at least to some extent, in branch.
2. Addressed in the published Guidelines: “A child <constraint> is required when the @mode attribute has the value "replace" or "add" (or is not specified, as "add" is the default). No child elements are permitted when the @mode attribute has the value "delete". At least one child element is required when the @mode attribute has the value "change".”.
3. Ignoring on this ticket; I expect this to be addressed with the new <constraintDecl> element (or whatever it ends up being called; see, e.g. schemaSpec should provide a mechanism for specifing Schematron query language binding  #2330). Note that I have not opened a new issue for location of <sch:ns> declarations, because I expect that will be addressed with <constraintDecl>, too.
4. Not addressed; discussion needed. Personally, I think prose should explain that linguistic style is project-specific, and therefore we exemplify different approaches.
5. Not addressed; discussion needed. Personally I do not see this as much of a problem.[1]
6. As of the Paderborn conference, it seems I may be the only person on the planet who thinks default contexts are useful and should be retained. Most everyone else thinks we should just require there be an <sch:rule context="…"> in any <constraint> that includes either an <sch:assert> or <sch:report>. Thus I think this point should be ignored here, and addressed fully in whatever issue is raised for requiring contexts. Sigh.

Note
[1] But looking at it, I am horrified by the example it is talking about, which has the character < in the content of the <sch:assert> itself, twice. That should never happen (it should show up on the page as <table> or some such, so that the user reading the HTML page can copy-and-paste, and the user reading a PDF or printed page can read-and-copy-by-typing). I have just tried to fix this (by changing < to <, twice), but that resulted in < in the output. Weird. I think I smell another issue being opened …

[sydb]

Assigning @ebeshero to look up her old ticket that may be related and link iff appropriate.

[sydb]

See #2369, instead.