Christian Moe <[email protected]> writes: > Apologies, must have forgotten to delete the old. Here's the right one, > with the misleading footnote removed.
Thanks! See my comments inline. I also attached all my comments in a form of suggested changes on top of your patch. > +- 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] I think that this list is sprawling a bit too much now. Extended clarification may better be moved down, into separate paragraphs. I also reviewed which variants are supported by which processors and incorporated. I think you missed "note" style from oc-basic (I did not yet put it). > The only mandatory elements are: > > - The =cite= keyword and the colon. > - The =@= character immediately preceding each key. > - The brackets surrounding the citation(s) (group). This feels a bit out of scope after elaborate discussion about locators and styles. I moved it up. > +#+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. > ... Compared to the earlier list with examples, this reads much less clearly. I moved the examples right into the list items here. Note that it revealed that some examples are missing. > +#+cindex: locators > +CSL locator terms include > +- "book", "bk.", "bks." > +- "chapter", "chap.", "chaps." > +- "column", "col.", "cols." > ... This is (1) too far from where we discuss locators; (2) feels more like a footnote. I made it such.
>From efcaf9e991682f7f4177e48fa652b50a97af0bd7 Mon Sep 17 00:00:00 2001 Message-ID: <efcaf9e991682f7f4177e48fa652b50a97af0bd7.1763322014.git.yanta...@posteo.net> From: Ihor Radchenko <[email protected]> Date: Sun, 16 Nov 2025 20:38:11 +0100 Subject: [PATCH] doc/org-manual.org (Citations): Suggested edits --- doc/org-manual.org | 213 +++++++++++++++++++++++++-------------------- 1 file changed, 119 insertions(+), 94 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 685adcd92..01c70f573 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -17844,116 +17844,141 @@ ** Citations : [cite/<style>:@key] : [cite/<style>/<variant>:@key] - Support for styles varies between processors. Supported styles and - variants are detailed below. +- The only mandatory elements are: - When =style= is not specified, one of the two default styles are - used + + The =cite= keyword and the colon. + + The =@= character immediately preceding each key. + + The brackets surrounding the citation(s) (group). - + either the default style specified in the =CITE_EXPORT= keyword - (see [[*Citation export processors]]) - - : #+cite_export: basic numeric noauthor/bare - : [cite:@key] is the same as [cite/noauthor/bare:@key] - - + or, if =CITE_EXPORT= is not set, using the default =nil= style - - : [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] +#+cindex: styles, for citations +Support for styles varies between processors. Supported styles and +variants are detailed below. Citation styles and variants can be +specified by their full name (e.g., =author/bare=) or shortcut (e.g., +=a/b=). + +- default style =nil= (<omitted>) :: Provide a typical author-date + citation in parentheses.\\ + Variants: =bare= (=b=), =caps= (=c=), =bare-caps= (=bc=), =full= + (=f=), =bare-full= (=bf=), =caps-full= (=cf=), =bare-caps-full= + (=bcf=).\\ + Support: =basic= (=b=, =c=, =bc=), =csl= (=b=, =c=, =bc=), =natbib= + (all variants), =bibtex= (variants not supported), =biblatex= (=b=, + =c=, =bc=). + + | =[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 | -The only mandatory elements are: +- =author= (=a=) :: As default, but suppress the year.\\ + Variants: =bare= (=b=), =caps= (=c=), =full= (=f=), and all their + combinations.\\ + Support: =basic= (only =c=), =csl= (all variants), =natbib= (=c=, + =f=), =biblatex= (=c=, =f=, =cf=). -- The =cite= keyword and the colon. -- The =@= character immediately preceding each key. -- The brackets surrounding the citation(s) (group). + | =[cite/author:@dewaal06 p. 5]= | (de Waal et al., 5) | + | =[cite/a:@dewaal06 p. 5]= | (de Waal et al., 5) | -#+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: +- =noauthor= (=na=) :: As default, but suppress author names.\\ + Variants: =bare= (=b=), =caps= (=c=), and =bare-caps= (=bc=).\\ + Support: =basic= (only =b=), =csl= (all variants), =natbib= (only + =b=), =biblatex= (only =b=). -- 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=. + | =[cite/noauthor:@dewaal06, p. 5]= | (2006, 5) | + | =[cite/na:@dewaal06, p. 5]= | (2006, 5) | - =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. + works in the bibliography file(s) to be printed in the bibliography.\\ + Variants: none.\\ + Support: =basic=, =csl=, =natbib=, =bibtex=, =biblatex=. + + | =[cite/nocite:@dewaal06]= | <empty> | + | =[cite/n:@dewaal06]= | <empty> | - =year= (=y=) :: Provide the year only, like =noauthor=, but also suppress - locators. Variant: =bare=. + locators.\\ + Variant: =bare=.\\ + Support: =csl=. - =text= (=t=) :: Provide an author-date citation with the author - outside the parentheses. Variants: =caps=, =full=, and =caps-full=. + outside the parentheses.\\ + Variants: =caps= (=c=), =full= (=f=), and =caps-full= (=cf=).\\ + Support: =basic= (only =c=), =natbib= (all variants), =biblatex= + (only =c=). -- =title= (=ti=) :: Provide the title only. Variant: =bare=. + | =[cite/t/cf:@dewaal06 p. 5]= | De Waal, Jones, and Smith (2006, 5) | + +- =title= (=ti=) :: Provide the title only.\\ + Variant: =bare=.\\ + Support: =csl= - =locators= (=l=) :: Provide the locator(s) only, e.g., the page - number. Variant: =bare=. + number.\\ + Variant: =bare= (=b=), =caps= (=c=), =bare-caps= (=bc=).\\ + Support: =csl= (only =b=), =biblatex= (all variants). + + | =[cite/locators:@dewaal06 p. 5]= | (5) | + | =[cite/l:@dewaal06 p. 5]= | (5) | + +- =numeric= (=nb=) :: Provide citation number.\\ + Variant: none.\\ + Support: =basic= - =bibentry= (=b=) :: Provide full bibliographic information as an - in-text citation. Variant: =bare=. + in-text citation.\\ + Variant: =bare=.\\ + Support: =csl= -The following variants and their combinations are supported for some -styles: +Here is the full list of all the variants and their meaning: - =bare= (=b=) :: Do not enclose the citation in parentheses. + + | =[cite//bare:@dewaal06 p. 5]= | de Waal et al. 2006, 5 | + | =[cite//b:@dewaal06 p. 5]= | de Waal et al. 2006, 5 | - =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." - + | =[cite//caps:@dewaal06 p. 5]= | (De Waal et al. 2006, 5) | + | =[cite//c:@dewaal06 p. 5]= | (De Waal et al. 2006, 5) | + - =bare-caps= (=bc=) :: Combine =bare= and =caps=. + + | =[cite//bare-caps:@dewaal06 p. 5]= | De Waal et al. 2006, 5 | + | =[cite//bc:@dewaal06 p. 5]= | De Waal et al. 2006, 5 | +- =full= (=f=) :: List all author names instead of replacing them with + "et al." + + | =[cite//full:@dewaal06 p. 5]= | (de Waal, Jones, and Smith 2006, 5) | + | =[cite//f:@dewaal06 p. 5]= | (de Waal, Jones, and Smith 2006, 5) | + - =bare-full= (=bf=) :: Combine =bare= and =full=. + | =[cite//bare-full:@dewaal06 p. 5]= | de Waal, Jones, and Smith 2006, 5 | + | =[cite//bf:@dewaal06 p. 5]= | de Waal, Jones, and Smith 2006, 5 | + - =caps-full= (=cf=) :: Combine =caps= and =full=. + | =[cite//caps-full:@dewaal06 p. 5]= | (De Waal, Jones, and Smith 2006, 5) | + | =[cite//cf:@dewaal06 p. 5]= | (De Waal, Jones, and Smith 2006, 5) | + - =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= + | =[cite//bare-caps-full:@dewaal06 p. 5]= | De Waal, Jones, and Smith 2006, 5 | + | =[cite//bcf:@dewaal06 p. 5]= | De Waal, Jones, and Smith 2006, 5 | + +When =style= is not specified, one of the two default styles are used + +- either the default style specified in the =CITE_EXPORT= keyword + (see [[*Citation export processors]]) + + : #+cite_export: basic numeric noauthor/bare + : [cite:@key] is the same as [cite/noauthor/bare:@key] + +- or, if =CITE_EXPORT= is not set, using the default =nil= style + + : [cite:@key] is the same as [cite/nil:@key] #+vindex: org-cite-biblatex-styles While the =basic= and =csl= processors format citations directly in @@ -17967,23 +17992,23 @@ ** Citations 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." +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."[fn::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."]. 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] ** Citation export processors -- 2.50.1
-- Ihor Radchenko // yantar92, Org mode maintainer, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92>
