From: Rens Oliemans <hallo@rensoliemans.nl>
To: "Ihor Radchenko" <yantar92@posteo.net>,
"András Simonyi" <andras.simonyi@gmail.com>
Cc: emacs-orgmode@gnu.org
Subject: Re: [PATCH] org-manual: Rewrite opening section in Citation handling
Date: Tue, 14 May 2024 20:58:05 +0200 [thread overview]
Message-ID: <87wmnwrzk2.fsf@rensoliemans.nl> (raw)
In-Reply-To: <87ikzkvfhb.fsf@localhost>
[-- 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?
next prev parent reply other threads:[~2024-05-14 18:59 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
2024-05-17 11:00 ` Ihor Radchenko
2024-05-18 20:21 ` Rens Oliemans
2024-05-20 13:25 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87wmnwrzk2.fsf@rensoliemans.nl \
--to=hallo@rensoliemans.nl \
--cc=andras.simonyi@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=yantar92@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).