[tei-council] genetic draft -- from Brett

[Lou Burnard]

On 23/08/11 23:38, Brett Barney wrote:
> This is a two-part response.

Many thanks for this Brett -- it's exactly the sort of feedback I was 
hoping for -- and I look forward to receiving similar from other council 
members.

So as not to burden people's email unnecessarily, I've snipped only 
those parts of your thoughtful response for which I have comments on 
below. The absence of a response does not mean your comment is invalid 
or uninteresting!
Naming the elephant:

> I can live with sourceDoc, though I wish it didn't look so much like
> sourceDesc, thus sort of inviting my brain to try to systematize the
> semantics of "source" in a way that I think "isn't supported."

Yes, I had that worry too. How about <source> ?

>
> As others have said, I think we need to have a new element instead of a
> repurposed<ab>. My first thought was also "block," though it doesn't
> make me giddy. Like sourceDoc, it seems at least serviceable. Part? Bit?
> Chunk? Morsel?

Since I took it on myself to add <ab> to the draft, I have also taken it 
on myself to replace it with <block> in the most recent draft (not yet 
HTML-ised, sorry).

>
> I'll look into the permissions question for the Whitman images, and,
> depending on which ones folks think are keepers I can also work to make
> them
> clearer (using better sources, cropping, highlighting, whatever). I could
> probably also hunt up different/better examples of some things, if anyone
> has specific requests.

Thanks, that would be much appreciated. Other guardians of mss images 
are also urged to look for suitable cases! Even if they don't make it 
into P5 a store of such things is invaluable for 
teaching/presentation/explanatory  purposes.


> The<desc>  for att.global.facs (at the top of p.346) and the<desc>  for
> att.coordinated (on both pp. 347 and 348) describe the attribute class in
> terms of elements rather than attributes, as is the norm. I didn't look at
> every other attribute class's<desc>, but of the ones listed under a-g on
> the webpage version, only two others (att.enjamb and att.entryLike) are
> similar. I realize that there's no real contradiction between saying that
> an attribute class provides attributes for a particular set of concerns or
> that an attribute class groups certain elements, but the first seems like
> the more useful information, at least as the<desc>s are currently used in
> the Guidelines.

The descs should definitely use a common formula. It might be worth 
putting in a bug report naming ones that seem divergant.


>
> Also, I'm not sure why the definition of att.coordinated is repeated in
> such a short space. I would think that the two could be combined and all of
> the attributes listed at once and then discussed one by one, in the way
> that I believe the discussions of other attribute classes elsewhere are
> organized.

Good suggestion. Definitely the text of PH will need quite a bit of work 
once we've added this new material -- largely for personal reasons, I 
think of this chapter as currently undergoing major dental surgery, with 
old stumps being withdrawn and replaced by gleaming new implants. Much 
pain, time, and effort is necessitated, and we can certainly expect 
intermediate stages in which the patient is only just about able to chew.



>
> @facs "may be used to associate any element in a transcribed text with an
> image of it, by means of the usual URI pointing mechanism." This makes me
> wonder what "usual" means. Usual when? To whom? If this is intended to
> refer to something made explicit elsewhere in the Guidelines (the
> definition of data.pointer in Appendix E, maybe?), an actual
> cross-reference would seem in order.

"the usual" is definitely wrong.


>
>> "By convention, this encoding indicates that the image indicated by facs
>> attribute represents . . . ."
>
> Seems to be missing "the" before "facs." I'd also rather avoid two such
> close occurrences of "indicate"; perhaps "By convention, this encoding
> implies that the image indicated by the facs attribute represents . . ."?

Yes


