Re: [PATCH] org-manual: Rewrite opening section in Citation handling

[András Simonyi]

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>