From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms1 with LMTPS id 8KT/OKvAjF5TZQAAk0OIDg (envelope-from ) for ; Tue, 07 Apr 2020 18:04:27 +0000 Received: from aspmx2.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id CAZBGqrAjF5DUgAA1q6Kng (envelope-from ) for ; Tue, 07 Apr 2020 18:04:26 +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 aspmx2.migadu.com (Postfix) with ESMTPS id D2E516895F4 for ; Tue, 7 Apr 2020 17:52:14 +0000 (UTC) Received: from localhost ([::1]:51534 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jLsOT-00064t-25 for larch@yhetil.org; Tue, 07 Apr 2020 13:52:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:35108) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jLsNu-0005pA-UD for emacs-orgmode@gnu.org; Tue, 07 Apr 2020 13:51:40 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jLsNt-0005Wp-0l for emacs-orgmode@gnu.org; Tue, 07 Apr 2020 13:51:38 -0400 Received: from relay6-d.mail.gandi.net ([217.70.183.198]:44641) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1jLsNs-0005VJ-OJ for emacs-orgmode@gnu.org; Tue, 07 Apr 2020 13:51:36 -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 relay6-d.mail.gandi.net (Postfix) with ESMTPSA id 9B501C0007; Tue, 7 Apr 2020 17:51:32 +0000 (UTC) From: Nicolas Goaziou To: "Bruce D'Arcus" Subject: Re: wip-cite status question and feedback References: Mail-Followup-To: "Bruce D'Arcus" , emacs-orgmode@gnu.org Date: Tue, 07 Apr 2020 19:51:31 +0200 In-Reply-To: (Bruce D'Arcus's message of "Tue, 7 Apr 2020 11:15:15 -0400") Message-ID: <87o8s389r0.fsf@nicolasgoaziou.fr> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 217.70.183.198 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 Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=default; t=1586281935; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=jX+ENZhItvYxIB/+35V2g4IFVEAJ9VquuPb/kXMHSLg=; b=mKSA8BuC3JYB+nQfm10beIZgI4F6zIKcfwT7/Ea/Sg89UbrFd3oThCmIohs2gL0/8YFKIH tqaahL6McArm6sFIprntK+qaWiaWAJ03sPGXCxaxVeFfbppx0+Eem1DLfp3cFW7sg6rOmC wuN+abHPvJmxNnrbIC/PT8FYQIdcB4M= ARC-Seal: i=1; s=default; d=yhetil.org; t=1586281935; a=rsa-sha256; cv=none; b=lWElJaqX4jpGuwIx6I1OCAQRBO4KWM69ALK/dDO18mJ2QxVMFXSvTJ7hcFG7WtAOQZJwyf pi8rsNWSQUTCJSe23PEBZwRLjQTKZbKKJ6RgmkqmakOOJVEHKkjP1BX0ZNqBjQVUQSW612 VexyG7tGd7WJ/BbexUykhmHc/vawTRo= ARC-Authentication-Results: i=1; aspmx2.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx2.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-Scanner: scn0 X-Spam-Score: -1.01 Authentication-Results: aspmx2.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx2.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-Scan-Result: default: False [-1.01 / 13.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; GENERIC_REPUTATION(0.00)[-0.58224367015365]; HAS_XOIP(0.00)[]; TO_DN_SOME(0.00)[]; R_SPF_ALLOW(-0.20)[+ip4:209.51.188.0/24:c]; IP_REPUTATION_HAM(0.00)[asn: 22989(0.32), country: US(-0.01), ip: 209.51.188.17(-0.58)]; ARC_SIGNED(0.00)[i=1]; MX_GOOD(-0.50)[cached: eggs.gnu.org]; RCPT_COUNT_TWO(0.00)[2]; MAILLIST(-0.20)[mailman]; FREEMAIL_TO(0.00)[gmail.com]; FORGED_RECIPIENTS_MAILLIST(0.00)[]; RCVD_TLS_LAST(0.00)[]; R_DKIM_NA(0.00)[]; ASN(0.00)[asn:22989, ipnet:209.51.188.0/24, country:US]; MID_RHS_MATCH_FROM(0.00)[]; TAGGED_FROM(0.00)[larch=yhetil.org]; ARC_NA(0.00)[]; RCVD_COUNT_FIVE(0.00)[6]; FROM_NEQ_ENVFROM(0.00)[mail@nicolasgoaziou.fr,emacs-orgmode-bounces@gnu.org]; FROM_HAS_DN(0.00)[]; MIME_GOOD(-0.10)[text/plain]; MIME_TRACE(0.00)[0:+]; DMARC_NA(0.00)[nicolasgoaziou.fr]; HAS_LIST_UNSUB(-0.01)[]; FORGED_SENDER_MAILLIST(0.00)[] X-TUID: MIaYMHa2WqU4 Hello, "Bruce D'Arcus" writes: > Hi everyone; first post. Welcome! > I see from the archive there was an encouraging thread from April of 2018 > > (so, two years ago) that seemed to suggest merging to master was close, > with perhaps some uncertainty around syntax being the primary hold up? > > My main question: how do we get this done? Good question. I don't think syntax is the primary hold up. It seems to me that the glue part between the parser and the export back-ends is missing. If we merge wip-cite branch in master, where do we plug it? How do Org folks use it, out of the box? It also need tooling. For example, citations could be a link to a database. Of course, that doesn't mean the syntax is perfect, but as it is, I assume it theoretically goes a long way towards solving most citation needs. > I'm happy to help resolve any syntax questions, if that's the primary hold > up, though my coding skills in general are minimal. Actually, the coding part is the easiest one. I can help on that part. Unfortunately, I do not use citations, so I cannot speak for the people who would make use of them in Org. > While I=E2=80=99m here, some feedback and thoughts below. I think the pro= posed > syntax is basically sound, but maybe could be simplified. Great! > The only documentation I can find on the proposal is at the citeproc org > project. > > https://github.com/andras-simonyi/citeproc-org#citations > > If the above is correct, then: > > 1. There are two forms of citations: short and long. > 2. Short is of this syntax, and can only have a single citekey as cont= ent: > [@doe2019]. > 3. Anything else (multiple citations, locators, prefixes and/or suffix= es) > requires the long form. > 4. In addition, there is a standard long form, and what the doc above = calls > =E2=80=9Cparenthetical=E2=80=9D form of the long form. > > So do I have all that right? You do. > First question: > > Why #4 above; a distinction between two different long forms? I think this is because you may want to mix two styles in the same document: inline and parenthesised. I think the idea comes from BibTeX. > Moving on, assuming the above is correct, let=E2=80=99s borrow these exam= ples from > the pandoc citation syntax for markdown > (which it also supports in org= ): > > Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1]. > > Blah blah [@doe99, pp. 33-35, 38-39 and *passim*]. > > Blah blah [@smith04; @doe99]. > > So from a model perspective, a citation in pandoc is a list of one-or-more > cites (or whatever we want to call them), each of which has optional: > > - prefix > - Locators (page numbers and such) > - suffix > > I believe this is similar to the proposed org model, with one difference: > the org proposal adds prefix and suffix for the list (the citation) as a > whole. > > So the pandoc version is a flat list, and the org version has two levels. > > Am I still understanding everything correctly? Org syntax has no notion of locators. Is that an issue for later interpretation? It just uses optional prefix and suffix around keys. The "(prefix) key (suffix)" is called a citation reference. A full citation may contain one ore more citation references, separated by semicolons. You are right about the global prefix and suffix. I'm not sure why they are here, but were probably suggested at some point. If there is no practical use for them, we can also drop them. > So ... am I correct that in none of these cases can one use the =E2=80=9C= short=E2=80=9D > form, and that the above would look like this converted to the proposed o= rg > syntax? True. I think the short form is just a quick reference that should be expanded in a predefined style, e.g., "(author, year)". > Blah blah [cite:see @doe99 pp. 33-35; also @smith04 chap. 1]. > > Blah blah [cite:@doe99 pp. 33-35, 38-39 and *passim*]. > > Blah blah [cite:@smith04; @doe99]. Actually, barring the "cite:" prefix, you can use the exact same syntax as Pandoc, i.e.: [cite:see @doe99, pp. 33-35; also @smith04, chap. 1] [cite:@doe99, pp. 33-35, 38-39 and *passim*] [cite:@smith04; @doe99] Only the semicolon is meaningful in there, not the commas. Also, for readability, spacing after the "cite:" prefix is ignored, so one can write, e.g., [cite: see @doe99, pp. 33-35; also @smith04, chap. 1] > Or the first one might treat the =E2=80=9Csee=E2=80=9D as a prefix for th= e list, though I=E2=80=99m > not sure what the practical benefit of that more hierarchical modelling i= s. No, IIRC, the common prefix is the part before the first semicolon, but only if that part contains no citation key. IOW, in the example above, "see " is the prefix of the first citation reference, not a global prefix. > While I do wonder if the syntax could be simplified, my main hope is that > it actually gets merged to master and deployed, to harmonize the variety = of > different ways emacs tools (org-ref, ebib, pandoc, etc.) are dealing with > citation links in org currently. If the syntax is practical, we could merge it, yes. Maybe that's the way forward, after all. But then? What library is going to use it? Org Ref is well established and is unlikely to switch to the new syntax. It would be nice if both syntax could converge at some point, though. The point of the new syntax is to make it easier for this kind of extension. "citeproc-el" is not included in Emacs, so integrating "citeproc-org" in Org may not be helpful at this point. Since Org is bundled with Emacs, it cannot use external libraries. WDYT? Regards, --=20 Nicolas Goaziou