improve explanation of @defaultExceptions on schemaSpec

[ebeshero]

We need a more specific explanation of how to work with the @defaultExceptions attribute to deal with (one or more) namespaces outside the TEI. Also, people working with xenodata to customize elements and attributes in other namespaces may need better documentation in general.

See listserv discussion on https://listserv.brown.edu/archives/cgi-bin/wa?A2=ind1811&L=TEI-L&P=5867

[martindholmes]

Perhaps we should consider making the attribute required on <schemaSpec> and providing the most common values by default.

[sydb]

I would prefer get rid of @defaultExceptions on <schemSpec>. Even its original creators, I believe, will concede that it is a problematic hack to get us around a thorny problem until we can figure out something better or we somehow shed the shackles to ID/IDREF checking.

[martindholmes]

I don't think we're ever going to get free of idref checking; it's the default in Oxygen, and lots of people (including me) want it turned on anyway. We could build the defaultExceptions mechanism into ODD processing, but that's taking something public but ugly and making it just magic, so I'm not sure that's the right solution.

Incidentally, I've never really understood the use of the term "anyName name classes" here:

When RELAX NG DTD Compatibility Mode is turned on, validation requires that any elements which may take an xml:id be excluded from the content of anyName name classes.

What does that mean exactly, and where is it defined?

[sydb]

Well yes, you (and I) and lots of others want it turned on. But we want it on not to actually do ID/IDREF checking. After all, none of us actually have any IDREFs in our documents: we have IDs (specified on @xml:ids) and URIs that point to them. We like to have ID/IDREF checking turned on not because we want ID/IDREF checking, but because we (understandably) want oXygen to provide us with a list of IDs in the document (preceded by ‘#’) whenever we insert an xs:anyURI attribute. For some reason oXygen performs that service only if ID/IDREF checking is turned on, which also means that actual DTD Compatability Mode ID/IDREF checking is done (i.e., jing is not sent the -i switch), and thus there are nasty limitations placed on the RELAX NG "ANY" contructs.

I have always felt that we should either a) tell people to turn that feature off and live with it; b) get SyncRO to de-couple actual ID/IDREF checking from URI attribute completion pop-ups; c) re-work our schema so that it works with ID/IDREF checking turned on (which George Bina, who is a heck of a lot smarter than I, says is doable; does not look at all easy, though)

[lb42]

I disagree strongly enough with Syd to say so! Id/idref checking is an important and useful thing. We teach people to put these wretched sharp signs in for a purpose. Documenting this defaultExceptions attribute properly is not hard, certainly easier than documrnting eg the similarly obscure prefix attribute"

[ebeshero]

Sorry, but I think this discussion of ID/IDRef is straying from the initial context of the ticket. The call to improve documentation of @defaultExceptions was about providing better guidance for ODDs that define elements and attributes in multiple namespaces. The request in the TEI list was for examples and better explanation.

[sydb]

@lb42 : But we don’t have any IDREFs to check; we use URIs, not IDREFs. We put the wretched sharp signs in precisely because they are not IDREFs, but URIs. @ebeshero : Except that we wouldn’t have to worry about how poorly documented @defaultExceptions is if we didn’t have it.

Remember that the only reason this solution is acceptable to OP (Elena Pierazzo) is that the element she was adding to her schema was not intended for use inside <xenoData> or <sch:*>. Someday someone is going to want to use a namespace both in their customized schema and on elements inside one of those, and then this whole hack won’t work.

[martindholmes]

I think when something is confusing or needs explaining to @lb42, then it's unacceptably complicated and users shouldn't have to deal with it. Call this the Burnard Threshold. We should do away with @defaultExceptions and find a way for this to be handled seamlessly in the background.

[lb42]

@martindholmes but that would conflict with the Rahtz Dogma which I take the liberty of re-expressing as "no magic, no sleight of hand, no dark secrets"

[martindholmes]

I think @defaultExceptions already fails the Rahtz Dogma test by virtue of being magic (it's not clear to most of us what it means, what it does, and why we need it). Something that fails both the Rahtz Dogma and the Burnard Threshold is unambiguously egregious.

[ebeshero]

I had not realized how murky and weird this was, since the OP’s context was sensible enough. Should we rename this ticket, the Unwriting of @defaultExceptions? Or, There Will Be No @defaultExceptions?

[martindholmes]

Subgroup thinks that this is basically an obscure bug in the way that P5 works, and end-users should never be exposed to it, so our processing should silently take care of it when building a schema. The best way to do this is presumably for the processor to notice whenever there are custom elements defined in unexpected namespaces, and add these namespaces to @defaultExceptions automatically. Another alternative is to add Schematron that prompts users to add their ns to defaultExceptions when needed. Another approach would be to add Schematron that prompts users to add their custom namespace to @defaultExceptions manually.

[lb42]

This is not a bug. It's a suboptimal design feature, possibly. I stand by my assertion that it should simply be documented better. "Our processing should silently take care of it" is too close to magic for my taste.

[martindholmes]

F2F subgroup thinks this could be done in the odd-to-relax process, as a pre-pass before we do the rest of the processing. The Stylesheets group could spend some time figuring out where this should best be done, and then one or two people could actually implement it.

[ebeshero]

Full F2F Council discussion: We need to investigate how to process @defaultException in odd2rng Stylesheet, which currently throws bizarre ID errors over namespace issues. Figure it out, decide whether to get rid of @defaultException, and then write up the documentation called for in the ticket.

[joeytakeda]

Has there been any further progress on this ticket? I added a few non-TEI elements to a schema and ended up running into the same issue of ID/IDREF checking and had to trawl through the TEI listServ to figure out what the issue was (thus discovering this ticket!)

I'm in agreement with @lb42 that, at least for now, this should just be documented. I imagine that @defaultExceptions could always be deprecated or improved later, but adding a brief paragraph to the effect of the documentation (I would say "23.3.2 Modification and Namespaces": https://www.tei-c.org/release/doc/tei-p5-doc/en/html/USE.html#MDNS) would go a long way to make it clear how one can properly extend a TEI schema.

[sydb]

Sorry to say, @joeytakeda, but no, no progress has been made since late 2019. I think you are correct, we are guilty of letting the “much better” be the enemy of the “at least document the sub-optimal”.

I suggest that if a few more Council members say so here, or agree to it at our next conference call, that we change this ticket to GREEN for just documentation, and create a new ticket for doing something more intelligent. Then assignees (@peterstadler and I) work on some better explanation and examples.

In the meantime, a comment on the exchange between @martindholmes and @lb42 on 11 Nov 18: This is probably not the first time, and surely won’t be the last, that the Burnard Threshold and the Rahtz Dogma are in opposition. 🙂