From: John Kitchin <jkitchin@andrew.cmu.edu>
To: "András Simonyi" <simonyi@all.hu>
Cc: tumashu <tumashu@163.com>, emacs-orgmode <emacs-orgmode@gnu.org>,
Nicolas Goaziou <mail@nicolasgoaziou.fr>
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: <87in8jaywk.fsf@all.hu>
[-- 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 <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 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 Should wip-cite branch be merged to master? 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' \
--to=jkitchin@andrew.cmu.edu \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
--cc=simonyi@all.hu \
--cc=tumashu@163.com \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public 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).