From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:8:6d80::]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id 8Ql5IwRJdGDr/gAAgWs5BA (envelope-from ) for ; Mon, 12 Apr 2021 15:20:04 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id kEhsFQRJdGBSPgAAB5/wlQ (envelope-from ) for ; Mon, 12 Apr 2021 13:20:04 +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 E20BC22067 for ; Mon, 12 Apr 2021 15:20:03 +0200 (CEST) Received: from localhost ([::1]:41924 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lVwTz-0001As-5O for larch@yhetil.org; Mon, 12 Apr 2021 09:20:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51308) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lVwTe-0001Am-B6 for emacs-orgmode@gnu.org; Mon, 12 Apr 2021 09:19:42 -0400 Received: from relay9-d.mail.gandi.net ([217.70.183.199]:43807) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lVwTc-0005b3-11 for emacs-orgmode@gnu.org; Mon, 12 Apr 2021 09:19:42 -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 relay9-d.mail.gandi.net (Postfix) with ESMTPSA id 09087FF810; Mon, 12 Apr 2021 13:19:35 +0000 (UTC) From: Nicolas Goaziou To: "Bruce D'Arcus" Subject: Re: wip-cite status question and feedback References: <874ktu8gr9.fsf@nicolasgoaziou.fr> <87mu5xpm4x.fsf@gnu.org> <87img81ad7.fsf@gnu.org> <20210324182751.GA8721@atlantis> Mail-Followup-To: "Bruce D'Arcus" , "emacs-orgmode@gnu.org" , =?utf-8?Q?Andr=C3=A1s?= Simonyi Date: Mon, 12 Apr 2021 15:19:34 +0200 In-Reply-To: (Bruce D'Arcus's message of "Sun, 11 Apr 2021 19:15:44 -0400") Message-ID: <87czuzprmh.fsf@nicolasgoaziou.fr> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=217.70.183.199; envelope-from=mail@nicolasgoaziou.fr; helo=relay9-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_H2=-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: , Cc: "emacs-orgmode@gnu.org" , =?utf-8?Q?Andr=C3=A1?= =?utf-8?Q?s?= Simonyi 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=1618233604; 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; bh=peqLRY6wOYX2Zl/4XU9xBya8B7rSc6goInrh+tIVO6s=; b=MlH/FfBMw6gacOKBypOX9vc2tp8aSA+cDGOS/bteP2ibi1WwojX4MIZFn8//ZLayT7NETF qL+aKUo8frP/Mlg+ssllAGg/q4GxtAmMRaCRhYzxs5j+NtS4UtzFdZkva2QCRznPO2QGkX SBxBwwG8J08Kqx162nXl+NBCZ/r5VV4dYHud9KgnK+QR8sOaKoW29Za874L33JZ2LjX4pp AlK6n6pQseFnzwbqn+to43hotVsTQx30SUm6h8jleS6gyOLyHywKVB8ocbgNKUMQ4Jem7d psd1gOmwG+NVcy6C9uBXY7bt8FG3RyblEPu++x3J8qHCcT730ZoWmREaFjssPQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1618233604; a=rsa-sha256; cv=none; b=hWvvk/uVP0+RJpznSTT5smldIiOYS3OTVAsVmcuSleunWvzaPTQ0WMaVXrnylaoF/qzA2l vyHaotVokWHbunWOIRd0DVRbBwuUJpcGM3jO1Ft5Z/8H2GV40046ds4IsJkK9vG6sRnWkJ SXJeNME2jFlGhuh4ySfPWdw5E6VPHKD2h298FWEz2TW8OnJEDsDCSgD2zELLQjrqySeLlq XBDB+N+NtwJzhpnuzFo2VHj0xlCbweeNjbxuT1axwHOOSbY0LTR7hnkytQ2IXMoXFUP0j7 4APdnFagqQ3xGhesPbLlYKrYcW1Rdx/Rv+7Slou9ghvMRaLmXtA9hbibt20FIA== 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.44 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: E20BC22067 X-Spam-Score: -2.44 X-Migadu-Scanner: scn0.migadu.com X-TUID: 5xzXVO1nwxbs Hello, "Bruce D'Arcus" writes: > Maybe since Nicolas has been around lately, he can weigh in? I guess I can make a summary about the current state of the citations branch, i.e., what is done, what is missing. There are three major steps to complete in order to add citations in Org: defining the syntax, designing the Org API for citation processors, and writing a default processor. The syntax is complete in "wip-cite-new" branch. For the record, in its full glory, it can look like this: [cite/style: global prefix; prefix -@key suffix ; ... ; global suffix] "/style", "global prefix", "prefix", "-" marker, "suffix" and "global suffix" are all optional. So, in its minimal form, it can be as simple as: [cite:@Doe:1995a] The syntax also includes a new #+bibliography keyword, which, when paired with a new `org-cite-global-bibliography', defines global or local bibliographies. For exporting needs, I also introduced #+print_bibliography, #+citation_style and #+bibliography_style keywords. Now about the API, which is partly implemented on a local branch. Citations processors, in addition to any tools they may provide, can integrate into Org in three distinct areas: opening (with `org-open-at-point'), fontification, and export. - "opening" action is straightforward. All is needed for the processor is to provide a function accepting two arguments: the citation key, as a string, and possibly a universal argument, which it may ignore, or not. All this is already implemented locally. - "exporting" action is trickier, because there are multiple ways to do the integration, and, since I'm not an implementor for citation processors, I don't have an accurate view about what is the best design. Anyway, here is the First, export happens as pre-process, before export back-ends are introduced. IOW, export back-ends are never going to see a citation object, which means no support whatsoever is needed on their end. Support export requires two functions. The first function is responsible for rendering a bibliography. Its arguments are the list of citations in the document, the list of bibliography files, the style, if any, and the export back-end. It should return a string. The second mandatory function is obviously responsible for rendering citations. It is called with a citation object, the desired style, if any, and the export back-end, the full list of citations objets in the document, and the list of bibliography files. It should also return a string. Org provides a helper function to determine the footnote containing a citation (and its label, or number) from a citation object. In the functions described above, I don't know if the arguments are sufficient. I would love to hear about citeproc-org and org-ref developers about this. Also, note that style is an indication. Export is requested to handle regular [cite:...] syntax. Unknown styles should fall-back to this. - "fontification" is meant to give full access to face selection, what is really displayed, additional keymaps, all using a single function. At the moment, I have no idea about what arguments would be useful. I think John Kitchin gave ideas about this already on this ML. I have to re-read his posts on the subject. In any case, feedback welcome. This not implemented yet. A citation processor does not need to provide integration in all these areas. Users may be able to mix and match processors. This is another (minor) point which is yet to be designed. How is a user supposed to select a processor for each integration area? It could be done through three variables, e.g., (setq org-cite-display-processor 'org-ref) (setq org-cite-export-processor 'citeproc) (setq org-cite-follow-processor 'default) I think it is unlikely for a user to locally select "display" and "follow" processors. However, we need a way to use a local export processor for a given document. I may need to introduce a #+citation_processor keyword during export. Any other idea? The last step is implementing a default processor. The point is to provide a self-contained, very basic processor handling all three areas described above. I started implementing one. It relies on built-in bibtex.el library, so it assumes bibliography is written as a BibTex file. At the moment it properly "follows" citations. It also exports citations as (Name, date). However, it doesn't export bibliographies yet. It does not fontify either. As a conclusion, besides the syntax, the branch is not ready for inclusion yet. There are a few design questions about the API to answer. Once done, and as long as no one has high expectations about the default processor, this last part should not be too hard to complete. Regards, -- Nicolas Goaziou