Citations

#Declaring a source

cite declares one source under an id. It is written at the top level of the internote, before, between or after the scenes, and renders nothing where it stands.

cite#fs1969(
    authors: Fellegi, I. P. and Sunter, A. B.
    year: 1969
    title: A theory for record linkage
    container: Journal of the American Statistical Association
    pages: 64(328), 1183–1210
    doi: 10.1080/01621459.1969.10501049
)

cite#tufte2001(
    authors: Tufte, E. R.
    year: 2001
    title: The visual display of quantitative information
    publisher: Graphics Press
)

scene{
    Two files that share no identifier can still be matched.
}

authors and title are required; the rest are optional. Every field is printed as written. authors joins names with and, because a semicolon ends the attribute. year is text, so n.d. and 2019a are years. A declaration without authors is refused: node `cite`: required attribute `authors` is missing.

Inside a scene a declaration is refused with the list of what the scene allows: node `cite` is not allowed here. Two declarations with one id are a duplicate-id error.

#Citing it in prose

!cite in the narrative names a declaration by its id and renders as a numbered badge. Hovering the badge shows the full reference; pressing it opens the reference list at that source. locator says where in the source the claim is, and is shown in the badge after the number: 1, p. 1187.

scene{
    Each field is weighed by how often it agrees among true matches against how often it agrees by chance !cite:#fs1969().
    The weights add, so a pair is scored field by field !cite:#fs1969(locator: p. 1187).
}

A citation works anywhere in the narrative — a paragraph, a heading, a list item, a callout's body. In a paragraph, list or table cell on the canvas it is refused, with the reference read as a dataset's: 'cite.ref' refers to '#fs1969', which no @data declares.

The compiler refuses:

• an id the document does not declare, such as !cite:#nobody(): unknown id `#nobody`;
• an id naming something other than a cite, such as a curve declared curve#rise: reference `#rise` targets a `curve`, expected one of: cite.

#The reference list

The reference list is a drawer over the internote, headed References. It opens from the internote's navigation, which shows the action only when the document declares at least one source, and from any badge, which scrolls the list to its own entry.

Sources are numbered in the order the internote first cites them, reading from the top: the first source cited is 1. A source cited five times is one entry and keeps its first number, so adding a citation early in the internote renumbers every source after it. Declarations nothing cites follow the rest under Not cited in the text, in the order they are declared.

Each entry reads authors and year, title, then container in italic, pages and publisher, each only when written. A doi is linked through doi.org, bare or written doi:…; url is linked only when there is no doi. An entry with either link is itself the link.