Ihor Radchenko <[email protected]> writes: > Christian Moe <[email protected]> writes: > >> Thanks for the comments. I attach a revised patch and reply inline. >> ... > > I think you attached the old version of the patch...
Apologies, must have forgotten to delete the old. Here's the right one, with the misleading footnote removed. To summarize the previous discussion, the patch has been amended to: - Clarify that locators are only supported when using csl processor. - Clarified which processors support which styles by adding a shorter list of the other processors and the styles they support (but not the variants). I also added an explanatory paragraph about what the (nat)bib(la)(tex) processors do differently from basic/csl, and mentioning the option of customizing `org-cite-biblatex-styles' for biblatex. Is it clear enough? - Mix full names and shortcuts to illustrate both options in the table with example citations and output. (Was: shortcuts only; you suggested using full names for readability; I suggested illustrating the use of both.) Regards, Christian
>From b7e74139e10bfce8f243571b7f7068ce3c56c86c 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 for the csl processor. Add a table of supported styles, a table of variants, and a table with examples of use for the csl processor. Add a list of what styles are supported by the other processors. Add a list of locator terms. Add index entries. The missing documentation of citation styles was brought up by yaca in the October 2025 Org meetup, see 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 | 131 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 128 insertions(+), 3 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index ff5a569d4..fd5c2af77 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,15 @@ 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] + Support for styles varies between processors. Supported styles and + variants are detailed below. When =style= is not specified, one of the two default styles are used @@ -17852,13 +17859,131 @@ identifying a reference in the bibliography. : [cite:@key] is the same as [cite/nil:@key] - +- When the =csl= processor is used, "locators" such as page references + will be recognized and rendered according to the selected CSL style + (other processors will render them verbatim). A locator is a part + of the citation suffix that 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 =p. 3-4= 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 shortcut (e.g., =a/b=). The following +citation styles are supported by the =csl= processor: + +- 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=. Support: =csl=, =natbib=, =biblatex=. + +- =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 and +their shortcuts can be used, and how the CSL citation export processor +might render them with the default style: + +| =[cite:@dewaal06 p. 5]= | (de Waal et al. 2006, 5) | +| =[cite//bare-caps:@dewaal06 p. 5]= | De Waal et al. 2006, 5 | +| =[cite//bc:@dewaal06 p. 5]= | De Waal et al. 2006, 5 | +| =[cite/author:@dewaal06 p. 5]= | (de Waal et al., 5) | +| =[cite/a:@dewaal06 p. 5]= | (de Waal et al., 5) | +| =[cite/noauthor:@dewaal06, p. 5]= | (2006, 5) | +| =[cite/na:@dewaal06, p. 5]= | (2006, 5) | +| =[cite/nocite:@dewaal06]= | | +| =[cite/l:@dewaal06 p. 5]= | (5) | +| =[cite/t/cf:@dewaal06 p. 5]= | De Waal, Jones, and Smith (2006, 5) | + +Only the =csl= processor supports =year=, =title=, and =bibentry= +styles. The other processors support the following styles besides the +default: + +- =basic= :: =author=, =noauthor=, =text=, and =nocite= +- =bibtex= :: =nocite= +- =natbib= :: =author=, =noauthor=, =text=, and =nocite= +- =biblatex= :: =author=, =noauthor=, =text=, =nocite=, and + =locators= + +#+vindex: org-cite-biblatex-styles +While the =basic= and =csl= processors format citations directly in +the final output format, the =bibtex=, =natbib=, and =biblatex= +processors output corresponding Bib(La)TeX cite commands for further +processing; for example, the =natbib= processor renders +=[cite/author:@Jones]= as ~\citeauthor{Jones}~. With the =biblatex= +processor the resulting commands can be controlled by customizing +`org-cite-biblatex-styles'. Results will depend on the style as well +as the engine used (bibtex or biber), and will vary between +processors. + +#+cindex: locators +CSL locator terms include +- "book", "bk.", "bks." +- "chapter", "chap.", "chaps." +- "column", "col.", "cols." +- "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.", "vols." + ** Citation export processors Org currently includes the following export processors: -- 2.43.0
