@@ -4954,39 +4954,63 @@ Inline and regular footnotes may be mixed freely.
49544954
49554955#### Extension: `citations` ####
49564956
4957−Markdown citations go inside square brackets and are separated
4958−by semicolons. Each citation must have a key and may optionally
4959−have a prefix, a locator, and a suffix. The citation key
4960−consists of `@` plus the citation identifier, possibly
4961−enclosed in curly braces. If the identifier starts
4962−with a letter, digit, or `_`, followed by zero or more
4963−alphanumerics, `_`, and internal punctuation characters
4964−(`:.#$%&-+?<>~/`), then the curly braces may be omitted.
4965−Identifiers may not contain whitespace characters or unbalanced
4966−curly braces. Here are some examples:
4967−
4968− Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
4969−
4970− Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
4971−
4972− Blah blah [@smith04; @doe99].
4973−
4974− Blah blah [@{https://example.com/bib?name=foobar&date=2000}, p. 33].
4975−
4976−`pandoc` detects locator terms in the [CSL locale files].
4977−Either abbreviated or unabbreviated forms are accepted. In the `en-US`
4978−locale, locator terms can be written in either singular or plural forms,
4979−as `book`, `bk.`/`bks.`; `chapter`, `chap.`/`chaps.`; `column`,
4980−`col.`/`cols.`; `figure`, `fig.`/`figs.`; `folio`, `fol.`/`fols.`;
4981−`number`, `no.`/`nos.`; `line`, `l.`/`ll.`; `note`, `n.`/`nn.`; `opus`,
4982−`op.`/`opp.`; `page`, `p.`/`pp.`; `paragraph`, `para.`/`paras.`; `part`,
4983−`pt.`/`pts.`; `section`, `sec.`/`secs.`; `sub verbo`, `s.v.`/`s.vv.`;
4984−`verse`, `v.`/`vv.`; `volume`, `vol.`/`vols.`; `¶`/`¶¶`; `§`/`§§`. If no
4957+To cite a bibliographic item with an identifier foo, use the
4958+syntax `@foo`. Normal citations should be included in square
4959+brackets, with semicolons separating distinct items:
4960+
4961+ Blah blah [@doe99; @smith2000; @smith2004].
4962+
4963+How this is rendered depends on the citation style. In an
4964+author-date style, it might render as
4965+
4966+ Blah blah (Doe 1999, Smith 2000, 2004).
4967+
4968+In a footnote style, it might render as
4969+
4970+ Blah blah.[^1]
4971+
4972+ [^1]: John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
4973+ Susan Smith, "Flies," *Journal of Insects* (2000);
4974+ Susan Smith, "Bees," *Journal of Insects* (2004).
4975+
4976+See the [CSL user documentation] for more information about CSL
4977+styles and how they affect rendering.
4978+
4979+If a citation key do not start with a letter, digit, or `_`,
4980+and contain only alphanumerics and internal punctuation
4981+characters (`:.#$%&-+?<>~/`), the key must be surrounded
4982+by curly braces, which are not considered part of the key.
4983+In `@Foo_bar.baz.`, the key is `Foo_bar.baz`. The final
4984+period is not *internal* punctuation, so it is not included in
4985+the key. In `@{Foo_bar.baz.}`, the key is `Foo_bar.baz.`, including
4986+the final period. The curly braces are recommended if you use URLs as
4987+keys: `[@{https://example.com/bib?name=foobar&date=2000}, p. 33]`.
4988+
4989+Citation items may optionally include a prefix, a locator, and
4990+a suffix. In
4991+
4992+ Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1].
4993+
4994+The first item (`doe99`) has prefix `see `, locator `pp. 33-35`,
4995+and suffix `and *passim*`. The second item (`smith04`) has
4996+locator `chap. 1` and no prefix or suffix.
4997+
4998+Pandoc uses some heuristics to separate the locator from the
4999+rest of the subject. It is sensitive to the locator terms
5000+defined in the [CSL locale files]. Either abbreviated or
5001+unabbreviated forms are accepted. In the `en-US` locale, locator
5002+terms can be written in either singular or plural forms, as
5003+`book`, `bk.`/`bks.`; `chapter`, `chap.`/`chaps.`; `column`,
5004+`col.`/`cols.`; `figure`, `fig.`/`figs.`; `folio`,
5005+`fol.`/`fols.`; `number`, `no.`/`nos.`; `line`, `l.`/`ll.`;
5006+`note`, `n.`/`nn.`; `opus`, `op.`/`opp.`; `page`, `p.`/`pp.`;
5007+`paragraph`, `para.`/`paras.`; `part`, `pt.`/`pts.`; `section`,
5008+`sec.`/`secs.`; `sub verbo`, `s.v.`/`s.vv.`; `verse`,
5009+`v.`/`vv.`; `volume`, `vol.`/`vols.`; `¶`/`¶¶`; `§`/`§§`. If no
49855010locator term is used, "page" is assumed.
49865011
4987−`pandoc` will use heuristics to distinguish the locator
4988−from the suffix. In complex cases, the locator can be enclosed
4989−in curly braces:
5012+In complex cases, you can force something to be treated as
5013+a locator by enclosing it in curly braces:
49905014
49915015 [@smith{ii, A, D-Z}, with a suffix]
49925016 [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
@@ -4997,13 +5021,26 @@ author is already mentioned in the text:
49975021
49985022 Smith says blah [-@smith04].
49995023
5000−You can also write an in-text citation, as follows:
5024+You can also write an author-in-text citation, by omitting the
5025+brackets, as follows:
50015026
50025027 @smith04 says blah.
50035028
50045029 @smith04 [p. 33] says blah.
50055030
5031+This will cause the author's name to be rendered, followed by
5032+the bibliographical details. Use this form when you want to
5033+make the citation the subject of a sentence.
50065034
5035+When you are using a note style, it is usually better to let
5036+citeproc create the footnotes from citations rather than writing
5037+an explicit note. If you do write an explicit note that
5038+contains a citation, note that normal citations will be put in
5039+parentheses, while author-in-text citations will not. For
5040+this reason, it is sometimes preferable to use the
5041+author-in-text style inside notes, when using a note style.
5042+
5043+[CSL user documentation]: https://citationstyles.org/authors/
50075044[CSL]: https://docs.citationstyles.org/en/stable/specification.html
50085045[CSL markup specs]: https://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields
50095046[Chicago Manual of Style]: https://chicagomanualofstyle.org