From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.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 INJ8O4aYOGZqSwEA62LTzQ:P1 (envelope-from ) for ; Mon, 06 May 2024 10:44:55 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id INJ8O4aYOGZqSwEA62LTzQ (envelope-from ) for ; Mon, 06 May 2024 10:44:55 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=dHkDjqLV; 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=1714985094; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=CpUxWzpCXApOQ6DsR+wtBhtrgqIhPJnb+gxy1kiGEg4=; b=j68g+GU83bWNCWFabT3X5EiqDXFN6Ua3Qy9sOw7ch2AX3OqF0G8gMrBsjVFmSjsvwE1DTj bvxrvHtBjLoI4LyTPgdFGonHtB9ZYxj+v3iFNrEjOZIPttGWOANw3W+SOU7Qa2JdqSWF1m uiZdKgReAM+j9J8RLz/DuUNZuJgsSV33TF26dAbmQiD1YxLhy9dmbCuHygGVey/8wXJOGI F1bzSqOsj6w26IkstvCCbA7FrkFqusXgxd0kKtFzu4i43fF0lQ/dXda7Wb6NcgpIHW50dc +Kj4MOL2TS5oRLa04VEqON7Z4UsuFMTyIuStgjXkKP8ATlAkZNmNPzwvmICxSg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1714985094; a=rsa-sha256; cv=none; b=CQyKsIF4oRey4EJYDnStGmOSdTASj1LocE/ODnf4eSB5u3sA1tn/elDnl4/nXVDz0p8D7m G1DQ9JTQkltaLSu3mJ0p3zRC8TOGdbZxOya3Mabz2AUI32Gee8fXg1FT/6BKa/vr5FyxdA KT7CGkY9BGTG0LmuwPcwehnMNNCQfHDUmOlysvrDMehAVuqIRlxGaEtkEPSNftrTSatmJX NHzXQudrpdiC2YM7/0ubZ7cCy4ynwSg32BaZmHZeLeW50pITbNEmB+m7u+YnoByIn/cya9 VjCUD5pi9GrnFJktIVHmdcbyX3vCHGY5lkxxozMhEWlMMux27C/6+MfvIA3Ouw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=dHkDjqLV; 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" 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 8B5836299D for ; Mon, 06 May 2024 10:44:54 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s3tx1-0001kv-PY; Mon, 06 May 2024 04:43:59 -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 1s3twm-0001bF-Dt for emacs-orgmode@gnu.org; Mon, 06 May 2024 04:43:44 -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 1s3twi-0001hH-CF for emacs-orgmode@gnu.org; Mon, 06 May 2024 04:43:44 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 50982240103 for ; Mon, 6 May 2024 10:43:37 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1714985017; bh=9lBdiFP+QGKFB4ru5PhsdhYMash+nGTjBtTf6E6ajKU=; h=From:To:Subject:Date:Message-ID:MIME-Version:Content-Type:From; b=dHkDjqLVVXsos9b+KvzrwWFQSPzfbpGiPJI0Kscgs1k+S6kcd/E5w/k+5dpEn76K9 xdl7xxYdXcG4JHYADaDwsYX+CaysFQMYUcc/sfzv4KUt//JfGNp43r1LyOabVEJ1lo EPu0EAqSbMnVqAsvLgDSr1bhRWS/fN9JY88pw2pPb+ZKCz2cw/jIa/KQK3dQJ0G275 wpkGdVFwtCbP1asvEoZkl6R8exTGzomxX8+MdYRVE40kB5p0QFgcSByNxzod+lk5O9 X8CcvhCgygSc7koqZZGS1BsnricQ8YEtm6jBDBIKjSThwjep/lSV1VXwCnRH4otZYA yMM3r5TfFqN3A== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4VXw142nP5z9rxG for ; Mon, 6 May 2024 10:43:36 +0200 (CEST) From: Ihor Radchenko To: emacs-orgmode@gnu.org Subject: [PATCH] org-manual: Rewrite opening section in Citation handling Date: Mon, 06 May 2024 08:44:56 +0000 Message-ID: <87a5l3wcqf.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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, 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-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -6.10 X-Spam-Score: -6.10 X-Migadu-Queue-Id: 8B5836299D X-Migadu-Scanner: mx11.migadu.com X-TUID: RYAKZbbn2fDp --=-=-= Content-Type: text/plain Hi, The current version of Citation handling section of the manual is rather technical. I tried to rewrite it aiming for ordinary users not familiar with Org mode internals. Please, let me know if it reads better. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-org-manual-Add-better-opening-description-to-Citatio.patch >From 89e5bd96a1219e85f8e6be7a6eabb840257b021a Mon Sep 17 00:00:00 2001 Message-ID: <89e5bd96a1219e85f8e6be7a6eabb840257b021a.1714984945.git.yantar92@posteo.net> From: Ihor Radchenko Date: Mon, 6 May 2024 11:40:18 +0300 Subject: [PATCH] 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 | 89 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 66 insertions(+), 23 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 1feb5ed60..59663a90f 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -17490,30 +17490,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 [[*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 =#+bibliography= database +and use it to typeset the exported document in arbitrary formats. +For example, below snippet 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 Citation +Style Language bibliographies (=csl= processor). + +The default citation processor is =basic= - it works with arbitrary +export formats and recognized 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 @@ -17567,7 +17605,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]]) @@ -17597,8 +17636,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: @@ -17627,13 +17668,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; @@ -17677,6 +17718,8 @@ ** Bibliography printing A document may contain more than one =PRINT_BIBLIOGRAPHY= keywords. Each of the keywords will trigger printing the bibliography. +At least one =PRINT_BIBLIOGRAPHY= keyword must be present in the +document to render citations on export. The keywords can be used with or without additional options. Options can be used, for example, to print only entries that belong to a @@ -17687,7 +17730,7 @@ ** Bibliography printing *** 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, @@ -17699,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 --=-=-=--