emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [O] Should wip-cite branch be merged to master?


From: John Kitchin
Subject: Re: [O] Should wip-cite branch be merged to master?
Date: Mon, 23 Apr 2018 12:42:12 -0700

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ás 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

On Sun, Apr 22, 2018 at 11:17 AM, András Simonyi <address@hidden> 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 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 but
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 with 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 styles 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 adding
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/andras-simonyi/citeproc-el/wiki/Citation-types-and-commands

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

best regards,

András

  >> 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, covers
  > 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ás and John for their opinion about it. I'd love to hear from
  > everyone involved in the last round of discussion about the subject,
  > too.



  > Regards,

  > --
  > Nicolas Goaziou


reply via email to

[Prev in Thread] Current Thread [Next in Thread]