>
>> "The recommended approach to encoding facsimiles is instead to use the
> facs
>> attribute in conjunction with the elements facsimile, surface, and zone,
>> which are also provided by this module."
>
> This sentence immediately follows a paragraph that basically acknowledges
> that for some purposes (specifically, "many straightforward ‘digital
> library’ applications")<pb facs="">  is just fine. Mixed message.

Unfortunately, (or not) this mixed message faithfully represents (I 
claim) divergence of opinion and need within the user community. See 
current debate on TEI-L.


>
> At the bottom of p. 346 we are told that<zone>  "defines a rectangular area
> contained within a surface element," and that restriction is repeated in
> this prose at the bottom p. 352: "Zones need not nest within each other;
> they must however be rectangular, as previously noted." At the top of p.
> 348, though, we are told that "A zone may be rectangular or
> non-rectangular," and the way to define a non-rectangular zone is
> specified. Also, this whole thing makes me wonder why<surface>  must be
> rectangular.


Non-rectangular zones were added recently, and the text needs to be read 
for oversights of this kind. I don't remember anyone arguing for 
non-rectangular surfaces, hitherto. At first blush it seems obviously 
desirable; but less so perhaps at second blush.




>
> Preliminary updates document
>
> At the top is a note saying that this is destined for insertion "after the
> 22nd para in section 11.1," which by my reckoning puts it between ". . .
> which defines its coordinate space." and "In this example, . . . ." I'm
> sure this must be wrong, but I'm curious what the correct place is. A
> little bit farther down, there's a note about the placement of the Bovelles
> example, but I wasn't able to quickly sort things out.
>

You're counting differently from me, I suspect. I mean literally after 
the 22nd <p> element, which puts you between the encoding for the two 
page example and the section beginning "In the following example, we 
discuss a hypothetical digital edition..."


>
> I'm pretty sure it's just a by-product of the way the current HTML
> processing and not material, but I paused over the presence of pointy
> brackets around some element names and not others.

it's a formating artefact. The ones without pointy brackets are not 
defined in the ODD because it's only a partial document.

>
>> "This approach is illustrated in section ?? below."
>
> Since Lou knows as well as or better than anyone that this is in the same
> section (11.1), is the suggestion that it would be bumped to a new section?

No, it's a formatting artefact (and also a useful means for me of 
checking that I have got the cross reference identifier right)

>
>> "Alternatively, if the transcription is intended to do no more than
>> represent the physicality of the document itself . . . ."
>
> Several things about this phrase puzzle me. Why "no more than"? The idea
> that a transcription might represent physicality strikes me as at least
> recondite--I'm not sure what to make of it without some unpacking. Finally,
> in "the document itself" "document" seems ambiguous and I'm not sure what
> "itself" is doing.

I'm trying to draw distinction between the "documentary" and the 
"textual" views. You might have a transcription representing either 
view. Suggestions for improved wording appreciated!

>
>> "<patch>  contains a part of a written surface which was originally
>> physically distinct but became attached to it at the time that one or
> more
>> written zones were created."
>
> Why "written"? Is the time of the creation referred to here the one that
> took place in physical or digital space?

"Written" simply because a patch with no writing on it probably isn't 
interesting. But it could go.

> What I'm starting to worry about,
> I think, is that maybe "surface" is being used for both physical surfaces
> and the ones created by the encoder.

The encoder cannot create surfaces so this is definitely misleading.

For this particular definition,
> though, I'm now thinking that it's probably not helpful (even if it is
> possible) to raise the issue of when the surfaces were created. Why does it
> matter?


How's this as a new definition:

"<patch>  a part of a surface which was originally physically distinct 
but was combined with it at some time prior to some or all of the 
writing on the surface"


>
>> "@binder      describes the method by which a patch is or was connected to
>> the main surface".
>
> I'm not wild about the name of the attribute, but I don't have anything
> better to suggest. If it sticks, though, I suggest getting rid of "method."
> One possibility: "material used to connect a patch to the main surface."

I'm not wild about the name either. But why don't you like "method"? 
Maybe a list of suggested values for this attribute would help us decide 
on its name.


>
>> "@flipping    indicates whether the patch is attached and folded in
> such a
>> way as to provide two writing surfaces".
>
> I definitely dislike this attribute name. No perfect alternatives come to
> mind, but could we at least avoid the participle--"flippable"? Also, the
> description misses the mark (I think). To my mind, whether the thing is
> folded is irrelevant, and from the encoder's/reader's perspective the
> flippable-ness has nothing to do whether I can write on the other side. Of
> the manuscripts I've worked with, lots of non-flippable patches have
> writing on the other side, and some flippable ones are blank on the
> reverse. I suggest something along the lines of "indicates whether the
> patch is attached in such a way sas to allow it to be flipped (turned?
> turned over?), bringing the reverse side into view."

I agree that this needs improvement. Not sure how.


OK, I have to dash. Waiting next instalment with interest!