From 3b4ab1c3e4f1ea41a39a9c0e391a8640c8aaea87 Mon Sep 17 00:00:00 2001 From: Bruce D'Arcus Date: Tue, 28 Sep 2021 06:59:20 +0200 Subject: [PATCH] doc/org-manual.org (Citations): Enhance * doc/org-manual.org (Citations): Enhance. This is based on a preliminary draft provided by Emmanuel Charpentier. --- doc/org-manual.org | 141 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 110 insertions(+), 31 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 96f55616f..4ebc315cb 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -16515,43 +16515,122 @@ keywords. :END: #+cindex: citation -Org 9.5 provides a new library =oc.el= which provides tooling to -handle citations in Org, e.g., activate, follow, insert, and export -them, respectively called "activate", "follow", "insert" and "export" -capabilities. Libraries responsible for providing some, or all, of -these capabilities are called "citation processors". +As of Org 9.5, a includes a new library =oc.el= provides tooling to +handle citations in Org via "citation processors" that offer some or +all of the following capabilities: -Such processors are defined using ~org-cite-register-processor~. -Using this function, it is possible, in addition to giving it a name, -to attach functions associated to capabilities. As such, a processor -handling citation export must set the ~:export-citation~ property to -an appropriate function. Likewise, "activate" capability requires an -appropriate ~:activate~ property, "insert" requires ~:insert~ property -and, unsurprisingly, "follow" capability implies ~:follow~ property. +- "activate" :: Fontification, tooltip preview, etc. +- "follow" :: At-point actions on citations via ~org-open-at-point~. +- "insert" :: Add and edit citations via ~org-cite-insert~. +- "export" :: Via different libraries for different target formats. -As a user, the first thing to do is setting a bibliography, either +The user can configure these with ~org-cite-active-processor~, +~org-cite-follow-processor~, ~org-cite-insert-processor~, and +~org-cite-export-processors~ respectively. + +The included "basic" processor provides all four capabilities. + +** Citations + +Before adding citations, first set one-or-more bibliographies, either globally with ~org-cite-global-bibliography~, or locally using one or -more "bibliography" keywords. Then one can select any registered -processor for each capability by providing a processor name to the -variables ~org-cite-activate-processor~ and -~org-cite-follow-processor~. +more "bibliography" keywords. -The "export" capability is slightly more involved as one need to -select the processor providing it, but may also provide a default -style for citations and bibliography. Also, the choice of an export -processor may depend of the current export back-end. The association -between export back-ends and triplets of parameters can be set in -~org-cite-export-processors~ variable, or in a document, through the -"cite_export" keyword. +#+begin_example +#+bibliography: SomeFile.bib +#+bibliography: /some/other/file.json +#+bibliography: "/some/file/with spaces/in its name.bib" +#+end_example -Eventually, this library provides some tools, mainly targeted at -processor implementors. Most are export-specific and are located in -the "Tools only available during export" and "Tools generating or -operating on parsed data" sections. +One can then insert and edit citations using ~org-cite-insert~, called +with {{{kbd(M-x org-cite-insert)}}}. -This section of this manual will be enhanced with more practical -information. In the meantime, if you need help, please send an email -to the mailing list at =emacs-orgmode@gnu.org=. +A /citation/ requires one or more citation /key(s)/, elements +identifying a reference in the bibliography. + +- Each citation is surrounded by brackets and uses the =cite= type. + +- Each key starts with the character =@=. + +- Each key can be qualified by a /prefix/ (e.g. "see ") and/or a + /suffix/ (e.g. "p. 123"), giving informations useful or necessary fo + the comprehension of the citation but not included in the reference. + +- A single citation can cite more than one reference ; the keys are + separated by semicolons ; the formatting of such citation groups is + specified by the style. + +- 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 usially makes sense only for the author-year styles. + +#+begin_example +[cite/style:common prefix ;prefix @key suffix; ... ; common suffix] +#+end_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). + +** Citation export processors + +Org currently includes the following export processors: + +- Two processors can export to a variety of formats, including =latex= + (and therefore =pdf=), =html=, =odt= and plain (UTF8) text: + + - basic :: a basic export processors, well adapted to situations + where backward compatibility is not a requirement and formatting + needs are minimal; + + - csl :: this export processor uses format files written in [[https://en.wikipedia.org/wiki/Citation_Style_Language][Citation + Style Language]] via [[https://github.com/andras-simonyi/citeproc-el][citeproc-el]]; + +- In contrast, two other processors target LaTeX and LaTeX-derived + formats exclusively: + + - natbib :: this export processor uses =bibtex=, the historical + bibliographic processor used with LaTeX, thus allowing the use of + data and style files compatible with this processor (including a + large number of publishers' styles). It uses citation commands + implemented in the LaTeX package =natbib=, allowing more stylistic + variants that LaTeX's =\cite= command. + + - biblatex :: this backend allows the use of data and formats + prepared for =biblatex=, an alternate bibliographic processor used + with LaTeX, which overcomes some serious =bibtex= limitations, but + has not (yet?) been widely adopted by publishers. + +The =#+cite_export:= keyword specifies the export processor and the +citation (and possibly reference) style(s); for example (all arguments +are optional) + +#+begin_example +#+cite_export: basic author author-year +#+end_example + +specifies the "basic" export processor with citations inserted as +author's name and references indexed by author's names and year; + +#+begin_example +#+cite_export: csl /some/path/to/vancouver-brackets.csl +#+end_example + +specifies the "csl" processor and CSL style, which in this case +defines numeric citations and numeric references according to the +=Vancouver= specification (as style used in many medical journals), +following a typesetting variation putting citations between brackets; + +#+begin_example +#+cite_export: natbib kluwer +#+end_example + +specifies the "natbib" export processor with a label citation style +conformant to the Harvard style and the specification of the +Wolkers-Kluwer publisher; since it relies on the =bibtex= processor of +your LaTeX installation, it won't export to anything but PDF. * Working with Source Code :PROPERTIES: