From mboxrd@z Thu Jan 1 00:00:00 1970 From: John Kitchin Subject: Re: Should wip-cite branch be merged to master? Date: Mon, 23 Apr 2018 12:42:12 -0700 Message-ID: References: <29b94436.a1e.162e54aa7c1.Coremail.tumashu@163.com> <871sf9f2ak.fsf@nicolasgoaziou.fr> <87in8jaywk.fsf@all.hu> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="00000000000006bf75056a893c92" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:34326) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fAhLu-0006ql-GC for emacs-orgmode@gnu.org; Mon, 23 Apr 2018 15:42:20 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fAhLr-0005ZF-NJ for emacs-orgmode@gnu.org; Mon, 23 Apr 2018 15:42:18 -0400 Received: from mail-wr0-x22b.google.com ([2a00:1450:400c:c0c::22b]:42764) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fAhLr-0005Yu-91 for emacs-orgmode@gnu.org; Mon, 23 Apr 2018 15:42:15 -0400 Received: by mail-wr0-x22b.google.com with SMTP id s18-v6so44399715wrg.9 for ; Mon, 23 Apr 2018 12:42:14 -0700 (PDT) In-Reply-To: <87in8jaywk.fsf@all.hu> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: =?UTF-8?Q?Andr=C3=A1s_Simonyi?= Cc: tumashu , emacs-orgmode , Nicolas Goaziou --00000000000006bf75056a893c92 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable I don't have any objections to merging now, or in the future. org-ref addresses a fairly specific need, which is simple citations that ultimately end up being processed by bib(la)tex/latex. It does a mediocre job supporting footnote style citations, and limitations of the link format it uses make it challenging to better support those. It has had limited support for citeproc like capability for other formats. Hopefully what Andr=C3=A1s is doing will be the right size nucleus to keep growing to completion. Some of this limitation is due to the complexity of a citeproc engine that fully supports all types of citations, some of it to limitations in the link syntax (which may be solved by a new syntax), choices about what dependencies get added as a result of the citeproc engine, and some of it is the backend where bibliographic data is stored (e.g. how do you store markup of titles, author names in bibtex, zotero, etc... It might depend on the final output, e.g. latex, html,...). More progress on my end is certainly limited by it not being critical to the kind of work I have been doing. org-ref has been relatively stable lately, and is likely to stay that way for the foreseeable future. I would be happy to stop using links in org-ref, in favor of a new syntax (especially if it provided better support for footnote citations), provided it doesn't reduce the functionality I use and rely on already in org-ref. Here is my take on the important capabilities that make org-ref so useful to us. 1. functional citations that provide a UI to elisp functions that do something useful to the author about the citation at point. This is currently provided in org-ref via links that use color to indicate they are citations, as well as when they are broken, tooltips to provide a bibliographic representation, clicking to activate a menu of actions, and keybindings to facilitate citation manipulation and navigation. I would expect the new citation syntax to (eventually) support all of these capabilities, otherwise it would be a regression in functionality in my opinion (except for the part about supporting footnote citations). I am aware this probably makes the new cite syntax look a lot like a more generalized link. I think it is worth considering the other cross-reference needs of documents in this context too, notably references to figures, equations, tables, etc. These aren't generally supported in org-mode in a way that meets the needs of technical documents, and so I have analogous links defined in org-ref for them. They have similar functionalities as the cite links. 2. A UI that uses some completion backend to insert citations. This is currently done with helm/ivy-bibtex, or an ivy backend I created for org-ref. This is not part of the syntax exactly, except that the syntax has to be programmatically constructable at least for the easy cases. 3. Support for export that provides styling of citations and the bibliography. This is where a citeproc like solution is needed. This is also not part of the syntax exactly, but without this as part of the solution, we would still basically be stuck with exporting to latex, or with ad hoc/partial support for other formats. Since these citations must be exportable to different backends, it feels like it has to be part of the solution. 4. org-element support. This is currently provided by the link, and it enables a lot of the functionality to be possible, as well as other external possibilities like linting, storing all citations in a database, etc... I presume this is part of the syntax/org integration, but it is important that citations/bibliography elements be first-class citizens. Those are my thoughts at the moment. I don't want to delay the integration of this because of org-ref if it leads to better support for citeproc and footnote citations. If the new syntax eventually enables org-ref++ it will be progress. John ----------------------------------- Professor John Kitchin Doherty Hall A207F Department of Chemical Engineering Carnegie Mellon University Pittsburgh, PA 15213 412-268-7803 @johnkitchin http://kitchingroup.cheme.cmu.edu On Sun, Apr 22, 2018 at 11:17 AM, Andr=C3=A1s Simonyi wrot= e: > Dear All, > > thanks for bringing this up. I definitely agree that it'd be too early to > merge > the wip-cite branch. In fact, having added (experimental) support for it = in > citeproc-org I've been planning to propose some changes/extensions to the > syntax > but I wanted to wait until citeproc-org and citeproc-el become available = as > MELPA packages which still isn't the case (citeproc-el is already there b= ut > citeproc-org still needs some work before I can submit it). Anyhow, since > the > topic has come up, here is how I see the situation (sorry for the length)= : > > From the citeproc-el/CSL point of view, the current syntax is perfect wit= h > the > notable exception of the provided citation commands. Currently only `cite= ' > and > `(cite)' are supported, where the latter seems to be intended to provide > the > parenthetical version of a basic citation, e.g. in an author-date style > `cite' > would produce something like `Smith 2018` while `(cite)' `(Smith 2018)'. > Now I > think that for author-date styles `cite' should produce the parenthetical > version and that `(cite)' probably shouldn't be among the commands at all= . > The > main reason is that most citation processors (biblatex, CSL processors > etc.) > support not only author-date citation styles but footnote-based ones as > well, > and the concept of a `parenthetical citation' doesn't really make sense > for the > latter. A more abstract characterization which is applicable to all style= s > is > that normally references are not part of the main text, they are set off > either > by brackets or in a note. Since this is the most frequent, basic form, I > think > this the one which should be produced by the `cite' syntax, that is, when > used > in normal text `cite' should produce something like `(Smith 2018)' for > author-date styles and a note with the reference for note styles. > > In addition to `cite', the following additional variants would be very > useful, and would probably cover the majority of use-cases: > > - "bare cite": the same as cite, but doesn't separate the reference from > the main text (no brackets/note); > > - "suppress author": removes the author's name from the citation. > > - "textual cite": includes the author's name in the main text but sets > off the rest of the citation. > > A proposal for the syntax of the additional forms: bare cite could be > indicated > by a `-' suffix, suppress author by a `*' and textual cite by a `t' > resulting in > the variants > > | command | result in author-date styles | > |---------------+------------------------------| > | cite | (Smith 2017) | > | citet | Smith (2017) | > | cite- | Smith 2017 | > | cite* | (2017) | > | cite*-/cite-* | 2017 | > > (omitting some combinatorial possibilities that don't make practical > sense). > > It would be a nice extra to also provide commands for adding an item to > the list > of references without actually citing it (`nocite' command), and for addi= ng > literal cites (that provide the full text of the citation, and whose sole > function is to let the processor know that a citation occurred at a certa= in > location) but these are obviously not so important as the ones in the abo= ve > table. > > The citeproc-el wiki contains a bit more information about this proposal: > > https://github.com/andras-simonyi/citeproc-el/wiki/ > Citation-types-and-commands > > I'd be glad to hear your views regarding these issues. > > best regards, > > Andr=C3=A1s > > >> There is a package which support wip-cite: > >> https://github.com/andras-simonyi/citeproc-org, should wip-cite > >> branch be merged to master now? > > > Merging wip-cite branch with master, and integration of citeproc-org > > into Org core, could be discussed with the author of the library, and= , > > of course, with anyone interested in using the @cite syntax. For > > example, I need to know if that syntax, along with citeproc-org, cove= rs > > enough use-cases for citations, if it brings more value than using, > > e.g., Org Ref, which already exists, how it could be improved, etc. > > > I have the feeling that it is a bit early for Org 9.2. Anyway, I'm > > Cc'ing Andr=C3=A1s and John for their opinion about it. I'd love to h= ear > from > > everyone involved in the last round of discussion about the subject, > > too. > > > > > Regards, > > > -- > > Nicolas Goaziou > --00000000000006bf75056a893c92 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
I don't have any objections to merging now, or in the = future. org-ref addresses a fairly specific need, which is simple citations= that ultimately end up being processed by bib(la)tex/latex. It does a medi= ocre job supporting footnote style citations, and limitations of the link f= ormat it uses make it challenging to better support those. It has had limit= ed support for citeproc like capability for other formats. Hopefully what= =C2=A0 Andr=C3=A1s is doing will be the right size nucleus to keep growing = to completion.=C2=A0Some of this limitation is due to the complexity of a c= iteproc engine that fully supports all types of citations, some of it to li= mitations in the link syntax (which may be solved by a new syntax), choices= about what dependencies get added as a result of the citeproc engine, and = some of it is the backend where bibliographic data is stored (e.g. how do y= ou store markup of titles, author names in bibtex, zotero, etc... It might = depend on the final output, e.g. latex, html,...). More progress on my end = is certainly limited by it not being critical to the kind of work I have be= en doing. org-ref has been relatively stable lately, and is likely to stay = that way for the foreseeable future.=C2=A0

