Hi, Ihor, Thanks for the comments. I attach a revised patch and reply inline.
> Christian Moe <[email protected]> writes: >> [...] I think Worg rather than the manual might be the place to >> reproduce and update [Tecosaur's] large table of styles/variants, so >> I've taken a different tack here. > > +1 I think I'll make it a section of a new general org-cite tutorial page under worg/tutorials/org-cite/ (making it a dir to have a tidy place for bibfiles etc.). >> +- CSL styles recognize "locators" such as page or chapter numbers in >> + the suffixes to citation keys, and have rules for rendering them. A [...] > > I think it is worth clarifying that locators are only supported when > using ob-csl processors. Otherwise, it may be confused, say, for > oc-basic, that supports CSL bibliographies, but not locators. Clarified. At the bottom of the patch, I have also tidied up the format of the list of locator terms. >> +- =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=. > > These are not supported by all the citation processors. Maybe it is > worth clarifying which processors support which styles. Clarified by adding a shorter list of the other processors and the styles they support (but not the variants), with a footnote about the meaning of =locators= for biblatex. I have not gone into variants here. 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? >> +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 | [...] > Maybe we should provide full style/variant names for better readability. Or maybe we should mix full names and shortcuts to illustrate both options. I've tried that approach here. Regards, 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
