From: John Kitchin <firstname.lastname@example.org> To: "András Simonyi" <email@example.com> Cc: tumashu <firstname.lastname@example.org>, emacs-orgmode <email@example.com>, Nicolas Goaziou <firstname.lastname@example.org> Subject: Re: Should wip-cite branch be merged to master? Date: Mon, 23 Apr 2018 12:42:12 -0700 [thread overview] Message-ID: <CAJ51ETrMHVsN=iJk-dLuo=_qVXf+fO8cYdKtjM2oVhxDQ1wPBw@mail.gmail.com> (raw) In-Reply-To: <email@example.com> [-- Attachment #1: Type: text/plain, Size: 8924 bytes --] 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 @johnkitchin http://kitchingroup.cheme.cmu.edu On Sun, Apr 22, 2018 at 11:17 AM, András Simonyi <firstname.lastname@example.org> 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 > [-- Attachment #2: Type: text/html, Size: 10433 bytes --]
next prev parent reply other threads:[~2018-04-23 19:42 UTC|newest] Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top 2018-04-20 23:01 tumashu 2018-04-21 7:26 ` Nicolas Goaziou 2018-04-21 8:43 ` Christian Moe 2018-04-22 18:17 ` András Simonyi 2018-04-23 19:42 ` John Kitchin [this message] 2018-04-25 19:19 ` Richard Lawrence 2018-04-26 23:34 ` Bastien 2018-04-27 21:07 ` András Simonyi 2018-04-27 23:34 ` Nicolas Goaziou
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style List information: https://www.orgmode.org/ * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to='CAJ51ETrMHVsN=iJk-dLuo=_qVXf+fO8cYdKtjM2oVhxDQ1wPBw@mail.gmail.com' \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: Should wip-cite branch be merged to master?' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Code repositories for project(s) associated with this inbox: https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).