I would be ha= ppy to stop using links in org-ref, in favor of a new syntax (especially if= it provided better support for footnote citations), provided it doesn'= t reduce the functionality I use and rely on already in org-ref. Here is my= take on the important capabilities that make org-ref so useful to us.
<= div>
1. functional citations that provide a UI to elisp funct= ions that do something useful to the author about the citation at point. Th= is is currently provided in org-ref via links that use color to indicate th= ey are citations, as well as when they are broken, tooltips to provide a bi= bliographic representation, clicking to activate a menu of actions, and key= bindings to facilitate citation manipulation and navigation.=C2=A0

I would expect the new citation syntax to (eventually) sup= port all of these capabilities, otherwise it would be a regression in funct= ionality in my opinion (except for the part about supporting footnote citat= ions). I am aware this probably makes the new cite syntax look a lot like a= more generalized link. I think it is worth considering the other cross-ref= erence needs of documents in this context too, notably references to figure= s, equations, tables, etc. These aren't=C2=A0 generally supported in or= g-mode in a way that meets the needs of technical documents, and so I have = analogous links defined in org-ref for them. They have similar functionalit= ies as the cite links.

2. A UI that uses some comp= letion backend to insert citations. This is currently done with helm/ivy-bi= btex, or an ivy backend I created for org-ref.

