use Pure ODD for content model elements

[sydb]

NOTE — this PR is to merge changes into the iss2154_interleave branch, not dev. Therefore it would beehoove us to merge it before we merge iss2154_interleave.

---

The primary idea behind this PR is to use Pure ODD, rather than Schematron, to require that each of the content model wrapper elements (<alternate>, <interleave>, and <sequence>) has two or more children.

HOWEVER, as I went about doing so I realized that the existing content model for <alternate> had a bug. It was

 ( valList | model.contentPart )*

That allows for two or more <valList> children. I am not 100% sure what having an <alternate> with 3 <valList>s would mean.¹ But in any case, if there is more than one <valList>, the Stylesheets simply ignore the whole <alternate> (and, in my test, the <elementRef> I had before it, but not the <elementRef> I had after it — weird).

So I replaced this content model (and the Schematron that went with it to ensure 2+ children) with:

(
  ( model.contentPart, ( ( model.contentPart+, valList?) | valList) )
  |
  ( valList, model.contentPart+)
)

That is reasonably complicated, partially because it is a mildly complex set of restrictions, and partially because we cannot use an ambigous model (because DTDs and XSDs choke on them). But I have provided an English description below. In any case, the really astute reader may notice that this new content model prohibits two sequences of elements that were allowed under the old one:

1. Any sequence that has more than one <valList>. Since these don’t work, anyway, this is a good thing. (And one of the desired effects.)
2. One or more model.contentPart followed by a <valList> followed by one or more model.contentPart. It is at least very difficult, if not impossible, to allow this sequence and remain unambiguous. But I really cannot see any user complaining that she has to put the <valList> either first or last. (Heck, I find it hard to imagine any user ever making use of an <alternate> that includes a <valList> child and has more than 2 children. There are no such cases in P5.)

In any case, I have built P5 and the exemplars and run the tests in the Docker (this branch against the dev branch of the Stylesheets), and they all worked.

below

It is a bit easier to say this in English if the content model were written in a different order:

(
  ( valList, model.contentPart+)
  |
  ( model.contentPart, ( valList | ( model.contentPart+, valList?)  )
)

That declares exactly the same content, and if I had thought ahead to the problem of explaining it in English, I might have done it that way. Given this re-ordered model, the following is a possibly helpful description of it:

The content either starts with vL or with m.cP.
If it starts with vL, then that single vL must be followed by one or more m.cP.
If it starts with m.cP, it is actually starting with either a single m.cP, in which case that single m.cP must be followed by a vL; or it is starting with a sequence of two or more m.cPs, in which case said sequence may be followed by a single vL (or not).

notes

¹ My guess is that it would mean “any one value from any of these value lists”. And one could imagine a situation where it would be useful to get the lists into the <alternate> via XInclude, and thus allowing more than 1 would be necessary. But I daresay no one has ever even seen that done before, let alone done it, because our Stylesheets couldn’t process it!

[raffazizzi]

This looks like a clever replacement to me that matches the intended behavior for <alternate>. I see a commit to closer.xml adding byline to the content model. Does that belong elsewhere? Left in there by mistake?

[martindholmes]

I agree with @raffazizzi that the closer thing is probably not part of this. I also went back to the original ticket for this branch, which is closed, and I'm not sure I understand what the actual motivation for this PR is. Schematron is a fully valid component of the TEI schema system, and I worry that an overly-complicated Pure ODD content model is perhaps less comprehensible and maintainable than a simple Schematron rule. @sydb is there any motivation other than that it's an interesting challenge to make this work?

[sydb]

• I do not know why the small change to <closer> (adding <byline> to its content) is here, but it is also in <dev>, so is utterly irrelevant.
• The motivation for this has nothing to do with the challenge, which was not discovered until after I started trying to implement it.
• Of the three “real” (i.e., not <closer>) changes, two of them reduce a constraint expressed in 9 elements & attributes in 7 lines of code to 1 attribute in 0 lines of code.
• Only the change to <alternate> adds complexity, and it does so in order to solve a (serious, if incredibly rarely a problem) bug: an <alternate> can currently (and erroneously) have 2+ <valList> children.

So, as I see it, the arguments in favor are:

• ODD writers will get validation immediately (including proper pop-up lists), not only if they remember to use Schematron (which they should)
• Our ODD will be a lot simpler in 2 of 3 cases
• A corrigible error in the schema is fixed

The argument against is:

• The PureODD for the content of <alternate> is complex

I have tried to mitigate that one argument against by providing lots of commentary.