From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:bcc0::]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id mEwOEny9imD2bwAAgWs5BA (envelope-from ) for ; Thu, 29 Apr 2021 16:06:52 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id wIelDXy9imBHVQAAB5/wlQ (envelope-from ) for ; Thu, 29 Apr 2021 14:06:52 +0000 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 707A221B6E for ; Thu, 29 Apr 2021 16:06:51 +0200 (CEST) Received: from localhost ([::1]:34172 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lc7JZ-000783-Ms for larch@yhetil.org; Thu, 29 Apr 2021 10:06:49 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:41088) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lc7HO-0005pE-93 for emacs-orgmode@gnu.org; Thu, 29 Apr 2021 10:04:34 -0400 Received: from relay3-d.mail.gandi.net ([217.70.183.195]:55449) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lc7HD-0007KI-C0 for emacs-orgmode@gnu.org; Thu, 29 Apr 2021 10:04:32 -0400 X-Originating-IP: 185.131.40.67 Received: from localhost (40-67.ipv4.commingeshautdebit.fr [185.131.40.67]) (Authenticated sender: admin@nicolasgoaziou.fr) by relay3-d.mail.gandi.net (Postfix) with ESMTPSA id CB7336000B for ; Thu, 29 Apr 2021 14:04:18 +0000 (UTC) From: Nicolas Goaziou To: Org Mode List Subject: Notes about citations in Org (part 3) Mail-Followup-To: Org Mode List Date: Thu, 29 Apr 2021 16:04:17 +0200 Message-ID: <8735v91926.fsf@nicolasgoaziou.fr> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=217.70.183.195; envelope-from=mail@nicolasgoaziou.fr; helo=relay3-d.mail.gandi.net X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, 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.23 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" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1619705211; 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: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=YCvq+3wk/Ee1H6tHdlm7hBzL1c9C965Ow60/zaEQ9R8=; b=vC2DK3TFqaadP4H9ubo6kEinv03r4RrbZrZu1zn/KPfx25NvAZVxsNdxFGfctyU4AX9ytK Nq/UiPiTQH2PIHsno7QUjcto86IndfAV5ermm2zfOn8IbqgBejco+hKX10k72BvtJVGF6k Edf0lZb5y/+sELkSckSLM6L2xM4zgtZVXdGULh61t3u1paMzbt2adp/ngjVobH/o60eep3 4xjWSpWP7KSHXzuLwDELR+1g5RiZoyJfkF30xS/f8nPPanyuFaEM+ISrajimL8JAAUpESH AOWw7BfkBolAagijFN8UEtXsSRK+RfxKN4DgKhUmRwghjOaUqdexGAj77XuuIA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1619705211; a=rsa-sha256; cv=none; b=W+c04eoD9ZsltO/OP4c8LozVrH9Y8B3lQwhncz7W2E3rnWrKxuf/R1juyX0LdTnCn6PXNL Op9oo7mKxMibm9dDpVNfr/zlX8vPp7fC8FLHjrbJFIXnpteWKeqIRHL3bSPYG7oJNZ+9up Vib6eIS8UNiT+OZLZUvplk7hwURiuR5z0NntBe65GAg768geh1fBXyczD6kSq1/fCjZkGw 6Lxfmb3pd5FShlUAmUVKDX2ACv8sMxajnSXNCJ+ALj+lGFazL7R9tZGnHo7ED0yYk49lQ2 QJJq8sl4VTOTOdNSO9Hkb8XRwd7fTOqt1vznJPhfWSyhytlEWyUoGhh0lOxvhw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Spam-Score: -2.46 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Queue-Id: 707A221B6E X-Spam-Score: -2.46 X-Migadu-Scanner: scn0.migadu.com X-TUID: GU8cIM1fXh0A Hello, This post is an update about "wip-cite-new" branch, which I rebased a few minutes ago. It introduces changes that make previous reports obsolete. In particular, the "demo" I wrote in the previous thread is no longer applicable directly, even though the ideas developed there still hold. Please comment on this thread from now on. The first noteworthy changes are about the syntax.=20 1. I re-introduced objects in prefixes and suffixes, which can again contain usual emphasis (bold, italic, strike-through, underscore, code, verbatim), subscript, superscript, entities and LaTeX fragments. 2. I removed support for "suppress author" minus symbol. The complete syntax is now [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] Everything is optional, except the brackets, "cite" and the colon. Also the citation must contain at least a key. So its minimal form is: [cite:@key] Spaces are meaningful in prefixes and suffixes, except for those right after the colon and those before the closing bracket. As a reminder, the syntax also supports the following keywords. #+bibliography: file #+cite_export: [processor] [bibliography-style] [citation-style] #+print_bibliography: [style] For complete information about styles, please refer to the last post, "(Not so) Short note about citations in Org". >From a technical standpoint, as a consequence of item 1, (org-element-property :prefix citation) or (org-element-property :prefix citation-reference) may return so-called "secondary strings", i.e., lists of strings and objects. In order to deal with this additional complexity, I implemented some specific tooling in "oc.el": `org-cite-concat' and `org-cite-mapconcat' are similar to `concat' and `mapconcat', but can also operate on secondary strings and objects. For example, a processor developer could write: (org-cite-concat "(" (org-element-property :prefix citation) ")") and later export the result with `org-export-data' as if the central argument were a string. This new revision also introduces additional tooling, which I won't comment but is worth looking at if you consider giving a try at writing a citation processor: `org-cite-key-number', `org-cite-wrap-citation', `org-cite-make-paragraph', and `org-cite-emphasize'. The other incompatibility is about function signatures for `:export-bibliography' and `:export-finalizer' keywords. This change should not be an issue at this point in the development. Citation processors are registered using `org-cite-register-processor'. Its docstring follows: --8<---------------cut here---------------start------------->8--- Mark citation processor NAME as available. NAME is a symbol. BODY is a property list, where the following optional ke= ys can be set: `:activate' Function activating a citation. It is called with a single argument: a citation object extracted from the current buffer. It may add text properties to the buffer. If it is not provided, `org-cite-fontify-def= ault' is used. `:export-bibliography' Function rendering a bibliography. It is called with five arguments: the list of citation keys used in the document, as strings, a list of bibliography files, the style, as a string or nil, the export back-e= nd, as a symbol, and the communication channel, as a property list. It is called at each \"print_bibliography\" keyword in the parse tree. It may return a string or nil. When it returns nil, the keyword is ign= ored. Otherwise, the string it returns replaces the keyword in the export out= put. `:export-citation' (mandatory for \"export\" capability) Function rendering citations. It is called with four arguments: a cita= tion object, the style, as a string or nil, the export back-end, as a symbol, and the communication channel, as a property list. It is called on each citation object in the parse tree. It may return a string or nil. When it returns nil, the citation is ignored. Otherw= ise, the string it returns replaces the citation object in the export output. `:export-finalizer' Function called at the end of export process. It must accept six argum= ents: the output, as a string, a list of citation keys used in the document, a list of bibliography files, a list of bibliography styles requested by \"print_bibliography\" keywords, as strings or nil, the export back-end, as a symbol, and the communication channel, as a property list It must return a string, which will become the final output from the ex= port process, barring subsequent modifications from export filters. `:follow' Function called to follow a citation. It accepts two arguments, the citation or citation reference object at point, and any prefix argument received during interactive call of `org-open-at-point'. --8<---------------cut here---------------end--------------->8--- Ah! I almost forgot=E2=80=A6 This new revision introduces a poor man citati= on processor for BibTeX bibliography files, named "basic", in the file "oc-basic.el". Here is its commentary section: --8<---------------cut here---------------start------------->8--- The `basic' citation processor provides "activate", "follow" and "export" capabilities. More specifically, "activate" capability re-uses default fontification, but highlights with `error' face any unknown citation key according to the bibliography defined in the document. On a citation key, "follow" capability moves point to the corresponding entry in the current bibliography. Elsewhere on the citation, it asks the user to follow any of the keys cited there, with completion. "export" capability supports the following styles for citations: - author - nocite - note - numeric - text - year - author-year (default) It also supports the following styles for bibliography: - plain - numeric - author-year (default) It assumes bibliography files are in BibTex format. Disclaimer: this citation processor is meant to be a proof of concept, and possibly a fall-back mechanism when nothing else is available. It is too limited for any serious use case. With that out of the way, if you still want to use this processor, you may set `org-cite-activate-processor', `org-cite-follow-processor', or `org-cite-export-processor' to `basic'. --8<---------------cut here---------------end--------------->8--- As pointed out above, don't expect too much from it. Nevertheless, feedback is welcome. Improvements are welcome too, but at this point, I would suggest to spend energy porting "citeproc-org" or "org-ref" to this API instead. Regards, --=20 Nicolas Goaziou