Thi= s is not part of the syntax exactly, except that the syntax has to be progr= ammatically constructable at least for the easy cases.=C2=A0

=
3. Support for export that provides styling of citations and the= bibliography. This is where a citeproc like solution is needed.
=
This is also not part of the syntax exactly, but without thi= s as part of the solution, we would still basically be stuck with exporting= to latex, or with ad hoc/partial support for other formats. Since these ci= tations must be exportable to different backends, it feels like it has to b= e part of the solution.

4. org-element support. Th= is is currently provided by the link, and it enables a lot of the functiona= lity to be possible, as well as other external possibilities like linting, = storing all citations in a database, etc...=C2=A0

I presume this is part of the syntax/org integration, but it is impor= tant that citations/bibliography elements be first-class citizens.

Those are my thoughts at the moment. I don't want to d= elay the integration of this because of org-ref if it leads to better suppo= rt for citeproc and footnote citations. If the new syntax eventually enable= s org-ref++ it will be progress.


John
-----------------------------------
Professor John Kitchin=C2=A0
Doh= erty Hall A207F
Department of Chemical Engineering
Carnegie Mellon Un= iversity
Pittsburgh, PA 15213
412-268-7803

On Sun, Apr 22, 2018 at 11:17 AM, Andr=C3=A1= s Simonyi <simonyi@all.hu> wrote:
Dear All,

