Managing egXML content (validation and presentation)

teix:show is skightly different from James' teix:noDisplay='true', since it applies to the nodes to be displayed or not and not to the parent of the nodes one does not want to display. This allows a better control on which subnodes one may want to show or not.

Any combination of the two attributes for a given example can be forseeen, of course.

And sorry for the spam, I now see that James wanted the same as me, I quote:
It would, however, be better if the user could choose to see the
missing bits or not in some cases, and the example was when fully
shown a valid chunk of TEI. So my suggesting is *slightly*
different from what Sebastian suggests below. Instead of putting
the attribute on the <fileDesc> I would have put it on the child
elements since you may wish to hide some of them and not others.
Moreover I would not have this be a binary true/false but
instead have something like: 'collapsed', 'expanded', 'hidden',

I don't have any problem with @show (though I would not give massive priority to implementing it).

As regards @validates, I am not sure of the name. perhaps just @valid. But more importantly, I would differentiate three ways between

1. a tree which is fully valid against the chosen schema
2. a tree which is feasibly valid against the chosen schema
3. a tree which does not try to be valid at all (<foo><bar/></foo>)

As regards having it as an attribute on the elements within the <egXML>,
as opposed to on <egXML> itself, I am lukewarm. Supporting it on all
elements traversing down the tree is a lot more work (and thats without
even implementing it).

Because I like a quiet life, I'd propose adding it to <egXML> and then
extending it later when/if the demand comes.

teix:show - I suppose that yes/no (inherited as stated) does what I want.... the reason I didn't make it boolean is for the possibility of distinguishing between things which we are hiding for pedagogical reasons (we don't want to frighten you with this yet) and things we *never* want to show.

teix:valid - I definitely feel that either the example as whole should be valid or it shouldn't be. Having partly valid examples where we go through and say "This bit is valid, that bit is valid, oh, but this bit here isn't" seems overkill and a nightmare to implement. (And for the use-case of the Guidelines, I don't think buys us much.) I also worry about the boolean datatype again, as SPQR notes it might be better to have 'valid', 'invalid', and 'feasibly' or something.

-j

I like @valid, so long as Sebastian's suggestion of the value "feasible" is incorporated, as that seems the single most useful use of this in the guidelines: to be able to leave out unnecessarily complicated but strictly required elements from an example to which they're irrelevant. (It occurs to me this might have bought us a chunk of what TEI Tite ended up leaving out too, mightn't it?) And there must be examples of implementation against feasible validation out there.

@show I'm less convinced of the use-case for, now that the examples are solved (!) with @valid...?

Gaby: My argument for @show (or whatever) remains the same. I'd like to be able to present an example where some of the children/grandchildren were collapsed (whether displayed as a comment or some expandable/collapsible bit of javascript depends on context). One of the benefits of this is it allows the presentation of quite a full example, but an initial display that is less threatening, and then as the user reads through information about the example, they can expand/collapse other parts of it. Just making the decision on the processing-for-presentation side of things becomes immensely difficult without something in the source saying 'keep this one showing' and 'hide this one and its children', etc.

This is, you are right, a completely separate issue from the validation of the examples (just came up as a result of discussing possible ways to solve it).

-James

How's the following as an update to <egXML>:

<attList>
<attDef ident="valid">
<desc>indicates the intended validity of the example with respect to
a schema.</desc>
<valList>
<valItem ident="yes"><desc>the example is intended to be fully valid,
assuming that its root example can be used as the root element of the
schema concerned.</desc></valItem>
<valItem ident="feasibly"><desc>the example could be transformed into
a valid document by inserting any number of valid attributes and child
elements anywhere within it; it is valid against a version of the
schema concerned in which every data, list, element, or attribute
element has been made optional.</desc>
</valItem>
<valItem ident="no"><desc>the example is not intended to be valid,
and contains deliberate errors.</desc></valItem>
</valList>
</attDef></attList>

<exemplum>
<egXML xml:lang="und" xmlns="http://www.tei-c.org/ns/Examples" valid="feasible">
<TEI >
<teiHeader xml:lang="fra">
<!-- ... -->
</teiHeader>
<text xml:lang="eng">
<!-- ... -->
</text></TEI></egXML>

</exemplum>

Further comment, if we agree that @show and @valid are different -- how is @show different from @rend ?

two comments on Lou's proposed implementation
a) add type="closed" to <valLlist>
b) "yes", "no" and "feasibly" jar slightly as a group. Firstly,
we agreed to use "true" and "false" elsewhere, and secondly
the grammar seems odd.

true, false, and feasible

?

Just to report, @valid is now present in the soon-to-be-released P5 1.9.0, with allowed values of true, false and feasible.

no agreement or progress on the other attribute

When we were examining this ticket at the Council F2F meeting, we felt a little confused by the wording of the description of the values for @valid as they currently appear in the guidelines. First of all, egXML is identified as containing an XML fragment. An XML fragment is a section of an XML document which is considered "well balanced":

"A region (consecutive sequence of characters) of an XML document is said to be (well-)balanced if it matches production [43] content of [XML 1.0]. Informally this means that, if the region includes any part of the markup of any construct, it contains all of the markup of that construct (e.g., in the case of elements, all of both the start and end tag)."

http://www.w3.org/TR/xml-fragment.html#terminology

This implies that an XML fragment may consist of a pair or a group of siblings, not necessarily a single hierarchy rooted on one element. However, the subsequent definitions of @valid="true" and @valid="feasible" seem to require that a fragment in <egXML> be rooted on a single element, in order that it may be validated using a manipulated schema which is rooted on that element. If this is indeed the import of @valid, then the word "fragment", which in XML has a broader meaning than is intended here, should be removed from, or qualified in, the definition of <egXML>.

In addition to this, we believe two of the three value definitions could be clarified. Specifically>:

"true:
the example is intended to be fully valid, assuming that its root element can be used as the root element in the schema concerned. [Default]"

The use of "can" here implies that a TEI schema can be rooted on any TEI element (such as for example <p>). This is not the case in a standard TEI schema, so the language should reflect that this is a hypothetical condition, by the use of "could" or "were able to" instead of "can".

"feasible:
the example could be transformed into a valid document by inserting any number of valid attributes and child elements anywhere within it; it is valid against a version of the schema concerned in which every data, list, element, or attribute element has been made optional."

Here our problems are with two phrases which we don't understand: "every data", and "attribute element". We suspect "attribute element" should simply read "attribute", but we don't actually know what is intended by "every data".

The apparently meaningless phrase is cut and pasted from the Jing specification at http://www.thaiopensource.com/relaxng/jing.html

"A document is feasibly valid if it could be transformed into a valid document by inserting any number of attributes and child elements anywhere in the tree. This is equivalent to transforming the schema by wrapping every data, list, element and attribute element in an optional element and then validating against the transformed schema."

What cutting and pasting obscures is that the words "data"," list", "element", "attribute" and "optional" are typographically distinct: they are actually element names in the RelaxNG schema being validated. One hesitates to improve on James Clark's language but maybe the following is less confusing:

"This is equivalent to validating the document against a version of its schema which has been transformed by wrapping every data, list, element and attribute element it contains in an optional element"

Proposal 1: correct prose as per last two comments
Proposal 2: use tei:rend inside <egXML> to control rendering of egXML content

In implementing this, it is my understanding that I will
a) Correct the prose of the egXML elementSpec, particularly the valItem's of @valid to represent the understanding recorded below
b) Change TD chapter to recommend the use of tei:rend inside the TEI Examples namespaced egXML to record rend information.
c) Add an example of egXML with an embedded @rend both for the elementSpec and the TD chapter.