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

[Rens Oliemans]

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.

0001-org-manual-clarify-default-style.patch
Description: Text Data

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?