From 89e5bd96a1219e85f8e6be7a6eabb840257b021a Mon Sep 17 00:00:00 2001 Message-ID: <89e5bd96a1219e85f8e6be7a6eabb840257b021a.1714984945.git.yantar92@posteo.net> From: Ihor Radchenko Date: Mon, 6 May 2024 11:40:18 +0300 Subject: [PATCH] org-manual: Add better opening description to "Citation handling" section * doc/org-manual.org (Citation handling): Rewrite the opening paragraphs describing citations using less technical description. The new version aims to ordinary Org mode users and avoids talking about Elisp libraries. (Citations): Unify markup for citation processor names (use verbatim). Mention that at least one #+PRINT_BIBLIOGRAPHY is mandatory to render output. Indicate that default citation style is "nil". --- doc/org-manual.org | 89 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 66 insertions(+), 23 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 1feb5ed60..59663a90f 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -17490,30 +17490,68 @@ * Citation handling #+cindex: citation #+cindex: citation processor -The =oc.el= library provides tooling to handle citations in Org via -"citation processors" that offer some or all of the following -capabilities: +While [[*Hyperlinks][links]] are often sufficient to refer to external +or internal information from Org, they have their limitations when +referring to multiple targets or typesetting printed publications. -- 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. +Org mode provides a more sophisticated markup to "cite" external +resources. For example, consider the following Org mode snippet -To use a "citation processor", the user must load them; for example; +: #+bibliography: citationdata.bib +: +: Org mode is used by various communities [cite:teaching: @orgteaching; +: and TeX: @orgtex]. [cite/author/caps:@orgtex] uses Org mode to simplify +: writing scientific publications, while [cite/author/caps:@orgteaching] +: experiment with Org babel to improve teaching. +: +: #+print_bibliography: -#+begin_src emacs-lisp -(require 'oc-bibtex) -#+end_src +Org mode will gather citation metadata from =#+bibliography= database +and use it to typeset the exported document in arbitrary formats. +For example, below snippet shows ASCII export output. + +: Org mode is used by various communities (teaching: Birkenkrahe, Marcus, +: 2023, and TeX: Somma, Emmanuele F, 2023). Somma, Emmanuele F uses Org +: mode to simplify writing scientific publications, while Birkenkrahe, +: Marcus experiment with Org babel to improve teaching. +: +: Birkenkrahe, Marcus (2023). /Teaching Data Science with Literate +: Programming Tools/, MDPI. +: +: Somma, Emmanuele F (2023). /Simplifying LaTeX with ORG-mode in Emacs/, +: TUGboat volume. + +In addition to export, users can use completion to search and insert +citations from the bibliography (via ~org-cite-insert~). Citations +also act like ordinary links, jumping to the citation metadata when +"following" them (~org-open-at-point~). + +You can customize every aspect (/capability/) of citation handling +using built-in or external /citation processors/. + +Org mode ships with several built-in citation processors tailored to +work with LaTeX export and BiBTeX bibliographies (=bibtex=, +=biblatex=, and =natbib= processors), or with more generic Citation +Style Language bibliographies (=csl= processor). + +The default citation processor is =basic= - it works with arbitrary +export formats and recognized both BiBTeX and CSL bibliographies. + +More citation processors are distributed as Emacs packages. #+vindex: org-cite-activate-processor #+vindex: org-cite-follow-processor #+vindex: org-cite-insert-processor #+vindex: org-cite-export-processor -They can then configure them with ~org-cite-activate-processor~, -~org-cite-follow-processor~, ~org-cite-insert-processor~, and -~org-cite-export-processors~ respectively. +Multiple citation processors can be mixed to meet your preferences. +Configure ~org-cite-activate-processor~, ~org-cite-follow-processor~, +~org-cite-insert-processor~, and ~org-cite-export-processors~ to +select which processor to use for every citation capability: -The included "basic" processor provides all four capabilities. +- 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. ** Citations @@ -17567,7 +17605,8 @@ ** Citations : [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] - When style is not specified, default style is used + When style is not specified, default style (=nil=) specified by the + citation processor is used + either the default style specified in =CITE_EXPORT= keyword (see [[*Citation export processors]]) @@ -17597,8 +17636,10 @@ ** Citation export processors 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]]; + - 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, three other processors target LaTeX and LaTeX-derived formats exclusively: @@ -17627,13 +17668,13 @@ ** Citation export processors : #+cite_export: basic author-year author #+texinfo: @noindent -specifies the "basic" export processor with citations inserted as +specifies the =basic= export processor with citations inserted as author's name and references indexed by author's names and year; : #+cite_export: csl /some/path/to/vancouver-brackets.csl #+texinfo: @noindent -specifies the "csl" processor and CSL style, which in this case +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; @@ -17677,6 +17718,8 @@ ** Bibliography printing A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords. Each of the keywords will trigger printing the bibliography. +At least one =PRINT_BIBLIOGRAPHY= keyword must be present in the +document to render citations on export. The keywords can be used with or without additional options. Options can be used, for example, to print only entries that belong to a @@ -17687,7 +17730,7 @@ ** Bibliography printing *** Bibliography options in the "biblatex" and "csl" export processors -The "biblatex" and "csl" export processors support bibliography +The =biblatex= and =csl= export processors support bibliography options through a property list attached to the =PRINT_BIBLIOGRAPHY= keyword. For example, @@ -17699,10 +17742,10 @@ *** Bibliography options in the "biblatex" and "csl" export processors : #+print_bibliography: :keyword "algebraic logic" :nottype article,book -The "biblatex" export processor accepts all options supported by +The =biblatex= export processor accepts all options supported by BibLaTeX's ~\printbibliography~ command. -The "csl" processor accepts the following options: +The =csl= processor accepts the following options: - =:keyword = :: Print only entries whose keyword field contains all given keywords. -- 2.45.0