thanks for bringing this up. I definitely agree that it'd be too early = to merge
the wip-cite branch. In fact, having added (experimental) support for it in=
citeproc-org I've been planning to propose some changes/extensions to t= he syntax
but I wanted to wait until citeproc-org and citeproc-el become available as=
MELPA packages which still isn't the case (citeproc-el is already there= but
citeproc-org still needs some work before I can submit it). Anyhow, since t= he
topic has come up, here is how I see the situation (sorry for the length):<= br>
>From the citeproc-el/CSL point of view, the current syntax is perfect with = the
notable exception of the provided citation commands. Currently only `cite&#= 39; and
`(cite)' are supported, where the latter seems to be intended to provid= e the
parenthetical version of a basic citation, e.g. in an author-date style `ci= te'
would produce something like `Smith 2018` while `(cite)' `(Smith 2018)&= #39;. Now I
think that for author-date styles `cite' should produce the parenthetic= al
version and that `(cite)' probably shouldn't be among the commands = at all. The
main reason is that most citation processors (biblatex, CSL processors etc.= )
support not only author-date citation styles but footnote-based ones as wel= l,
and the concept of a `parenthetical citation' doesn't really make s= ense for the
latter. A more abstract characterization which is applicable to all styles = is
that normally references are not part of the main text, they are set off ei= ther
by brackets or in a note. Since this is the most frequent, basic form, I th= ink
this the one which should be produced by the `cite' syntax, that is, wh= en used
in normal text `cite' should produce something like `(Smith 2018)' = for
author-date styles and a note with the reference for note styles.

In addition to `cite', the following additional variants would be very<= br> useful, and would probably cover the majority of use-cases:

- "bare cite": the same as cite, but doesn't separate the ref= erence from
=C2=A0 =C2=A0the main text (no brackets/note);

- "suppress author": removes the author's name from the citat= ion.

- "textual cite": includes the author's name in the main text= but sets
=C2=A0 off the rest of the citation.

A proposal for the syntax of the additional forms: bare cite could be indic= ated
by a `-' suffix, suppress author by a `*' and textual cite by a `t&= #39; resulting in
the variants

| command=C2=A0 =C2=A0 =C2=A0 =C2=A0| result in author-date styles |
|---------------+------------------------------|
| cite=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 | (Smith 2017)=C2=A0 =C2=A0 =C2=A0= =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|
| citet=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| Smith (2017)=C2=A0 =C2=A0 =C2=A0= =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|
| cite-=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| Smith 2017=C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|
| cite*=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0| (2017)=C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|
| cite*-/cite-* | 2017=C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0|

(omitting some combinatorial possibilities that don't make practical se= nse).

It would be a nice extra to also provide commands for adding an item to the= list
of references without actually citing it (`nocite' command), and for ad= ding
literal cites (that provide the full text of the citation, and whose sole function is to let the processor know that a citation occurred at a certain=
location) but these are obviously not so important as the ones in the above=
table.

The citeproc-el wiki contains a bit more information about this proposal:
https://github.com/and= ras-simonyi/citeproc-el/wiki/Citation-types-and-commands

I'd be glad to hear your views regarding these issues.

best regards,

Andr=C3=A1s

=C2=A0 >> There is a package which support wip-cite:
=C2=A0 >> https://github.com/andras-simonyi= /citeproc-org, should wip-cite
=C2=A0 >> branch be merged to master now?

=C2=A0 > Merging wip-cite branch with master, and integration of citepro= c-org
=C2=A0 > into Org core, could be discussed with the author of the librar= y, and,
=C2=A0 > of course, with anyone interested in using the @cite syntax. Fo= r
=C2=A0 > example, I need to know if that syntax, along with citeproc-org= , covers
=C2=A0 > enough use-cases for citations, if it brings more value than us= ing,
=C2=A0 > e.g., Org Ref, which already exists, how it could be improved, = etc.

=C2=A0 > I have the feeli= ng that it is a bit early for Org 9.2. Anyway, I'm
=C2=A0 > Cc'ing Andr=C3=A1s and John for their opinion about it. I&#= 39;d love to hear from
=C2=A0 > everyone involved in the last round of discussion about the sub= ject,
=C2=A0 > too.



=C2=A0 > Regards,

=C2=A0 > --
=C2=A0 > Nicolas Goaziou

--00000000000006bf75056a893c92--