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 0CWCKMRAP2Y02gAAe85BDQ:P1 (envelope-from ) for ; Sat, 11 May 2024 11:56:20 +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 0CWCKMRAP2Y02gAAe85BDQ (envelope-from ) for ; Sat, 11 May 2024 11:56:20 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=qoLyzGAR; 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=1715421380; a=rsa-sha256; cv=none; b=UsS5bjZbUpyH/8Bbl992D1oI87l+1RW6Pba5fNOO0nV/g+wa0Famy67c0RbRxLrt2CFh7n 7lDNZQ1Zi8O/sMf6AyQhG/pMDHCJRP08p8umIYq3IK8Jx2cay5dRSvARfrplvQIxygTQ76 pEeAADc3SsAeBvxT0Gc2AHuD83xUo7FtwOR/IrlD6wIP7DSVUZgAUdzSqijAQsJXnnVjsL 1aR0h2t8XxtiPbtI6spje6a2ARc8vlO0qKkum8aquOCoL6gykLnhy0hfA2kQ2zsH8mkP37 XRM2sES7o03jfZv8zQNixZc+NzLqW8ZVnlFj2TJ/+ZSlAbVmgmES8yhthU+Rkg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=qoLyzGAR; 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=1715421380; 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=oe/nkndUw3uO0WBKSbVJpAV7eHJpKtBlWy4lnnWIyNA=; b=U6l/te3elEZ1e4IT8gjQWNaikBwgPWXXTrOHDIDZdwdVJ7HhGblHQcC0TlqEj7pPyA2hPL vlH+MjucGwE+hMq0QPcJivXHgJZ/AH/6qqi33udNifVykzJCjqEfSBNfcqLnHbvZUaqe2J aYFWyEt8UtXcLSuA3EUZhk9piujVVlxPf+PglSpTwLnCPHmpAiGZ3iF1we7hPcWSVkUaY1 dAvJB4mUgfbWQV2WY6BEumTojYI83wN5VzflmDnXn/LF6Nsjv/MzWuQFqsFlOn1Y+NaDbo 85Nhd19o/p+z7RKEDJ8+SoqC50NX6h5/lFVBRU40s+AhQmSZIhj0EFIW8aZ87w== 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 5CAA8646A5 for ; Sat, 11 May 2024 11:56:20 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s5jRx-0001UW-Ff; Sat, 11 May 2024 05:55:29 -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 1s5jRr-0001OU-Ad for emacs-orgmode@gnu.org; Sat, 11 May 2024 05:55:24 -0400 Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s5jRn-0005ks-Nh for emacs-orgmode@gnu.org; Sat, 11 May 2024 05:55:23 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id EE1FF240103 for ; Sat, 11 May 2024 11:55:16 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1715421317; bh=/nG7yr3lIWTPuE2erUWk2GvmJ5x+1lf/F9dVozr4rmI=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: From; b=qoLyzGARPmjprCOT/gF86oZLY4I7ASdOSUXYCqWlVEGdNeOzBeCGikiPrpTjIq6cb owbTkhShTzq2MNLW8/Tozaq5oVwIYhOpFJbpbrzrskw1bbJcgtv250WopZIhkGORY6 qhelmz+B5lbGsULth+Oohz2peaAgTy4uGH1jv9zzVTxH2PmJqL8edUGnwupFNhms5e JqmDvSuJ6re+n/7MqwwFo5xetlMrEsbhCOR3N5/ZvYk0f7nqYsnMDfSjF9Dz2Ff1jx VViwdFYmELsjp/NSzF2UP423zzuDONghOZU96tmNv5G0S8maGlczz0lhp+rqWXdeRv pho/OxfLV16jw== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Vc1MS1rzkz6tlh; Sat, 11 May 2024 11:55:16 +0200 (CEST) From: Ihor Radchenko To: =?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: References: <87a5l3wcqf.fsf@localhost> Date: Sat, 11 May 2024 09:56:48 +0000 Message-ID: <87ikzkvfhb.fsf@localhost> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=185.67.36.66; envelope-from=yantar92@posteo.net; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 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 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: 5CAA8646A5 X-Migadu-Scanner: mx12.migadu.com X-Migadu-Spam-Score: -9.60 X-Spam-Score: -9.60 X-TUID: r08Wj2WFAUzF --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Andr=C3=A1s Simonyi writes: > ... Some comments on the proposed changes: > ... Thanks for the comments! See the attached updated version of the patch with all your comments addressed. >> At least one =3DPRINT_BIBLIOGRAPHY=3D 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. Right. It is only true in bibtex-based processors, and only when the citation command tries to create a link to (missing) bibliography record. I removed this passage completely. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=v2-0001-org-manual-Add-better-opening-description-to-Cita.patch >From e16e5b2c678a18a772f338162fbfb9d2626b9317 Mon Sep 17 00:00:00 2001 Message-ID: From: Ihor Radchenko Date: Mon, 6 May 2024 11:40:18 +0300 Subject: [PATCH v2] 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 | 94 +++++++++++++++++++++++++++++++++------------- 1 file changed, 68 insertions(+), 26 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 3c60f3268..bf9547ae9 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -17491,30 +17491,69 @@ * 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 [[*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. -- 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 (~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 @@ -17568,7 +17607,8 @@ ** Citations : [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] - When style is not specified, default style is used + When style is not specified, default style (=nil=) specified by the + citation processor is used + either the default style specified in =CITE_EXPORT= keyword (see [[*Citation export processors]]) @@ -17598,8 +17638,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: @@ -17628,13 +17670,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; @@ -17672,8 +17714,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. @@ -17686,9 +17728,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, @@ -17700,10 +17742,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.0 --=-=-= 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 --=-=-=--