[tei-council] invalid examples allowed in Guidelines?

[James Cummings]

On 11/01/11 15:40, Lou Burnard wrote:
> On 11/01/11 10:23, James Cummings wrote:
>> On 11/01/11 09:44, Sebastian Rahtz wrote:
>>> James has an interesting counter proposal, that we should make all
>>> the examples entirely valid, but add a new attribute @noDisplay in the TEIX namespace.
>> Just to elaborate on this.  The idea is that when we are missing
>> out elements in TEI examples we are doing so *only* for a reason
>> of presentation.
>
> As my previous post suggests, I think I disagree with this. It isn't
> just a matter of presentation: it's a matter of the intention underlying
> the specific example -- what it is meant to illustrate. There are
> situations where we want to illustrate something about an element
> without being specific about its content because to do so would be
> confusing. We want to illustrate whereabout in a document  a Header can
> appear without repeating all the information about what a Header must
> contain. We want to demonstrate that a<div>  can contain just<entry>
> elements and nothing else.

Sure... here I was using 'presentation' in a way to include 
'pedagogical reasons for why we only want to show some of the 
example'.  As a counterpoint to 'validation' in my head I guess. 
  I in no way suggest that it isn't a good thing to be able to 
not include otherwise required bits of the TEI in an example for 
exactly the reasons you suggest.  The presentation of fully valid 
examples would be confusing for the reader, thus we want to 
present fragmentary examples for completely clear and good 
pedagogic reasons.  The presentation of these is ...a matter of 
presentation, I would argue, and has very little to do with the 
validity or not of the example.  Separately we think, I believe, 
having entirely valid examples in general to be $AGoodThing and 
so need some mechanism to allow us to have fully valid examples 
but hide some bits of those whose presentation might be confusing 
to the user and undermine the lesson we are trying to teach.  I 
don't think at the core of things we're disagreeing, except 
perhaps on implementation.  My suggestion is only a straw man really.

If it is just that entry can be used inside div then it is 
pedagogically good to alert the reader (through some 
presentational means) to that this isn't a fully complete entry 
element.  One way to do that is to have the underlying example be 
valid, but present them with an XML comment saying that some 
things have been hidden in this rendering to allow them to just 
concentrate on the important bit.

> Of course there are also times when we want to present the overall gross
> structure of a document, and allow the reader to unpack at will
> particular bits of it to reveal the wonders below, but that's a
> different pedagogic situation and a different approach, not really well
> suited to a document which has to be usable in static printed form as
> well as on the web.

Yes, teiHeader is a good example of this.  People would *LOVE* 
for pedagogical reasons exactly the fully complete and specified 
header that they could drill down into, but would hate this in a 
printed version.  But replacing the drill-down-into'able sections 
with a comment saying <!-- publicationStmt would go here --> or 
whatever, seems sensible to me in print versions.

-James

-- 
Dr James Cummings, Research Technologies Service
OUCS, University of Oxford