* [PATCH] org-manual: Rewrite opening section in Citation handling
@ 2024-05-06 8:44 Ihor Radchenko
2024-05-10 17:06 ` András Simonyi
0 siblings, 1 reply; 8+ messages in thread
From: Ihor Radchenko @ 2024-05-06 8:44 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 217 bytes --]
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.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-Add-better-opening-description-to-Citatio.patch --]
[-- Type: text/x-patch, Size: 7915 bytes --]
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
[-- Attachment #3: Type: text/plain, Size: 224 bytes --]
--
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>
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] org-manual: Rewrite opening section in Citation handling
2024-05-06 8:44 [PATCH] org-manual: Rewrite opening section in Citation handling Ihor Radchenko
@ 2024-05-10 17:06 ` András Simonyi
2024-05-11 9:56 ` Ihor Radchenko
0 siblings, 1 reply; 8+ messages in thread
From: András Simonyi @ 2024-05-10 17:06 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
Dear Ihor,
thanks for working on this, I agree that the current version,
especially the introduction, was too technical, so that is a very
good direction to take. Some comments on the proposed changes:
> 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.
Hopefully native speakers will chime in, but the phrase "below
snippet" sounds strange to me, I feel that "the snippet below" would
be a better solution. Also, maybe a "the" could be inserted before
"=#+bibliography= database".
> 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).
Perhaps the second part of the sentence would be a bit more precise
along the following lines:
"or with more generic bibliography and citation formats described
using/in the Citation Style Language (=csl= processor)"
and maybe "Citation Style Language" could link to the CSL site
https://citationstyles.org/.
> The default citation processor is =basic= - it works with arbitrary
> export formats and recognized both BiBTeX and CSL bibliographies.
Here I think there is a typo as "recognized" should be "recognizes".
> At least one =PRINT_BIBLIOGRAPHY= keyword must be present in the
> document to render citations on export.
That is not true in general, as the csl processor and most probably
some others too can render citations without a bibliography; there are
even citation styles (typically, note-based ones) that are designed to
work without a bibliography and specify all bibliographic data in
citations. Because of this I suggest removing or at least rewriting
this sentence.
best wishes,
András
On Mon, 6 May 2024 at 10:44, Ihor Radchenko <yantar92@posteo.net> wrote:
>
> 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.
>
>
> --
> 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>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] org-manual: Rewrite opening section in Citation handling
2024-05-10 17:06 ` András Simonyi
@ 2024-05-11 9:56 ` Ihor Radchenko
2024-05-14 7:10 ` András Simonyi
2024-05-14 18:58 ` Rens Oliemans
0 siblings, 2 replies; 8+ messages in thread
From: Ihor Radchenko @ 2024-05-11 9:56 UTC (permalink / raw)
To: András Simonyi; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 898 bytes --]
András Simonyi <andras.simonyi@gmail.com> writes:
> ... Some comments on the proposed changes:
> ...
Thanks for the comments!
See the attached updated version of the patch with all your comments
addressed.
>> At least one =PRINT_BIBLIOGRAPHY= keyword must be present in the
>> document to render citations on export.
>
> That is not true in general, as the csl processor and most probably
> some others too can render citations without a bibliography; there are
> even citation styles (typically, note-based ones) that are designed to
> work without a bibliography and specify all bibliographic data in
> citations. Because of this I suggest removing or at least rewriting
> this sentence.
Right. It is only true in bibtex-based processors, and only when the
citation command tries to create a link to (missing) bibliography
record. I removed this passage completely.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-org-manual-Add-better-opening-description-to-Cita.patch --]
[-- Type: text/x-patch, Size: 8241 bytes --]
From e16e5b2c678a18a772f338162fbfb9d2626b9317 Mon Sep 17 00:00:00 2001
Message-ID: <e16e5b2c678a18a772f338162fbfb9d2626b9317.1715421288.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Mon, 6 May 2024 11:40:18 +0300
Subject: [PATCH v2] 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 | 94 +++++++++++++++++++++++++++++++++-------------
1 file changed, 68 insertions(+), 26 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 3c60f3268..bf9547ae9 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17491,30 +17491,69 @@ * 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 the =#+bibliography=
+database and use it to typeset the exported document in arbitrary
+formats. For example, the snippet below 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 formats
+described using [[https://citationstyles.org/][Citation Style
+Language]] (=csl= processor).
+
+The default citation processor is =basic= - it works with arbitrary
+export formats and recognizes 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
@@ -17568,7 +17607,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]])
@@ -17598,8 +17638,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:
@@ -17628,13 +17670,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;
@@ -17672,8 +17714,8 @@ ** Bibliography printing
: #+print_bibliography:
The bibliography printed by the LaTeX-based export processors
-"bibtex", "natbib" and "biblatex" has a chapter or section heading by
-default, while the "basic" and "csl" processors print the list of
+=bibtex=, =natbib= and =biblatex= has a chapter or section heading by
+default, while the =basic= and =csl= processors print the list of
bibliography entries without a heading.
A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords.
@@ -17686,9 +17728,9 @@ ** Bibliography printing
the different citation export processors. Some export processors do
not support passing options.
-*** Bibliography options in the "biblatex" and "csl" export processors
+*** 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,
@@ -17700,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
[-- Attachment #3: Type: text/plain, Size: 224 bytes --]
--
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>
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] org-manual: Rewrite opening section in Citation handling
2024-05-11 9:56 ` Ihor Radchenko
@ 2024-05-14 7:10 ` András Simonyi
2024-05-14 18:58 ` Rens Oliemans
1 sibling, 0 replies; 8+ messages in thread
From: András Simonyi @ 2024-05-14 7:10 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
Dear All,
On Sat, 11 May 2024 at 11:55, Ihor Radchenko <yantar92@posteo.net> wrote:
> See the attached updated version of the patch with all your comments
> addressed.
Thanks Ihor, the patch looks good to me now!
best wishes,
András
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] org-manual: Rewrite opening section in Citation handling
2024-05-11 9:56 ` Ihor Radchenko
2024-05-14 7:10 ` András Simonyi
@ 2024-05-14 18:58 ` Rens Oliemans
2024-05-17 11:00 ` Ihor Radchenko
1 sibling, 1 reply; 8+ messages in thread
From: Rens Oliemans @ 2024-05-14 18:58 UTC (permalink / raw)
To: Ihor Radchenko, András Simonyi; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 2136 bytes --]
Thanks for the patch, it looks good and is an improvement over the
somewhat terse previous version. I do have some thoughts though so will
chime in. Note that I am not a native speaker, it might be best if we get
extra eyes from a(nother?) native speaker.
Ihor Radchenko <yantar92@posteo.net> writes:
> +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.
In Emacs Info, this renders as
"While see links. are often sufficient ...".
This seems quite unnatural to me. I would suggest using a different way
of referencing (without "see [link].") if possible, or rewording the
sentence otherwise.
> +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~).
Alternatively:
when "following" them using ~org-open-at-point~.
For a more natural sentence?
> +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 formats
> +described using [[https://citationstyles.org/][Citation Style
> +Language]] (=csl= processor).
> +
> +The default citation processor is =basic= - it works with arbitrary
> +export formats and recognizes both BibTeX and CSL bibliographies.
> +
> +More citation processors are distributed as Emacs packages.
These very small paragraphs read a bit clunky to me, I think that it's
better to merge them into a single paragraph.
> - When style is not specified, default style is used
> + When style is not specified, default style (=nil=) specified by the
> + citation processor is used
I am only slightly familiar with Org's citation handling, and this part
of the manual is a bit confusing to me. I wrote a small patch on top of
yours with something that is clearer to me, but perhaps this is unique to
me.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-clarify-default-style.patch --]
[-- Type: text/x-patch, Size: 1351 bytes --]
From 70fe33fe0012c124fd011011ee77e544e18d50ad Mon Sep 17 00:00:00 2001
From: Rens Oliemans <hallo@rensoliemans.nl>
Date: Tue, 14 May 2024 20:45:01 +0200
Subject: [PATCH] org-manual: clarify default style
I don't intend this commit to be merged but instead to be squashed in
the existing patch.
---
doc/org-manual.org | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index 50af99c5b..c2f08be17 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17609,16 +17609,16 @@ identifying a reference in the bibliography.
: [cite/style:common prefix ;prefix @key suffix; ... ; common suffix]
- When style is not specified, default style (=nil=) specified by the
- citation processor is used
+ When =style= is not specified, one of the two default styles are
+ used
- + either the default style specified in =CITE_EXPORT= keyword (see
- [[*Citation export processors]])
+ + 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 using default =nil= style
+ + or, if =CITE_EXPORT= is not set, using the default =nil= style
: [cite:@key] is the same as [cite/nil:@key]
--
2.44.0
[-- Attachment #3: Type: text/plain, Size: 362 bytes --]
Is this understanding of the 'style' specification correct? This is what
I concluded from reading the manual, if it is incorrect, please forgive
me and let me know how exactly I am incorrect, perhaps that can
illuminate this part ;)
Best,
Rens
PS: is such a way of including a patch (that builds upon a discussed
patch) the best way to communicate changes?
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] org-manual: Rewrite opening section in Citation handling
2024-05-14 18:58 ` Rens Oliemans
@ 2024-05-17 11:00 ` Ihor Radchenko
2024-05-18 20:21 ` Rens Oliemans
0 siblings, 1 reply; 8+ messages in thread
From: Ihor Radchenko @ 2024-05-17 11:00 UTC (permalink / raw)
To: Rens Oliemans; +Cc: András Simonyi, emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 964 bytes --]
Rens Oliemans <hallo@rensoliemans.nl> writes:
> Thanks for the patch, it looks good and is an improvement over the
> somewhat terse previous version. I do have some thoughts though so will
> chime in. ...
Thanks! I have incorporated all your suggestions into the new version of
the patch (attached).
>> - When style is not specified, default style is used
>> + When style is not specified, default style (=nil=) specified by the
>> + citation processor is used
>
> I am only slightly familiar with Org's citation handling, and this part
> of the manual is a bit confusing to me. I wrote a small patch on top of
> yours with something that is clearer to me, but perhaps this is unique to
> me.
Your changes look reasonable.
> PS: is such a way of including a patch (that builds upon a discussed
> patch) the best way to communicate changes?
Yes, it is. Applying diff is easy - easier than manually editing the
changes according to comments in the email.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v3-0001-org-manual-Add-better-opening-description-to-Cita.patch --]
[-- Type: text/x-patch, Size: 8606 bytes --]
From 751d73fd0ae00a9a017cd73d5c6c7b2eb7412b5b Mon Sep 17 00:00:00 2001
Message-ID: <751d73fd0ae00a9a017cd73d5c6c7b2eb7412b5b.1715943408.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Mon, 6 May 2024 11:40:18 +0300
Subject: [PATCH v3] 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 | 99 ++++++++++++++++++++++++++++++++--------------
1 file changed, 70 insertions(+), 29 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index e3a2c9b70..920114f70 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -17493,30 +17493,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 links (see [[*Hyperlinks]]) 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 the =#+bibliography=
+database and use it to typeset the exported document in arbitrary
+formats. For example, the snippet below 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 using ~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 formats
+described using [[https://citationstyles.org/][Citation Style
+Language]] (=csl= processor).
+The default citation processor is =basic= - it works with arbitrary
+export formats and recognizes 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
@@ -17570,15 +17608,16 @@ ** Citations
: [cite/style:common prefix ;prefix @key suffix; ... ; common suffix]
- When style is not specified, default style is used
+ When =style= is not specified, one of the two default styles are
+ used
- + either the default style specified in =CITE_EXPORT= keyword (see
- [[*Citation export processors]])
+ + 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 using default =nil= style
+ + or, if =CITE_EXPORT= is not set, using the default =nil= style
: [cite:@key] is the same as [cite/nil:@key]
@@ -17600,8 +17639,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:
@@ -17630,13 +17671,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;
@@ -17674,8 +17715,8 @@ ** Bibliography printing
: #+print_bibliography:
The bibliography printed by the LaTeX-based export processors
-"bibtex", "natbib" and "biblatex" has a chapter or section heading by
-default, while the "basic" and "csl" processors print the list of
+=bibtex=, =natbib= and =biblatex= has a chapter or section heading by
+default, while the =basic= and =csl= processors print the list of
bibliography entries without a heading.
A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords.
@@ -17688,9 +17729,9 @@ ** Bibliography printing
the different citation export processors. Some export processors do
not support passing options.
-*** Bibliography options in the "biblatex" and "csl" export processors
+*** 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,
@@ -17702,10 +17743,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.1
[-- Attachment #3: Type: text/plain, Size: 224 bytes --]
--
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>
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] org-manual: Rewrite opening section in Citation handling
2024-05-17 11:00 ` Ihor Radchenko
@ 2024-05-18 20:21 ` Rens Oliemans
2024-05-20 13:25 ` Ihor Radchenko
0 siblings, 1 reply; 8+ messages in thread
From: Rens Oliemans @ 2024-05-18 20:21 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: András Simonyi, emacs-orgmode
Ihor Radchenko <yantar92@posteo.net> writes:
> Thanks! I have incorporated all your suggestions into the new version of
> the patch (attached).
Thanks, it looks good to me!
> Yes, it is. Applying diff is easy - easier than manually editing the
> changes according to comments in the email.
Great, good to know.
Best,
Rens
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] org-manual: Rewrite opening section in Citation handling
2024-05-18 20:21 ` Rens Oliemans
@ 2024-05-20 13:25 ` Ihor Radchenko
0 siblings, 0 replies; 8+ messages in thread
From: Ihor Radchenko @ 2024-05-20 13:25 UTC (permalink / raw)
To: Rens Oliemans; +Cc: András Simonyi, emacs-orgmode
Rens Oliemans <hallo@rensoliemans.nl> writes:
> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> Thanks! I have incorporated all your suggestions into the new version of
>> the patch (attached).
>
> Thanks, it looks good to me!
Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=3f539bc3d
--
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>
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2024-05-20 13:24 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-05-06 8:44 [PATCH] org-manual: Rewrite opening section in Citation handling Ihor Radchenko
2024-05-10 17:06 ` András Simonyi
2024-05-11 9:56 ` Ihor Radchenko
2024-05-14 7:10 ` András Simonyi
2024-05-14 18:58 ` Rens Oliemans
2024-05-17 11:00 ` Ihor Radchenko
2024-05-18 20:21 ` Rens Oliemans
2024-05-20 13:25 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).