Making bibl, and others, member of att.canonical.

[raffazizzi]

First pass at addressing #2392: Made bibl, biblFull, and biblStruct members of att.canonical. Ajusted the guidelines to reflect this addition and clarified uses of bibl vs ref.

[sydb]

I think the PR is good enough as is, but the wording in CO could be improved. I think it is better to make it explicitly clear that, even here, @key and @ref perform the same function, just in different ways. Thus something like:

<p>Bibliographic references encoded with <gi>bibl</gi>,
<gi>biblFull</gi>, or <gi>biblStruct</gi> may link to an alternate,
likely more detailed, bibliographic reference to the same resource
using either the <att>ref</att> or <att>key</att> attribute from
<ident type="class">att.canonical</ident>. The <att>ref</att>
attribute performs this linking function using a URI that points to an
XML element either within or outside the TEI document, as shown in the
following example:
<egXML xmlns="http://www.tei-c.org/ns/Examples" xml:id="COBITY-egXML-bibref" source="#NONE">
  <bibl ref="https://search.worldcat.org/title/song-of-achilles/oclc/911117343"><title>The song of Achilles</title> by <author>Madeline Miller</author>.</bibl>
</egXML>
The <att>key</att> attribute, on the other hand, performs this linking
function using an identifier from a project-defined scheme as demonstrated here:
<egXML xmlns="http://www.tei-c.org/ns/Examples" xml:id="COBITY-egXML-bibkey" source="#NONE">
  <bibl key="Homer_Iliad.16">Book 16 of <author>Homer</author>'s <title>Iliad</title>.</bibl>
</egXML>
These bibliographic elements (<gi>bibl</gi>, <gi>biblFull</gi>, and
<gi>biblStruct</gi>) are not intended, even with the <ident
type="class">att.canonical</ident> attributes, to be used for encoding
bibliographic pointers (short-form citations); for that purpose, see
section <ptr target="#COBIXR"/> below.</p>

[sydb]

If we use spaces inside the value of @key we probably should explain that the Guidelines take no position on whether the value is three separate references ("Homer", "Iliad", and "16") or one reference ("Homer Iliad 16"). Personally, I would prefer to just use "HomerIliad16" or "Homer_Iliad_16" or some such.

[raffazizzi]

The only other place where this is shown is the exemplum for @key in att.canonical and this is not explained. I think it would just add bloat and confuse the reader at this point.

[raffazizzi]

