Hi, Here's a patch to document citation styles in the manual, a lack reported by yaca at Org meetup #23. The patch also covers locators.
I have adapted most of this from the commentary in oc-csl.el (the oc-*.el files are a mine of documentation), adding only some descriptive text and a small table with examples of use. To keep the section's list of elements of a citation readable, I have opted to add details after that list rather than inside it. We can discuss if that's a good choice or not. Yaca referenced Tecosaur's blog post (https://blog.tecosaur.com/tmio/2021-07-31-citations.html#cite-styles), which is beautifully done, and I've relied on it myself for a long while. But I think Worg rather than the manual might be the place to reproduce and update his large table of styles/variants, so I've taken a different tack here. There are more changes I'd like to propose for the `Citation handling' chapter. But this is also my first patch against the manual, and my first attempt to write Org for the texinfo exporter, so it needs review before I go on. Yours, Christian
>From 4e9400d72ffc337c06923ab079ca684b9c3a6f6f Mon Sep 17 00:00:00 2001 From: Christian Moe <[email protected]> Date: Mon, 27 Oct 2025 23:25:23 +0100 Subject: [PATCH] org-manual: Document citation styles and locators * doc/org-manual.org (Citations): Mention style variants. Simplify the cite/style syntax example and add an example with a variant. Mention locators in suffixes. Add a table of supported styles, a table of variants, and a table with examples of use. Add a list of locator terms. Add index entries. Brought up by yaca in the October 2025 Org meetup. Reported-by: Ihor Radchenko <[email protected]> Link: https://list.orgmode.org/87ms5cp4j5.fsf@localhost. The listings of styles, variants, and locators have been adapted from the commentary in lisp/oc-csl.el. --- doc/org-manual.org | 91 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 89 insertions(+), 2 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index ff5a569d4..f23a7c6b9 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -17811,6 +17811,7 @@ search for citation keys. One can then insert and edit citations using ~org-cite-insert~, called with {{{kbd(C-c C-x @)}}}. +#+cindex: citation A /citation/ requires one or more citation /key(s)/, elements identifying a reference in the bibliography. @@ -17835,9 +17836,14 @@ identifying a reference in the bibliography. - One can also specify a stylistic variation for the citations by inserting a =/= and a style name between the =cite= keyword and the - colon; this usually makes sense only for the author-year styles. + colon; this usually makes sense only for the author-year + styles. Additionally, one can insert a =/= and a variant name after + the style. + + : [cite/<style>:@key] + : [cite/<style>/<variant>:@key] - : [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] + Supported styles and variants are detailed below. When =style= is not specified, one of the two default styles are used @@ -17852,13 +17858,94 @@ identifying a reference in the bibliography. : [cite:@key] is the same as [cite/nil:@key] +- CSL styles recognize "locators" such as page or chapter numbers in + the suffixes to citation keys, and have rules for rendering them. A + locator starts with a locator term and ends with the last comma or + digit in the suffix, whichever comes last. Locator terms include + "p.", "page", and "chap."; more terms are listed below. In the + following example, the locator is =p. 3-4=, but it might be rendered + "pp. 3--4" or just "3--4" in export, depending on the CSL style. + : [cite:see @Tarski1965 p. 3-4 for an example] + The only mandatory elements are: - The =cite= keyword and the colon. - The =@= character immediately preceding each key. - The brackets surrounding the citation(s) (group). +#+cindex: styles, for citations +Citation styles and variants can be specified by their full name +(e.g., =author/bare=) or abbreviation (e.g., =a/b=). The following +citation styles are supported: + +- default style :: Provide a typical author-date citation in + parentheses. Variants: =bare=, =caps=, and =bare-caps=. + +- =author= (=a=) :: As default, but suppress the year. Variants: + =bare=, =caps=, =full=, and all their combinations. + +- =noauthor= (=na=) :: As default, but suppress author names. Variants: =bare=, + =caps=, and =bare-caps=. + +- =nocite= (=n=) :: Suppress the whole citation (but list the item in + the bibliography). As a special case, =[cite/n:@*]= will cause all + works in the bibliography file(s) to be printed in the + bibliography. Variants: none. + +- =year= (=y=) :: Provide the year only, like =noauthor=, but also suppress + locators. Variant: =bare=. + +- =text= (=t=) :: Provide an author-date citation with the author + outside the parentheses. Variants: =caps=, =full=, and =caps-full=. + +- =title= (=ti=) :: Provide the title only. Variant: =bare=. + +- =locators= (=l=) :: Provide the locator(s) only, e.g., the page + number. Variant: =bare=. + +- =bibentry= (=b=) :: Provide full bibliographic information as an + in-text citation. Variant: =bare=. + +The following variants and their combinations are supported for some +styles: + +- =bare= (=b=) :: Do not enclose the citation in parentheses. + +- =caps= (=c=) :: Capitalize the first word. This is sometimes useful + for last names beginning e.g.\nbsp{}with "von" or "de". + +- =full= (=f=) :: List all author names instead of replacing them with + "et al." + +- =bare-caps= (=bc=) :: Combine =bare= and =caps=. + +- =bare-full= (=bf=) :: Combine =bare= and =full=. + +- =caps-full= (=cf=) :: Combine =caps= and =full=. + +- =bare-caps-full= (=bcf=) :: Combine =bare=, =caps=, and =full=. + +The following table gives some examples of how style variations can be +used and how an citation export processor might render them: + +| =[cite:@dewaal06 p. 5]= | (de Waal et al. 2006, 5) | +| =[cite//bc:@dewaal06 p. 5]= | De Waal et al. 2006, 5 | +| =[cite/a:@dewaal06 p. 5]= | (de Waal et al., 5) | +| =[cite/na:@dewaal06, p. 5]= | (2006, 5) | +| =[cite/t/cf:@dewaal06 p. 5]= | De Waal, Jones, and Smith (2006, 5) | +| =[cite/n:@dewaal06]= | | +| =[cite/l:@dewaal06 p. 5]= | (5) | + +#+cindex: locators +CSL locator terms include "bk.", "bks.", "book", "chap.", "chaps.", +"chapter", "col.", "cols.", "column", "figure", "fig.", "figs.", +"folio", "fol.", "fols.", "number", "no.", "nos.", "line", "l.", +"ll.", "note", "n.", "nn.", "opus", "op.", "opp.", "page", "p.", +"pp.", "paragraph", "para.", "paras.", "¶", "¶¶", "§", "§§", "part", +"pt.", "pts.", "section", "sec.", "secs.", "sub verbo", "s.v.", +"s.vv.", "verse", "v.", "vv.", "volume", "vol.", and "vols.". + ** Citation export processors Org currently includes the following export processors: -- 2.43.0
