Remove the annote field from the data model

[reknih]

Reviewing #218, I was looking into how note and annote/annotation are defined and used by CSL and BibLaTeX and learned that there are big discrepancies.

TL;DR: note and annote mean the reverse in CSL and BibLaTeX, CSL styles mostly use both as if there were no difference

Let's start by seeing what the CSL spec says about both:

annote

Short markup, decoration, or annotation to the item (e.g., to indicate items included in a review);
For descriptive text (e.g., in an annotated bibliography), use note instead

note

Descriptive text or notes about an item (e.g. in an annotated bibliography)

Compare this with the BibLaTeX manual, section 2.2.2:

annotation field (literal)

This field may be useful when implementing a style for annotated bibliographies.
It is not used by all standard bibliography styles. Note that this field is completely unrelated to annotator. The annotator is the author of annotations which are part of the work cited.

note field (literal)

Miscellaneous bibliographic data which does not fit into any other field. The note field may be used to record bibliographic data in a free format. Publication facts such as “Reprint of the edition London 1831” are typical candidates for the note field. See also addendum.

addendum field (literal)

Miscellaneous bibliographic data to be printed at the end of the entry. This is similar to the note field except that it is printed at the end of the bibliography entry.

This shows that when going by spec, CSL's annote is most similar to the BibLaTeX field note and CSL note corresponds to BibLaTeX's annotation (also called annote in legacy BibTeX files). Personally, BibLaTeX's names make more sense to me. Additionally, our interop.rs code did not take this difference into account, but do not worry: the CSL style bibtex.csl that converts a CSL entry to BibTeX code makes the same mistake.

The problem?

Many CSL use the variables with their BibLaTeX semantics, some do a secret third thing. Use of the note variable is 3x as pervasive (31 styles) as annote (10 styles).

Most of the styles using note (American Journal of Sciences, ABNT, Bristol University Press, DIN 1505-2, many Harvard styles, Norma Portuguesa 405, Sorbonne, ...) violate the CSL spec by using it with its BibLaTeX meaning (short note). Some others, such as McGill and SPIE, use note as a fallback field to encode info specific to some entry types. In a unique use, The Pontifical Biblical Institute uses it to replace the issuance information of a publication completely (not unlike the note example in the BibTeX docs). I was only able to find the ISO 690 family of styles and Chicago Annotated using the field as intended by CSL, for narrative notes.

Meanwhile, six styles correctly use the CSL annote field to provide a short note: Antarctic Science, Harvard Univ. of Bath, Society of Biblical Literature, United States International Trade Commission, Univ. Bern - Institut für Theaterwissenschaft, Zeitschrift für Theologie und Philosophie. None of them use it for the BibLaTeX meaning. The Catholic Biblical Association uses both fields in a custom way: the note field to describe a URL, annote is used in another non-standard way: It replaces the citation completely with user-supplied text. This practice originated in this Zotero Forum thread and is also found in the styles of Society of Biblical Literature and the Tyndale Bulletin.

The upshot

CSL authors are confused about the field's meanings. Implementing the data model and BibLaTeX conversions according to spec will yield confusing results and users will need to update their bibliographies depending on the style they use.

Additionally, in the context of Typst, implementing narrative bibliographies in Hayagriva only is a bad experience as Typst's formatting capabilities will be unavailable in any Hayagriva field (except for an escape hatch via math). Instead, Typst should allow printing a single bibliography entry manually, with the user entering their comments below.

The effect of this PR

This PR removes the annote field and gives the note field BibLaTeX semantics. Both BibLaTeX keys will be copied into Hayagriva's note, with note taking precedence over annotation. In terms of CSL, both the note and annote standard variables will yield the Hayagriva note fields. This aligns with what most styles expect.

What breaks?

Most styles will work better after this is merged. However, this PR will break the following styles if note is present:

• Styles that use CSL annote to replace the citations: Catholic Biblical Association, Society of Biblical Literature, and the Tyndale Bulletin
• Styles that use CSL note correctly as annotations (in the sense that the semantics of the field break, they are usable): the ISO 690 family of styles and Chicago Annotated
• Styles that use CSL note to provide fallback info for some types (e.g. interviews) such as SPIE and McGill