[tei-council] Chapter 22 - Documentation Elements

[Lou's Laptop]

Brett Zamir wrote:
> In the note on the egXML reference page, "the content must however be 
> well formed XML: where this is not the case, the more general <eg> 
> element should be used in preference.", I think (besides adding a 
> hyphen to "well formed", the following could be more exact, since the 
> example need not have a root element: "the content must however be *a 
> well-formed XML fragment or document*: where this is not the case, the 
> more general <eg> element should be used in preference.".
OK.

>
> Likewise with the definition, " (example of XML) contains a single 
> well-formed XML example demonstrating the use of some XML element or 
> attribute, in which the <egXML> element itself functions as the root 
> element." being changed to " (example of XML) contains a single 
> *well-formed XML fragment or document *example demonstrating the use 
> of some XML element or attribute, in which the <egXML> element itself 
> functions as the root element."
>
I removed "or document".

> I added indication that egXML could not only be well-formed, but also 
> a well-formed fragment (i.e., not having a root element is ok).
>
this is implicit in the statement that the egXML element is the root 
element surely?

> I presumed that the namespaces for egXML and Relax NG were added by 
> this chapter's module and noted the docs as such.
No, they are not defined by this module.

>
> Has anyone made a Schema to ODD converter, btw?
>
Not that I know of: such an exercise would in general be difficult, 
since ODD has more information in it than most schema languages.

> *22.1.1 Phrase Level Terms
> *
> Maybe the xml:space definition (not in source) could be changed from:
>
> "signals an intention that white space should be preserved by 
> applications"
>
> to
>
> "signals an intention that white space should be preserved by 
> applications*, such as XSL processors*"
>
> in order to give a salient example?
>
well, possibly. but we dont want to give the impression that this 
applies only to XSL processors,


> *22.1.2 Elements and Attribute Descriptions
> *
> Couldn't a <specDesc> be made to use an IDREF type attribute 
> optionally to facilitate vaildation? How about <memberOf>, <classSpec 
> ident>, etc.?

I'm not sure what you're suggesting here. We validate using the @ident / 
@key attributes just as effectively as if we were using ID/IDREF.
>
> *22.2 Modules and Schemas
> *
> For the line, "the order in which  element declarations appear within 
> the schema code generated from a <gi>moduleSpec</gi> element cannot be 
> altered, and is not affected by the order of declarations within a 
> <gi>specGrp</gi>.", I think it might be nice if mention were made as 
> to why it cannot be altered.
>
Because that's how the ODD processors work... well, also because there 
isn't any way of specifying the order ... except by means of the 
predeclare attribute, come to think of it.  Actually, I think I'll just 
delete "cannot...and".


> *22.3 Specification Elements
> *
> In Chapter 1 on the Infrastructure, there is the line "In former 
> editions of these Guidelines, such elements were known metaphorically 
> as <soCalled>crystals</soCalled>". Therefore, should the line in this 
> section, "For this reason, we refer to them informally as crystals", 
> be emended to indicate that they were formerly referred to as such?
>
Ah yes. Well spotted! Changed "informally" to "metaphorically"


> *22.4.1 Description of Components
> *
> 1) For the line beginning "A <gi>desc</gi> element is used...", 
> perhaps this should be introduced in the list just previous to it and 
> in at least one of the examples that follow?
>
 <desc> is defined in the core so shouldnt appear in the specList here: 
but I've added an example.

> 2) For the example with "<ptr target="#COHQHF"/>", I think it might be 
> nice to have a comment indicating to which element this is pointing.
>
OK

> *22.4.2 Exemplification of Components*
>
> Maybe the definition for <exemplum> (not in source) could be changed from:
>
> "contains a single example demonstrating the use of an element, 
> together with optional paragraphs of commentary."
>
> to
>
> "contains both a single example demonstrating the use of an element, 
> along with optional paragraphs of commentary."
>
> in order to more clearly contrast it from the <eg> and <egXML> 
> definitions.
>
I see what you're trying to say, but your wording is not quite right. 
How about

"groups an example demonstrating the use of an element along
with optional paragraphs of commentary"

> *22.4.3 Classification of Components*
>
> Is there supposed to be something defined by the code starting with 
> the following (e.g., to define <equiv>?): 
>     <specGrp xml:id="TDSG4" n="Common specification elements">?
>
The <specGrp> is used to hold a number of specDescs.


>
> *22.4.4 Element Specifications*
>
> 1) The example beginning <rng:text 
> xmlns:rng="http://relaxng.org/ns/structure/1.0"/> is not actually 
> output with the xmlns attribute, even though I think it probably 
> should be in this case since the next line states "This content model 
> uses the RELAX NG namespace".
>
I think this is a formatting problem.


> 2) For the line, "The RELAX NG language does not formally distinguish 
> element names, class names, or macro names", is the same true for 
> attribute names, and if so, should it be added to the list?
>

Yes: and has been.

> *22.4.5 Attribute List Specification*
>
> Maybe the definition for <valDesc> (not in source), so as to 
> distinguish it from <datatype>, could begin as "*informally* specifies 
> any semantic..."
>
OK

> *22.4.5.2 Value Specificiation
> *
> 1) For the line, "The <gi>valList</gi> element is also used to provide 
> illustrative examples for the values permitted and their significance, 
> or to gloss the meaning of values implied by an attribute's 
> datatype.", might some examples be given of how examples can be given 
> or how a gloss is given for values implied by an attribute's datatype? 
> Might mention also be made of TEI Recommended Practice being indicated 
> by use of valList's?
This is a bit inaccurate: I've corrected it.
>
> 2) Why are <!--specDesc key="equiv"/--> and <!--specDesc key="desc"/> 
> <specDesc key="remarks"/--> commented out? I think the following line 
> from this section ought to be able to refer to these sections: "this 
> is the function of the <gi>desc</gi> element), nor to comment on 
> equivalent values in other schemes (this is the purpose of the 
> <gi>equiv</gi> element).".
>

As noted above, we dont include them here because they're dfeined in the 
core.

> *22.4.6 Element Classes*
>
> <classSpec> ought to have a comma after the words "that is" in its 
> definition (not in source).
OK
>
> *22.4.7 Pattern Documentation
> *
> Why does the example in the reference page for stringVal list "SYSTEM 
> 'teiclasses"'"? Isn't a SYSTEM entity supposed to be followed by a 
> file name?
>
OK, I've made it a flename.
> In the definition for <macroSpec type> and for <stringVal>, mention is 
> made of creation of an entity. Could this be made more generalized if 
> this is not only for entities?
>
These features  is really only used in DTD generation. I am not sure how 
we'd want to generalise it.
> *22.5 Building a Schema
> *
> The @predeclare attribute in att.identified (not in source) I think 
> should have "tei" capitalized, no?
>
No, module names are all lowercase


> I didn't see any mention here of how a namespace is specified for an 
> element definition. Should that be added to the <soundClip> example? 
> (I see the reference mentions use of @ns on the <elementSpec>.
>
Yes, that should be added.


> And I'd just like to reiterate my earlier suggestion to show on the 
> datatype pages examples of  elements and attributes that use the 
> datatypes in question.

Yes, some examples would certainly be useful.

>
> And while I'm sure this question was covered somewhere, I hope you 
> don't mind my asking whether datatypes are only defined for attribute 
> values or also for elements? If so, why not for elements (in addition 
> to allowing elements to be defined directly by RNG, etc.)? If for 
> elements too, should the datatype macros be changed to indicate that 
> they can also be used for element content?
>
In practice, although RNG permits it, we don't use datatypes for content 
models. We use model classes instead.