clarify how to encode short-form citations

[kshawkin]

The Guidelines say that you should "distinguish between a bibliographic reference, which is a self-sufficient description of a bibliographic item, and a bibliographic pointer, which is a short-form citation (e.g. Baxter, 1983)" ( http://www.tei-c.org/release/doc/tei-p5-doc/en/html/CO.html#COBITY ). Just before this statement, the Guidelines give an example of such a short-form citation:

<bibl>Baxter, 1983</bibl>

But then the Guidelines go on to say, "The usual encoding of short-form references such as Baxter, 1983 is not as bibl elements but as cross-references to such elements; see section 3.11.3 Bibliographic Pointers below." In that section ( http://www.tei-c.org/release/doc/tei-p5-doc/en/html/CO.html#COBIXR ), there are examples using ptr and ref. Here's one that involves a page range:

Nelson claims (<ref target="#NEL80">Nelson [1980]</ref> pages 13–37)

Unfortunately, the page range here is not tagged. However, as explained in a posting on TEI-L ( https://listserv.brown.edu/archives/cgi-bin/wa?A2=TEI-L;4eddd8d3.1602 ), there is a use case for being able to extract the page range.

To confuse things more, the element specification for citedRange ( http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-citedRange.html ) gives the following example:

<bibl>
 <ptr target="#mueller01"/>, <citedRange target="http://example.com/mueller3.xml#page4">vol. 3, pp.
   4-5</citedRange>
</bibl>

The Guidelines should be clearer on the recommended way to accomplish this. In particular:

a) Should the whole short-form citation be wrapped in a bibl? b) Should citedRange be used for the page range?

[hcayless]

Agreed. I don't see how short-form citations are not themselves bibliographic references.

My own preference would be that we allow linking a short citation (e.g. in the text) to a full citation (e.g. in the bibliography) using @ref on bibl. I believe there's been discussion about this in the past, and the idea was rejected, but I'm not sure why...

On Wed, Feb 3, 2016 at 8:53 AM, Kevin Hawkins notifications@github.com wrote:

The Guidelines say that you should "distinguish between a bibliographic reference, which is a self-sufficient description of a bibliographic item, and a bibliographic pointer, which is a short-form citation (eg Baxter, 1983)" ( http://wwwtei-corg/release/doc/tei-p5-doc/en/html/COhtml#COBITY ) Just before this statement, the Guidelines give an example of such a short-form citation:

Baxter, 1983

But then the Guidelines go on to say, "The usual encoding of short-form references such as Baxter, 1983 is not as bibl elements but as cross-references to such elements; see section 3113 Bibliographic Pointers below" In that section ( http://wwwtei-corg/release/doc/tei-p5-doc/en/html/COhtml#COBIXR ), there are examples using ptr and ref Here's one that involves a page range:

Nelson claims (Nelson [1980] pages 13–37)

Unfortunately, the page range here is not tagged However, as explained in a posting on TEI-L ( https://listservbrownedu/archives/cgi-bin/wa?A2=TEI-L;4eddd8d31602 ), there is a use case for being able to extract the page range

To confuse things more, the element specification for citedRange ( http://wwwtei-corg/release/doc/tei-p5-doc/en/html/ref-citedRangehtml ) gives the following example:

, vol 3, pp 4-5

The Guidelines should be clearer on the recommended way to accomplish this In particular:

a) Should the whole short-form citation be wrapped in a bibl? b) Should citedRange be used for the page range?

— Reply to this email directly or view it on GitHub https://github.com/TEIC/TEI/issues/1431.

[frederik-elwert]

I also agree that a short-form citation should be regarded as a bibliographic reference, hence I think that <bibl> is appropriate.

I am somewhat torn about having @ref on bibl. I think it could be used if we think of the full bibliography as a canonical reference. I think ptr/ref are a bit more generic. But I also feel one could potentially have both:

<bibl ref="http://dx.doi.org/10.1080/0141987042000280003">
  <ref target="#alba2005">Alba 2005</ref>, pp. <citedRange unit="page">25</citedRange>
</bibl>

So a short reference:

• should always be marked up using bibl,
• could optionally link to a canonical URL using @ref,
• could optionally mark up implicit internal references to a full bibliography using ref/ptr, and
• could optionally mark up a position inside the resource using citeRange.

[lb42]

Presumably everyone is happy with <ref> being used for a short-form reference to somewhere else in the current document (e.g. 'As discussed in <ref target="#section5"/>') or even somewhere else in some other document (e.g. 'As discussed in <ref target="http://mywonderfularticle.xml#section5"/>'). So how exactly are these different from "As discussed in <bibl><ref target="#burnard2016"/>section <citedRange unit="div">5</citedRange></bibl>" (apart from the latter being more verbose) ???

On attributes, if we add @ref to bibl, it really should only be used to supply (as Frederik suggests) a canonical identifier, rather than just a link. Of course, you could envisage adding @target as well.

[laurentromary]

I have the feeling that enforcing <bibl> where<ref> used to be used is quite a break in backward compatibility. I would suggest to focus on better documenting (exemples) <citeRange>

[hcayless]

@lb42: In a couple of ways: 1) a short-form citation isn't really a reference to the long-form citation; it's (usually) a reference to some external resource (not necessarily online); 2) The short-form citation might be all you get (e.g. Hom. Il. 1,1 as a standalone reference).

Referencing a canonical identifier would, I agree be the best case, but if one isn't available, I don't see what's wrong with referencing a fuller citation. And I'm not sure the semantics of @target are quite right...in my mind at least:

@target = "Retrieve the referenced resource here" @ref = "A definition or identity of the referenced thing may be found here."

@ref seems more like what we want. I suppose you could argue that a full bibliographic citation doesn't constitute a definition of a short citation, but in practice, that's kind of how they work. I don't like <ref> for this sort of thing actually, because the short citation isn't referencing the full citation, it's referencing a book or something. It's the wrong sort of link! Though I suppose you could argue the full citation constitutes a sort of redirect...Bibliography is hard.

[lb42]

Sorry, I forgot to allow for markdown making my first comment above meaningless. I've now edited it, to draw attention to the point I am trying to make: there's a cline from <ref> to <bibl> and I'm none too sure where the boundary comes.

[hcayless]

Just realized there is already a related feature request: #1414

[hcayless]

Assigning this and #1414 to Magdalena to progress.

[tuurma]

There is a consensus on adding a @ref on bibl and the example Nelson claims (<ref target="#NEL80">Nelson [1980]</ref> pages 13–37) is to be rewritten to illustrate the use of <bibl> with @ref and <citedRange>

[lb42]

The existing example should stay: we agreed to add a further example using <bibl> with @ref

[tuurma]

After some more considerations, the example is to be presented in both forms: simple one and more elaborate using <citedRange from="11" to "13" unit="page">

[ebeshero]

Example discussed in Council:

Nelson claims (<ref target="#NEL80">Nelson [1980]</ref> pages 13-37) so that it is a bibl reference thus: <bibl ref="#NEL80">Nelson claims (Nelson [1980] <citedRange unit="page" from="13" to ="37">pages 13-37<citedRange></bibl>

[MarjorieBurghart]

I'm jumping in the conversation late!

I really am in two minds about this. As I recently explained on the TEI list, I've had issues figuring out how to encode <ref> which are in the form of a <bibl> because I needed both the elements allowed in <bibl> (author, title...) AND the possibility to link to a full bibliographic description. The solution described in this ticket (adding @ref to <bibl>) would indeed solve my issue, I would get rid of the <ref> totally.

But I have two problems with the proposed solution to the very real problem:

• I am not very comfortable with the addition of yet another alternative way of encoding the same phenomenon
• if the problem is to link a <bibl> to another element, why do we need to add @ref? The generic @ana or @corresp could do the job.
• more importantly, if we add just @ref to <bibl>, it's not enough. Why not @target? And why not @cRef which would really be useful, since, if I'm giving a short form bibliographic reference to a classic, I might want to give both a canonical reference AND a bibliographic reference to the relevant pages/ columns of the most recent or better edition.

I am really wondering why we could not simply say that, when a <ref> takes the form of a short-form bibliographic entry, it is possible to wrap this <bibl> in a <ref>? Like: <ref target=”#NEL80"><bibl>Nelson [1980] <citedRange unit="page" from="13" to ="37">pages 13-37<citedRange></bibl></ref> It seems to me that it would give users the possibility to use the full range of relevant attributes and elements, while being semantically more correct (a short form bibliographic citation IS a ref in the form of a bibl, isn't it?).

[PFSchaffner]

I would add only not to forget the very intensive use of short-form citation made by dictionaries. In creating MED, 20 years ago, we abandoned the TEI model entirely and simply created a structure based on the print structure of the MED (originally OED) "stencil", so called from the fact that it was originallyl stamped on citation slips:

<CIT CD="1405" MD="1450"> <BIBL> <STNCL REF="hyp.54.19990304T151115"> <DATE>c1450(?a1405)</DATE> <AUTHOR>Lydg.</AUTHOR> <TITLE>CBK</TITLE> <MS>Frf 16</MS>``</STNCL> 11</BIBL> <Q>From dreryhed of heuy nyghtis sorowe Nature bad hem ryse..Ageyn the goodly glad grey morowe.</Q> </CIT>

which I imagine nowadays we'd tag something like this:

<cit> <bibl type="stencil" ref="#hyp.54.19990304T151115"> <date> <date type="manuscript" when="1450">c1450</date> <date type="composition" when="1405">(?a1405)</date> </date> <author>Lydg.</author> <title>CBK</title> <msIdentifier>``<idno>Frf 16</idno>``</msIdentifier> </bibl> <biblScope>11</biblScope> <q>From dreryhed of heuy nyghtis sorowe Nature bad hem ryse..Ageyn the goodly glad grey morowe.</q> </cit>

but would omit the @ref when the short-form citation had no listed source (yet) in the bibliography. It is important that otherwise identical forms of citation should be tagged identically, even when one targets a bibliography item and one does not. An optional @ref would seem to allow that.

[MarjorieBurghart]

An optional @ref would seem to allow that

OK, but so would an optional @ana or @corresp, wouldn't they?

[lb42]

I would tag those bibl things nowadays as <ref>s. In the case where they point to something existing they would have a @target . Something like this <ref target="#hyp.54.19990304T151115">hyp.54.19990304T151115</ref> and where they don't yet have a source in the bibliog <ref >hyp.54.19990304T151115</ref>

[PFSchaffner]

To Marjorie: yes, @corresp would work. To Lou, well, I wouldn't treat the arbitrary identifier as the content of <ref>, but I could certainly see capturing the entire 'stencil' as a <bibl>, and then optionally wrapping the <bibl> (or both <bibl> and <biblscope>) in a targeted <ref> when appropriate.

[MarjorieBurghart]

To Marjorie: yes, @corresp would work.

So we can agree that @ref is an unnecessary addition to <bibl>? My point is that adding @ref is unsatisfactory on all counts:

• it's either redundant, since @corresp could serve the same purpose
• or it's not enough, because if you accept that <bibl> might need an @ref, you'll have to admit that @target and @cRef are also necessary. I do not oppose allowing @ref + @cRef + @target on <bibl>, but allowing only @ref would be awkward.

[ebeshero]

@MarjorieBurghart I think @ref on <bibl> can make good sense in some projects that use <bibl> for short-form citations. (My projects could use that, as I currently use @corresp to do the pointing to a canonical entry in a listBibl, and I have never liked having to use @corresp to do the pointing, when I use @ref for that when pointing from persName and placeName elements to listPerson and listPlace entries. Why not be able to use @ref on bibl, too?) I don't think we ever intended here to remove @corresp since that would be quite drastic and break backwards compatibility unnecessarily.

[ebeshero]

So, I guess I lean toward permitting @cRef and @target as well.

[lb42]

But, Elisa, when you use @ ref on persName etc you are referring to an entity from a name. In this case you are saying that this short form bibl describes the same thing as the full bibl in your bibliography. Surely in that situation @corresp is the right choice? And adding three attributes which don't quite do the same job as one we already have does not seem like a good plan to me.

[MarjorieBurghart]

I see two possible routes:

• recommending to wrap references which are short-form bibliographic citations in a <ref>, which already has all the relevant attributes, when those attributes are needed; it is, I believe, semantically satisfying: these short bibliographic citations ARE references;
• allowing @ref, @cRef and @target on <bibl> as well as <ref>

But I'm afraid that allowing only @ref is not the a satisfactory solution.

As a side note, I believe there is a strong argument for authorising @cRef on <bibl>: a biblical citation may correspond to a canonical reference. If you're citing a classical author, you often need to give both a canonical reference (the one that will be useful for an index fontium) and a bibliographic reference (edition, pages, etc.). This may happen even when the bibliographic citation is not semantically a reference. @cRef would make perfect sense here, but that's for another ticket.

[ebeshero]

@MarjorieBurghart @lb42 I, too, like the idea of recommending the <ref> element for those short-form citations for flexibility in processing in the Guidelines.

I'm confused by the distinction between @corresp and @ref since for me, I'm just looking for a handy way to point to the full entry in a canonical list, and in my projects, those lists of people, places, and texts serve similar functions for precise identification and disambiguation. I don't quite understand the difference between "referring to an entity" and "describing the same thing as a full bibl entry": I suppose a bibl is not an "entity" in the same way as the listEntry that gives information about a person or a place would be. I suppose that in cases where there's a cited page range in a short-form bibl, and that page range isn't represented in the full bibl entry (because it's a whole text), there isn't a precise equivalent identity between the short-form bibl and the long-form version. But then, similarly, the name used for a person might not be the same or equivalent to the ones listed in a canonical person entry in a listPerson either, and any given reference would always be representative of only a part of a fuller account rather than an equivalent one-to-one identification. I don't understand the difference really between @ref and @corresp.

[ebeshero]

I suppose this is a frank confession of confusion over the different-but-similar uses of att.canonical and att.global.linking.

[ebeshero]

According to the Guidelines, @corresp seems most meaningfully used to point to two corresponding versions of a text, and one of our examples is a text corresponding to a translation. We also use @corresp to indicate a loose correspondence or relationship of some kind between two person entries and a place entry, working across list-ographies. See http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-att.global.linking.html

That's not at all the situation we've been describing here with referencing a short-form citation with its full bib.

[martindholmes]

I raised an issue about the meaning of @corresp a couple of years ago:

https://github.com/TEIC/TEI/issues/1144

I still think that widely disparate views of what @corresp is for are loose in the community; the definition and examples now reflect that disparity. The definition "points to elements that correspond to the current element in some way" is so vague that it's not surprising that it's interpreted broadly as well as narrowly; but we've now reached a situation in which half the community uses it for all sorts of things, without thinking about it very much (my own practice), whereas the other half is reluctant to use it for anything at all. In this case my contingent would say that <bibl> with @corresp is perfectly fine for pointing to a bibliography entry.

[lb42]

Lots of issues raised here (I was asleep at the time). Let me try to disentangle one or two. Firstly the vexed question of what @corresp means and how it differs from @ref. Martin is right to remind us that @corresp is sometimes abused as a generic "oh kind of linked to in some way" attribute, largely for historical reasons. I disagree however with the implication that this is an iredeemable situation. We can and should make clearer how we think the attribute should be used if we think it has a function not covered elsewhere, and deprecate it if not. I think it should be used to say that this x corresponds with some other x in some way. In the case of a translation, or a version, the meaning of this is clear. Note that the two elements of which the @corresp relationship is being asserted are of the same kind: this sentence corresponds to that other sentence. But that is not the case for @ref : typically with @ref we are asserting this (name) is referring to this (nameable-thing), and it wouldn't make sense to say therefore to say they "correspond" in the sense I am proposing: they are different kinds of thing. And, as I argued before, @corresp is not a directional association: if a@corresp b, then b@corresp a. That's not true of @ref either.

So why am I suggesting @corresp in this specific use case, the short form bibliographic reference? Because (a) both <bibl>Blenkinsop 1985</bibl> and

<bibl>
 <author>Blenkinsop</author> <!-- blah blah blah --><pubDate>1985</pubDate>
<!-- more blah --></bibl> 

are the same kind of thing (b) moreoever they are both ways of describing the same abstract entity : a bibliographic description ergo, they correspond. One does not point to the other, they are both standing in for the same thing.

[lb42]

However, I am only recommending @corresp to keep quiet the people who don't want to wrap their short biblio cites in a <ref>! Let's spell out all the different strategies I might adopt. Assume first theat I have a nice complete bibliography with identifiable entries for all the works I may want to cite in my document. Now how will I represent short form citations to point to entries within it (Let's leave to one side for the moment the question of wanting to reference only part of the entry). I hope we're in agreement that all the following are entirely plausible:

Pigs can in fact whistle <ref target="#BLENK98">(Blenkinsop 1985)</ref> but not sing.
Pigs can in fact whistle <ref target="#BLENK98"/> but not sing.
Pigs can in fact whistle <ref target="#BLENK98"><bibl><author>Blenkinsop, Q.</author><title>De porcibus volantes</title><pubDate>1985<pubDate</bibl></ref> but not sing.

The first two are exactly analogous to what I can currently do with references to other bits of my document, e.g. I can say

see <ref target="#sec3">III. Cross References</ref> for more evidence.
see <ref target="#sec3"/> for more evidence.

expecting (for either) that when my processing software deals with the second case it will be smart enough to construct what is made explicit in the first case

The third case above, the one with a bibl inside the ref, is a consequence of the natural TEI desire to markup structure appropriately wherever it appears. So I might, even in my crude example above, have preferred see "<ref target="#sec3">III. <title>Cross Refeferences</title></ref> for more evidence. " or I might want to go the whole hog (ha) and treat it as a degenerate or stylised <bibl>. I might even tweak my ODD so that I have more or different constraints on this kind of &bibl> from those applicable to the <bibl>s in my bibliogaphy.

If we all agree on that, it's hard to see what there's much here that needs changing .. but perhaps quite a lot that needs to be clarified.

Crucially, I think the decision to add @ref to <bibl> needs to be reconsidered. It is unnecessary and makes life more complicated. On that understanding I hope to be forgiven for re-setting the status of this ticket to orange, sorry.

[MarjorieBurghart]

(b) moreoever they are both ways of describing the same abstract entity : a bibliographic description ergo, they correspond. One does not point to the other, they are both standing in for the same thing.

I beg to (slightly) disagree with that.

In the example you give, yes, they are the same thing. But in other cases, they do not coincide exactly: the short-form is a sub-part of the full bibliographic entry. If your short form is pointing to Marcus Tullius Cicero, De amicitia, VII.23, on p. 56-57 of the C.F.W. Müller edition, published in Leipzig by Teubner in 1884, you're going to have:

• the full bibliographic entry in my bibliography: Marcus Tullius Cicero, Laelius de amicitia, ed. C.F.W. Müller, Leipzig: Teubner, 1884
• a short-form reference in the source notes, looking like: CICERO, De amic., VII.23 (Müller, p. 56-57)

The second is not identifcal to the first, it points to a particular bit of the first, which is (in this case) defined both with a canonical reference of sorts (De amic., VII.23) and a reference to the full description of the edition, including a page range (Müller, p. 56-57).

[lb42]

Marjorie, yes, that is an argument for not using @corresp in this case. But I did say I wasn't addressing this case! If you want to do that, you need to do use <ref> with a <bibl> inside it containing a <biblScope> or <citedRange> or whatever.

[MarjorieBurghart]

We are in agreement on that indeed, Lou.

Now I'm wondering if, at the heart of the issue, there might not be an unformulated problem: we're trying, in cases like the above, to represent a sort of tree-like relationship between bibliographic entries. Something like "this article is actually part of that collection of essays", or "this passage was published on pages x-y of that edition". In other terms, "this bibliographic entry is a daughter of this other one".

[martindholmes]

I don't think inheritance is the relationship; I think in the short-form what you have is an abbreviated form of a full reference that exists elsewhere, followed by an additional level of specificity. It would be unusual to reference an article in the body of a text, while providing only the information about the full anthology in the bibliography (at least, it would be in my experience).

Lou, in your abbreviated example, surely it should be <ptr> rather than <ref>?

see <ptr target="#sec3"/> for more evidence.

[MarjorieBurghart]

I don't think inheritance is the relationship; I think in the short-form what you have is an abbreviated form of a full reference that exists elsewhere, followed by an additional level of specificity.

OK, that would be an argument in favour of using @corresp, even in my Cicero example, then. I can perfectly live with that.

It would be unusual to reference an article in the body of a text, while providing only the information about the full anthology in the bibliography (at least, it would be in my experience).

I don't do that either when I edit texts, but sometimes in secondary literature. Something like "for more information on this topic, readers will find the following works useful: Smith 2010, Smith 2015, Jones 2016."

[tuurma]

@jamescummings do you have any idea if we decided anything during f2f? If it still needs discussion we have to remove it from Dec release I'm afraid.

[hcayless]

@tuurma the minutes from the f2f have:

SubGroup thinks it is daft - you should use <ref> and if not you could use @corresp. Update existing examples to use <ref> and not <bibl>.

(which sounds like @lb42's argument above) I'm not personally convinced by that, and I don't think we arrived at a proper consensus at the meeting. Suggest we remove it from the milestone.

[ebeshero]

F2F subgroup 2 agrees with last subgroup: <ref> or @corresp on <bibl>. Existing examples can be updated to use <ref>.

[jamescummings]

See also #1579

[ebeshero]

F2F: We're going to discuss this at a later meeting, and review Guidelines on canonical referencing, prefix def, bib citations, and short-form citations.

[raffazizzi]

F2F subgroup says we should use <bibl> with @corresp and possibly indicate on Guidelines that short-form citations SHOULD be encoded with <bibl> and corresp.

[ebeshero]

F2F (Victoria 2017): we need examples in the Guidelines to represent when we might use <ref> vs. when we'd use <bibl>. Both should be represented as appropriate, under distinct circumstances.

[MarjorieBurghart]

I gladly offer the example I mentioned earlier:

If your short form is pointing to Marcus Tullius Cicero, De amicitia, VII.23, on p. 56-57 of the C.F.W. Müller edition, published in Leipzig by Teubner in 1884, you're going to have:

• the full bibliographic entry in my bibliography: Marcus Tullius Cicero, Laelius de amicitia, ed. C.F.W. Müller, Leipzig: Teubner, 1884
• a short-form reference in the source notes, looking like: CICERO, De amic., VII.23 (Müller, p. 56-57) The second is not identifcal to the first, it points to a particular bit of the first, which is (in this case) defined both with a canonical reference of sorts (De amic., VII.23) and a reference to the full description of the edition, including a page range (Müller, p. 56-57).

[jamescummings]

For what it is worth, I still think the correct answer is that the full bibliographic entry is marked using <bibl> in your bibliography, and the short-form reference is a reference and thus should be marked up using <ref> in your text. For this I would still like <ref> to allow model.biblPart inside (for things like citedRange).

However, I seem to be being told by Council that while previously they agreed with me that this time they think things like this should always be encoded with <bibl>.

[MarjorieBurghart]

In the current view of the Council, is there something wrong with wrapping a <bibl> in a <ref> ?

[scstanley7]

Update from F2F Tokyo: We are a go to update the prose on this (JC will, despite objections), and add more examples (including ones already provided).

[hcayless]

I have added an example and explanation of using <bibl> with @corresp to capture short-form citations with bibliographic details.