[tei-council] Some doc issues

[Lou Burnard]

Brett Zamir wrote:
>
> I've removed some extra double spaces (not including those following 
> periods, colons, etc. for the sake of those who prefer these in the 
> text), also in the attached About document (no other changes in the 
> latter), though I know these were pretty harmless.
>
I've never quite understood why double spaces are a problem -- they 
don't seem visible to me when the text is rendered, but maybe I just 
haven't been looking closely enough. Anyway, a script to get rid of all 
of them everywhere shouldn't be too difficult!

> First, there are a few documentation-wide questions I have. While it 
> may not be required per se, I am more accustomed to certain terms 
> being hyphenated which are not in the document. For example, 
> "well-formed" in an XML context, "cross-reference", etc. Should I go 
> ahead and try to correct these, or is there some convention you are 
> relying on to use these?
>
We aim for consistency: although it's often pretty hard to decide 
apriori whether or not a given pair of words should be hyphenated (and 
there appears to be a historical trend away from hyphenation), if they 
*are* they should be everywhere (and vice versa). So feel free to point 
out inconsistencies you spot!


> Revisiting the GPL issue, if one were to make a software package which 
> used the TEI Guidelines, wouldn't the GPL license (if it were not 
> changed or dual-licensed as LGPL, the "Lesser" GPL) require such 
> software to not only obligate return of modificatons to the 
> documentation itself, but also to the software packaged with it?
>

I'm not a licensing dude, but we did look into this issue fairly 
carefully before deciding on the current license arrangements. Oxygen, a 
commercial product, certainly has no problem using the TEI Guidelines 
under the current licence scheme.
>
> *v. A Gentle Introduction to XML
> **
> *While this is an excellent tutorial including interesting background 
> information, I'm not so sure, I'd consider it all that gentle (at 
> least I didn't when I came across it and was starting out with XML). 
> W3Schools.com is gentle (at least for beginners), imo, but this intro 
> is a bit more technical, even while it is, as I think you mean to 
> imply, not an absolutely exhaustive introduction (though it does cover 
> a whole lot). Maybe something just like "An Introduction to XML" (or 
> "A Humanities-Oriented Introduction to XML)?
>
I think the title is now historic... it started off as a Gentle Intro to 
SGML, remember, and achieved a degree of notoriety under that guise. 
Over the years it has survived much modification, but remains one of the 
most widely distributed and cited parts of the Guidelines. I don't think 
we should change its title now -- it's practically a brand! If we were 
to change it, though, I'd suuggest inserting the word "TEI" in front of 
XML, since the main goal of this chapter is as it always has been to 
introduce all and only  those features of {SG,X}ML needed to understand 
how the TEI Guidelines work.



> v.ii - last paragraph - Could someone add an examples of how awareness 
> of "interplay between narrative units..and presentational ones" gives 
> a greater appreciation of certain works, for the edification of the 
> reader? Any ambiguous statements (ambiguous to non-literary folk at 
> least) might intimidate the reader (or they do me, at least).
>
There is a parenthetical reference to Sterne's Tristram Shandy -- a work 
in which the page breaks, page layout, and much besides are an important 
part of the narrative,and in which the author frequently pauses to 
comment on the narrative as it unfolds etc. Examples could be 
multiplied, but they would interfere with the basic point I think.


> v.iii. - At the end of the "Content models : an example" subsection, 
> I'd recommend giving mention (even as just a footnote) to RDDL, the 
> one-extra-element extension to XHTML which allows for indicating 
> resources relevant for a given namespace (the file is ideally placed 
> where the namespace URL references)--and not a bad idea for your own 
> namespace too! See http://rddl.org
> _
> _
To my shame, I've never heard of RDDL. If we find a use for it in the 
TEI, then I would certainly agree with you -- since it appears to be an 
extension to XHTML though, this seems unlikely.

> __Throughout the document, the use of "predefined" to refer to an 
> entity seems confused. In some places it seems to refer to the 5 
> always-available-in-XML entities such as "amp", but in other places it 
> seems to refer to any entities which are (necessarily) "predefined" in 
> the DTD before being used.
>
> e.g.,
>
>     "An XML
> document may contain references to predefined strings of data that a
> validator must resolve before attempting to validate the document's
> structure; these are called <term>entity references</term>"
>
> "The predefined entities
> <code>&amp;amp;</code> and <code>&amp;lt;</code> provide one method of
> dealing with this problem"
>
>

The word "predefined" appears several times in this chapter with a 
non-technical (not specific to entities) meaning, but I agree that there 
is something wrong with the following sentence:

"A reference to a named character entity, whether predefined or not, 
takes the form of an ampersand, followed by the name, followed by a 
semicolon. For example an XML document containing the string ‘T&C’ might 
be encoded as T&amp;C. Other predefined character entities include &lt; 
(<) and &apos; (')"

I suggest that the phrase "whether predefined or not" should be removed, 
and am explanation (and possibly a list) of the 
"always-available-in-XML" emtities inserted before the "For example..." 
senmtence.