From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms1.migadu.com with LMTPS id GGgJOqY4R2YSfwAAe85BDQ:P1 (envelope-from ) for ; Fri, 17 May 2024 12:59:51 +0200 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id GGgJOqY4R2YSfwAAe85BDQ (envelope-from ) for ; Fri, 17 May 2024 12:59:51 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=pBQlopYc; dmarc=pass (policy=none) header.from=posteo.net; 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-Seal: i=1; s=key1; d=yhetil.org; t=1715943590; a=rsa-sha256; cv=none; b=K8ZjPFKteDmV68MP5AhunUOmPYvd/b4sfPI0RU+GsgDbKUU5J2hZvQUXyG+S1ZnopJVqxb Bs2u6ucfUfwAlMDN6NHYmGJij+1UwCVKnZhUyJY+6iwIrCNa7Jn9627JRyk3NyUIMRaWag auN7VxyOX8ifWuzFlIbCjh4unXGjnH7QHEXActjCvV51W23cCp2ApYff3Zso6E9wS4pMoK tYbuA4ujwsKE5BqMYgpm/WKE60J4ZgcxRiPHzxM6fSVd6kmayV0bWkJYdH1Zb4vykmFnT/ KBKJyCCyyctzGiHH4zfqiKJ3qCL1XpTk+qOmRm+HNYgFsoe6saJK/QDn/X6Q/Q== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=pBQlopYc; dmarc=pass (policy=none) header.from=posteo.net; 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=1715943590; 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=OivCAQSVMjtCkTE4Iq37SbNQGcCLBYpDi1vQFBVWlYI=; b=V1jndwlRwYlCYL6B0yiiWldAxw4P2X1oeCRakkvrfzF4PcJv+tqd9G2rdgXEIq5PdC+clI DEjSIIzjt7CyNbAdWqvLAp2X/WVwwzRr25z4vCououNsXinglsLj5msAIHQkD7Y5AxhedF wZTEbUlE3VlzUS3o749LIsgswx65z4TCQC6GaV8PkGF3PJAIT8gY25L1YbgNOf0OWlWOl+ Cu3NpipphHCLsJJP2VC5GIKwMNq3NoyU9zDzxi6iE0Js6ofnSDyi6vb+yCBBI5EDQvP1Ek esxGCXISgVE16ATxnuPLWmJ8YagYjtGE+IF98HAEsWysHoE+f47sE2s03zgU1g== 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 7E5293131C for ; Fri, 17 May 2024 12:59:50 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s7vIS-0000N9-OC; Fri, 17 May 2024 06:58:44 -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 1s7vIQ-0000LU-MC for emacs-orgmode@gnu.org; Fri, 17 May 2024 06:58:42 -0400 Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s7vIL-0003Gk-IS for emacs-orgmode@gnu.org; Fri, 17 May 2024 06:58:41 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 9FAD9240029 for ; Fri, 17 May 2024 12:58:35 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1715943515; bh=Bh90QLy2qiJx9PlN9wywyQmd9kbWPG9voCAqwElAtNc=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: From; b=pBQlopYc5wnUwB3hH+Xk1172zzkAj9wZFiaC02um7byOFTGRLGtpbCxdIlMtuYkod eCnDvdo5WuLlWQMvPZQ5WC9hRN69W8VdIYj0vAMDPe3WLIw3wgWzSiDLw0OSfNPP9y uJaUSZnCFkRXupxJQFJA9fwpU+Z/vO3Xvjb8Y0C5JeT+/9BpM2zHzvKLA5sLPnVS71 Vz8ADNzvgmEPAHpU1cRDbjLhIJTwF9QLBTg7lBiWI2Y6t32R8Rfwobv3A1Y1yvkqlS LkfSRLMvFpi4jt6LPTpTy0S1IQ64YJ53pi85CJeJAsu5hgswuptYcYIBHO87xLZ2K9 iOnnDG5CD+LQA== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4VgkTk69Bsz6tw5; Fri, 17 May 2024 12:58:34 +0200 (CEST) From: Ihor Radchenko To: Rens Oliemans Cc: =?utf-8?Q?Andr=C3=A1s?= Simonyi , emacs-orgmode@gnu.org Subject: Re: [PATCH] org-manual: Rewrite opening section in Citation handling In-Reply-To: <87wmnwrzk2.fsf@rensoliemans.nl> References: <87a5l3wcqf.fsf@localhost> <87ikzkvfhb.fsf@localhost> <87wmnwrzk2.fsf@rensoliemans.nl> Date: Fri, 17 May 2024 11:00:16 +0000 Message-ID: <87eda0aekf.fsf@localhost> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=185.67.36.65; envelope-from=yantar92@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 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_MED=-2.3, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_SBL_A=0.1 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-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Queue-Id: 7E5293131C X-Migadu-Scanner: mx12.migadu.com X-Migadu-Spam-Score: -9.58 X-Spam-Score: -9.58 X-TUID: XVUfA1FYrM1b --=-=-= Content-Type: text/plain Rens Oliemans 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. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=v3-0001-org-manual-Add-better-opening-description-to-Cita.patch >From 751d73fd0ae00a9a017cd73d5c6c7b2eb7412b5b Mon Sep 17 00:00:00 2001 Message-ID: <751d73fd0ae00a9a017cd73d5c6c7b2eb7412b5b.1715943408.git.yantar92@posteo.net> From: Ihor Radchenko 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 = :: Print only entries whose keyword field contains all given keywords. -- 2.45.1 --=-=-= Content-Type: text/plain -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at --=-=-=--