[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH] org-manual: Rewrite opening section in Citation handling
From: |
Ihor Radchenko |
Subject: |
[PATCH] org-manual: Rewrite opening section in Citation handling |
Date: |
Mon, 06 May 2024 08:44:56 +0000 |
Hi,
The current version of Citation handling section of the manual is rather
technical. I tried to rewrite it aiming for ordinary users not familiar
with Org mode internals.
Please, let me know if it reads better.
>From 89e5bd96a1219e85f8e6be7a6eabb840257b021a Mon Sep 17 00:00:00 2001
Message-ID:
<89e5bd96a1219e85f8e6be7a6eabb840257b021a.1714984945.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
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 <keyword(,keyword2...)>= :: Print only entries whose
keyword field contains all given keywords.
--
2.45.0
--
Ihor Radchenko // yantar92,
Org mode contributor,
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>
- [PATCH] org-manual: Rewrite opening section in Citation handling,
Ihor Radchenko <=
- Re: [PATCH] org-manual: Rewrite opening section in Citation handling, András Simonyi, 2024/05/10
- Re: [PATCH] org-manual: Rewrite opening section in Citation handling, Ihor Radchenko, 2024/05/11
- Re: [PATCH] org-manual: Rewrite opening section in Citation handling, András Simonyi, 2024/05/14
- Re: [PATCH] org-manual: Rewrite opening section in Citation handling, Rens Oliemans, 2024/05/14
- Re: [PATCH] org-manual: Rewrite opening section in Citation handling, Ihor Radchenko, 2024/05/17
- Re: [PATCH] org-manual: Rewrite opening section in Citation handling, Rens Oliemans, 2024/05/18
- Re: [PATCH] org-manual: Rewrite opening section in Citation handling, Ihor Radchenko, 2024/05/20