From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms1.migadu.com with LMTPS id uEMTHnm0Q2ZO0gAAe85BDQ:P1 (envelope-from ) for ; Tue, 14 May 2024 20:59:05 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id uEMTHnm0Q2ZO0gAAe85BDQ (envelope-from ) for ; Tue, 14 May 2024 20:59:05 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=rensoliemans.nl header.s=soverin header.b=ObPx93kc; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1715713145; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=PYdJj+nSaRinic3uSD8ZPBoJOGtnkz8uwZlTJxlx31g=; b=rltUWEbbzabmWgIBgtlRfh0i+uefN1c73U5zGuxH6JSqdCS9+9T3MMpMVE90W4SCBxdPRr CkX+nffgTaXVuf0aScwQxwX3pXzXLkPJQK/iwJJeqRY0wXNFacQvWzZ5+uNrAxh4S86pMb YiiTXluvJ65FvVuBhU7nW32V/k2+Q3UZ3yPl63+QYr8yzWIAC1aKkKi2+1aVm0DTjeRfQY anbiW2Py8iEY54QMHkw2s4VohO5vS/CVQ1j2BL9ebUeh55bH36JgYcYAmo6K/cvtwcT2YM 5sItve7Cy61nfokdDCGzX/8AHHHKQDt0z5756ftqDgCnCgT3zh6m5wp3gN/u7w== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1715713145; a=rsa-sha256; cv=none; b=opHht3Y8UTMxLjx+pE/ggxO5CIqwgetmyK00Uf0lz/XvwJB/33rHY0PaeP/r2VAa8txdtr RsAqNU3qUDgyS6Em37oedEkDA6HIZ1hJo4YP0bIRnGN2nLYX23iBrroMIlRB1Umuf52mWl kgg23xpnfvHSEATAdxvEvmAqdsSvN0M3F8LvJJk3L2dEkVEmkE8sJ2Ek7WBC3c89v+yuVT WWx8cEwnwGU6p246NATerzbtxw17o1MKml7bOBrX7onSuBLcYzLlQIYse6Zh8p/xIYdlzg /qopZf+c/uKpwBZNXLJB+WkXS71zusofPdJTVEKFARe+drlENQVqjJeyNaY5Bg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=rensoliemans.nl header.s=soverin header.b=ObPx93kc; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 16C69B8F0 for ; Tue, 14 May 2024 20:59:05 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s6xLw-0001JW-S0; Tue, 14 May 2024 14:58:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s6xLt-0001JJ-31 for emacs-orgmode@gnu.org; Tue, 14 May 2024 14:58:17 -0400 Received: from outbound.soverin.net ([2a10:de80:1:4092:b9e9:2292:0:1]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1s6xLo-0007yU-2T for emacs-orgmode@gnu.org; Tue, 14 May 2024 14:58:15 -0400 Received: from smtp.soverin.net (c04cst-smtp-sov02.int.sover.in [10.10.4.100]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by outbound.soverin.net (Postfix) with ESMTPS id 4Vf5GR382CzVS; Tue, 14 May 2024 18:58:07 +0000 (UTC) Received: from smtp.soverin.net (smtp.soverin.net [10.10.4.100]) by soverin.net (Postfix) with ESMTPSA id 4Vf5GQ1HhxzKP; Tue, 14 May 2024 18:58:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=rensoliemans.nl; s=soverin; t=1715713087; bh=xh1JZZ1wmJMSXSOA0maCDU7DaqaQlao5RPZpSSw40ig=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=ObPx93kcnBLfIgSNcxQRjkSB5gHl4PHrD3TqfhcyHdz+q/qA8qaOLFfJT8hFoXsM8 WqWXBohk6nkFto2pw2vh+j1JAQ3q3K3VpyHvWA7M9iw0WNVvizlVcDbQawYv/MtvqN jEjkUQNLTwFG+9rESYejjr7Y7tjLAV5ZEvDqKfPC2AKFevs0MdPuJJi/CU9zjjhfGT YtUKUE1A1es9QXGIcSNrmsE17M1BG5v8rB5Knpi9mg/gXvLORSWXiN4FkYaCEno053 a5waf9rxQQjoLURFwWb7nXujzv5C0ZFw+MWrbfOTKNaxI3ferMY5FUiaDyXmpYGam9 BaFmvPk+KiM/g== From: Rens Oliemans To: Ihor Radchenko , =?utf-8?Q?Andr=C3=A1s?= Simonyi Cc: emacs-orgmode@gnu.org Subject: Re: [PATCH] org-manual: Rewrite opening section in Citation handling In-Reply-To: <87ikzkvfhb.fsf@localhost> References: <87a5l3wcqf.fsf@localhost> <87ikzkvfhb.fsf@localhost> Date: Tue, 14 May 2024 20:58:05 +0200 Message-ID: <87wmnwrzk2.fsf@rensoliemans.nl> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=2a10:de80:1:4092:b9e9:2292:0:1; envelope-from=hallo@rensoliemans.nl; helo=outbound.soverin.net X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -2.47 X-Spam-Score: -2.47 X-Migadu-Queue-Id: 16C69B8F0 X-Migadu-Scanner: mx11.migadu.com X-TUID: ot8iuRhw8QIt --=-=-= Content-Type: text/plain 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 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. --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-org-manual-clarify-default-style.patch >From 70fe33fe0012c124fd011011ee77e544e18d50ad Mon Sep 17 00:00:00 2001 From: Rens Oliemans 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 --=-=-= Content-Type: text/plain 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? --=-=-=--