(at least from running the XPath //*[local-name()='egXML']//*[@key]/@key on P5/Source)

[sydb]

Not sure I understand you, here. Yes, there is only one other exemplified case of @key that contains a space (I used //teix:*/@key[ contains( normalize-space(.), ' ') ] myself :-), which case is in the tagdoc for att.canonical, and is immediately followed by an annotation that includes “No particular syntax is proposed for the values of the @key attribute, since its form will depend entirely on practice within a given project.”.

Are you thinking that explanation is sufficient, and thus we do not need to explicitly point out here that space may or may not be a magic separation character, depending on the “practice within” the project? That seems perfectly reasonable, although I disagree.

Or are you thinking that the explanation in att.canonical does not explicitly mention that spaces (or anything else, for that matter) might be interpreted as magic separation characters, and therefore it should not be explained anywhere else, either?

Or are you thinking that the explanation in att.canonical does not explicitly mention that spaces might be interpreted as magic separation characters, and therefore they cannot be used as separation characters? (In which case I think you are just wrong — the internal syntax of a key, including separation characters that might be used to separate multiple values on a single @key, are up to the project IMHO.)

[raffazizzi]

The first: that explanation is sufficient and it doesn't seem useful to also add it in the guidelines in this section, since it's not specifically about att.canonical. Or I feel like we may then want to do the same when other members are discussed in the guidelines. What makes a discussion of bibliographical references the place to explain how the data type for @key works?

[raffazizzi]

Perhaps a way out of this is to follow your suggestion to not introduce spaces. I modelled it after the example in the specs, but it may be unwise to emulate it here.

[raffazizzi]

Thanks @sydb . I made some adjustments to the prose in response to your suggested rewording. I in particular excluded:

• "may link to an alternate, likely more detailed". "Alternate" doesn't strike me as quite correct here because I don't think the reference implies this OR another definition.
• "a URI that points to an XML element either within or outside the TEI document". AFAIK a URI can point to any kind of resource on the web. In fact, the example points to an HTML document.

Let me know what you think.

[sydb]

(In reverse order.)

---

Oh, you are absolutely right about the XML element being way too specific. Yours is much better, although I am not too fond of “definition”, since a bibliographic entry does not define anything, but rather describes it, supposedly well enough that the reader could find it (on the web, in a library, in a bookstore, by asking the publisher, whatever). Hence my “performs this linking function” bit. So, combining the two:

The <att>ref</att> attribute performs this linking function using a URI that may point either
within or outside the TEI document, as shown in the following example:

---

OK, but if we do not say “alternate” then running right into “likely” seems really clumsy. So I would push for one of

• “… may link to a different, likely more detailed, bibliographic reference …”
• “… may link to a more detailed bibliographic reference …”
• “… may link to some other bibliographic reference …”

[lb42]

Fwiw that usage of "likely" is markedly amerenglish and thus breaks the rockall convention

[sydb]

Oh. Didn’t know that. What would a Brit say instead of “likely”, there? (Is it the particular word “likely” or the sentence structure that puts an adverb there that is abnormal in en-GB?)

[jamescummings]

I'm assuming the discussion about the semantics of whitespace here only applies to @key because we already most certainly take a position on this with regard to @ref. For that we say "If more than one is supplied the implication is that the name identifies several distinct entities." (e.g. "the Browns"). Just checking.

[raffazizzi]

@lb42 okey dokey. How's "<gi>biblStruct</gi> may link to a another, most likely more detailed, bibliographic reference"?

[lb42]

Not much better to my ear. Try Possibly or probably Sent from Outlook for Android<https://aka.ms/AAb9ysg>

…

________________________________ From: Raff Viglianti ***@***.***> Sent: Saturday, January 18, 2025 6:32:54 PM To: TEIC/TEI ***@***.***> Cc: Lou Burnard ***@***.***>; Mention ***@***.***> Subject: Re: [TEIC/TEI] Making bibl, and others, member of att.canonical. (PR #2655) @lb42<https://github.com/lb42> okey dokey. How's "<gi>biblStruct</gi> may link to a another, most likely more detailed, bibliographic reference"? — Reply to this email directly, view it on GitHub<#2655 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAFBJ5BLJIHYHENV3EWYI3T2LKM5NAVCNFSM6AAAAABVKV7JN2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKOJZHAZDEMJTGY>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[raffazizzi]

@jamescummings I switched to a less controversial example in order to circumvent this issue :)
@lb42 "possibly" sounds good to me.

Are we good to go? @ebeshero do you want to chime in, if able?

[lb42]

"may link to a another, possibly more detailed, bibliographic reference to the same resource using" is not quite right though is it?

…

________________________________ From: Raff Viglianti ***@***.***> Sent: Saturday, January 18, 2025 6:39 PM To: TEIC/TEI ***@***.***> Cc: Lou Burnard ***@***.***>; Mention ***@***.***> Subject: Re: [TEIC/TEI] Making bibl, and others, member of att.canonical. (PR #2655) @jamescummings<https://github.com/jamescummings> I switched to a less controversial example in order to circumvent this issue :) @lb42<https://github.com/lb42> "possibly" sounds good to me. Are we good to go? @ebeshero<https://github.com/ebeshero> do you want to chime in, if able? — Reply to this email directly, view it on GitHub<#2655 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAFBJ5HCL3EJI7AVTDR7YJD2LKNWZAVCNFSM6AAAAABVKV7JN2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKOJZHAZDQNBQGM>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[raffazizzi]

@lb42 if that doesn't sound quite right, then I would just remove the aside. IMO the important piece of information here is that the link is to another bibliographic reference to the same resource. Whether it's more, less, or equally detailed.

[lb42]

For "may link to a another, possibly more detailed, bibliographic reference to the same resource using" please read
"may link to another, possibly more detailed, bibliographic reference for the same resource using"

[raffazizzi]

I'm not a native speaker so I would have to trust you on this one, but I'm pretty sure it's "a reference to something", rather than "a reference for something". Can we get a second opinion from a British English user? @jamescummings ?

[lb42]

So long as you get rid of the "a another" I don't mind!

[raffazizzi]

@lb42 oh I see! Fixed.

[ebeshero]

@raffazizzi I'm reviewing this one in a couple of hours...sorry for my delay!

[ebeshero]

I ran tests, built Guidlines and Exemplars (to test the new tei_all.rng on a sample file with @ref on <bibl>, and it all checks out.

I just have one wording revision here, and I think I'll just push that to branch and make sure you're okay with it... @raffazizzi

[ebeshero]

@raffazizzi Here, I think I would modify the phrasing slightly to avoid the word "links." I'd also change "externally-" to "external". Maybe something like this:

The <att>key</att> attribute, on the other hand, associates a bibliographical reference to an external or project-defined identifier, as demonstrated here:

[ebeshero]

This part looks good to me!

[raffazizzi]

@ebeshero sounds good to me! Please merge if you're able, thanks!

[ebeshero]

I just pushed a couple of small phrasing revisions--and am happy to approve this PR!

[ebeshero]

@raffazizzi Will do--waiting for it to pass tests here on GitHub first, and will merge afterwards!