emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Timothy <tecosaur@gmail.com>
To: John Kitchin <jkitchin@andrew.cmu.edu>
Cc: Vikas Rawal <vikasrawal@gmail.com>,
	emacs-orgmode@gnu.org, Nicolas Goaziou <mail@nicolasgoaziou.fr>
Subject: Re: citations: org-cite vs org-ref 3.0
Date: Mon, 21 Mar 2022 09:39:13 +0800	[thread overview]
Message-ID: <87r16wukx0.fsf@gmail.com> (raw)
In-Reply-To: <m2sfrc149c.fsf@andrew.cmu.edu>

[-- Attachment #1: Type: text/plain, Size: 13908 bytes --]

Hi John,

Thanks for your considered response.

When you contrast org-cite and org-ref, you say:

> With org-ref, bib(la)tex export is almost fully supported, and is easy,

I find this odd as org-cite supports bib(la)tex export, and rather easily.

┌────
│ #+bibliography: references.bib
│ #+cite_export: biblatex authortitle/authortitle-ibid
│ 
│ [cite:@key] etc.
│ 
│ #+print_bibliography:
└────

The limitation which I think is on your mind is that not all bib(la)tex commands
are supported, and not in the “usual” form. For instance, to get `pnotecite' one
would use `[cite/locators:]'. However, to get a 1-to-1 name mapping, you can just
customise `org-cite-biblatex-styles'. For instance, `parencite' is not currently
available, but if I just add `("parencite" nil "parencite" nil nil)' I can then do
`[cite/parencite:]' or if I replace the first `"parencite"' with `"paren"', just
`[cite/paren:]'.

A package could be created, say `org-cite-literal-biblatex' which is just a copy
of `oc-biblatex.el' with a different default `org-cite-biblatex-styles' and
`org-cite-biblatex-style-shortcuts' (or just sets those variables in
`org-cite-biblatex'). As far as I can tell this would provide exactly the
functionality you say org-cite can’t provide but org-ref does.

You can already use `.bib' files, and so frankly I cannot myself see the point in
org-ref’s existence beyond bifurcating the community on this. At this point the
only remaining motivation I see is old documents and current users, and for this
a migration tool seems more appropriate.

I don’t mean to be overly critical, however this is my current honest assessment
of the situation.

–
All the best,
Timothy

John Kitchin <jkitchin@andrew.cmu.edu> writes:

> I do not think it is productive for the community to say or consider it
> is a sad situation. Many good things have emerged from these
> discussions, even if it is not yet consensus on a solution. It is a
> complex problem, with many years of effort by many people on each side.
> That is an indication of how ambitious this project is and that there
> may be more than one solution that is needed. It pains me quite a bit
> there is a sentiment of fractionation, and that I may be contributing to
> it.
>
> My regular job workload the past few years has been crushing, and I have
> not had the time to participate in this that I wish I had. I am not sure
> I can add much here without sounding or feeling defensive about org-ref,
> and my decision to continue supporting and developing it. I have thought
> about this for most of the day, and in the (very long, apologies in
> advance) response that follows I will do my best to provide a balanced
> perspective (from my point of view) on the situation.
>
> Some specific context that is important to me is that I wrote org-ref
> long ago to solve a specific problem for me in the preparation of
> scientific publications that are destined for LaTeX export. I intended
> it to provide nearly equivalent bib(la)tex citation export, and as
> reasonable an export as possible for everything else. I use org-ref
> professionally, and it is a complete solution for me. I simply cannot
> compromise on the capability org-ref provides me, or wait for an
> alternative complete solution in org-mode. I have work I have to do now,
> and org-ref lets me do it. This alone is reason enough for me to
> continue using, developing and supporting org-ref. I understand org is
> not intended to be a substitute for writing LaTeX, but it is a fact of
> my job that I have to do that.
>
> There are more than 8 years of legacy org-ref documents. I have written
> 40+ scientific papers with it, and countless technical documents with
> more than 8000 cite links among them. org-ref has exceeded 190K
> downloads from MELPA, so I feel obligated to maintain org-ref for
> myself, and those users. org-ref may be heavyweight in bundling a lot of
> capability together that could be separated into individual packages,
> but it is also convenient for people who need it, and a GitHUB issue or
> pull request away from new features. I remain committed to supporting
> this, and I do it in a way I can manage, hence the monolithic package
> design.
>
> org-cite was also developed to solve some specific citation problems for
> others that org-ref did not address well at the time it was started. I
> believe those were issues like better pre/post note support, and
> integration with CSL.
>
> I think org-ref and org-cite have different priorities, they solve
> different problems with different approaches, and they have different
> pros and cons. I believe there are mutually incompatible compromises one
> must make here because the specific choices you make determine what is
> easy and what is possible. There is not a direct mapping of bib(la)tex
> and CSL as a citation processor. They are different programs and they
> don’t share citation commands, or style information. It is inevitable
> that something will be lost in the translation between these from a
> single source like org, and whether that loss is acceptable depends on
> what you need. For many things, close enough is ok for me, but for
> manuscripts and proposals, they must be perfect, and in bib(la)tex form
> for the journals I publish in. It is not that one thing is possible in
> one and not the other; it is that you have to compromise one to do the
> other no matter what you choose and that typically makes one thing or
> the other easier to do. I am not even sure it is possible to do
> everything one can do in bib(la)tex with CSL, for example, I don’t know
> the equivalent of  in CSL. org-ref sides on making bib(la)tex
> easy, and CSL is possible.
>
> With org-cite, CSL can be readily used across export backends, more
> bibliography database formats are supported, and it is also possible to
> get LaTeX export, although there is no goal to fully support all of
> bib(la)tex. A pure org approach (e.g. org-files as bibliography
> database) can be used, there are a lot of CSL styles to work with, and
> you can develop or adapt your own style if needed. With reasonable
> defaults this should be a straightforward introduction to using
> citations for new users that works out of the box. I support that.
>
> With org-ref, bib(la)tex export is almost fully supported, and is easy,
> and other exports via CSL are possible. Of course, you must have a
> working LaTeX installation, only bibtex databases are supported, and
> working knowledge of bib(la)tex is required to leverage this. Whether
> you want it or not, you get a lot of extra utilities for getting bibtex
> entries from a DOI, and support for cross-references, indexes,
> glossaries and acronyms. This is a lot to ask of people who don’t need
> it, and convenient for those who do. I support this.
>
> Which one of these approaches is right depends on what you want to be
> easy. Neither is right or wrong, that is determined by what you need at
> the time and what you prioritize in your solution. It is even possible
> you need both approaches at different times. The two approaches are not
> compatible, but it is org-mode after all, and you can certainly convert
> back and forth between them for the most part.
>
> Both projects have benefited from this discussion a lot. org has
> org-cite now, and org-ref now handles pre/post notes like org-cite does,
> it supports CSL much better, and is even a little more modular, lighter
> weight, and more easily integrated with other completion backends than
> ivy or helm. That should broadly be viewed as a win-win situation.
>
> Here are some factors that have prevented me from deprecating org-ref. I
> spent about a month and half trying to get a solution to this at
> <https://github.com/jkitchin/org-ref-cite>, and I don’t make these
> observations lightly. That solution was complete and highly functional
> for org-cite, but as I describe below not a replacement for org-ref at
> this time. I still welcome a new maintainer for this code.
>
> Cross-references are critical for me; without them, there is no path
> forward for me with org-cite. I did work on a cross-reference approach
> that leveraged org-cite syntax
> (<https://github.com/jkitchin/org-ref-cite/issues/16>), but there was not
> much appetite for the approach so I abandoned that. There are
> cross-reference capabilities in org, that may be suitable for some
> applications, but they do not come close to what org-ref offers, and
> that the kind of technical documents I write require. For me, any
> cross-reference capability would also have to support what is possible
> in LaTeX, and preferrably look similar to the LaTeX commands. It has not
> been possible to write an orthogonal package that could co-exist with
> org-ref to address this; this would require a new syntax for
> cross-references in my opinion. My opinion is that practically citations
> and cross-references are just links to a place in your document (either
> a figure/table/section/etc, or an entry in a bibliography). In org-ref,
> both are represented by links; of course, they have different types and
> functions, but they both have follow like actions. My opinion seems to
> be in the minority on this.
>
> I do not like the abstraction away from LaTeX cite commands in org-cite.
> This is an example of a compromise between LaTeX and CSL. They do not
> share common citation commands, so you can either choose one or the
> other, or make a new abstraction that generalizes them. I strongly favor
> the LaTeX commands because I write for LaTeX export, and there is
> extensive documentation for how to cite in LaTeX and what to expect.
> Clearly org-cite favors using the standardized abstractions in org-cite,
> and then mapping them to the LaTeX commands I think. My perspective on
> this is partially one of an educator; I have taught a lot of people how
> to use org-mode for technical writing. This layer of abstraction adds
> additional complexity to documentation, and in teaching people what to
> do. As a LaTeX-centric user, that abstraction adds an additional
> cognitive load while writing I find unwelcome. I concede that it also
> reflects “what I do”, that org is not LaTeX, and that others may have a
> more CSL centric perspective. org-cite is for them. I can see that the
> abstraction away from the LaTeX cite commands strengthens the org is not
> LaTeX philosophy, and will serve part of the community well. If I wasn’t
> required to generate LaTeX documents, and teach others how to do it, I
> would not feel so strongly.
>
> It is my opinion that the modularity of org-cite is a challenge. I think
> it is too difficult to configure, and difficult to support, even more so
> than org-ref. I know my opinion differs from many on the list who want
> modularity and configurability. I have supported org-ref since around
> 2014, and even the modularity there (helm or ivy) has been a challenge
> to support. org-ref has always been configurable, but monolithic. Still,
> I learned a lot from Bruce (thank you!) that pushed me to redesign parts
> of org-ref to be more modular and more easily pluggable to other
> completion backends, and less specific on ivy/helm where practical.
> There are limitations to this I learned about, compromises one has to
> choose in doing it, and consequences in maintenance, support and
> documentation from them. We still don’t fully agree on some of these
> points, but org-ref is closer to that ideal than it was. Maybe one day I
> will abandon ivy like I did helm many years ago and feel differently
> about this, but that day is sufficiently far away that I don’t see it
> now.
>
> Finally, the org-cite code is magnificent, and written at a level well
> above my coding skills. I am grateful to those who wrote it, and
> especially to Nicolas, for the opportunity to learn from it. The code I
> wrote in org-ref-cite was challenging. org-cite uses (IMO) advanced
> emacs-lisp techniques, and more complex data structures than I am
> accustomed to. I learned a lot studying the org-cite code, but I will be
> honest that I find it difficult to make contributions to. That gave me
> pause in continuing to develop it. It is fair to say that org-cite
> showed me some ways to address limitations of org-ref that I did not see
> before, org-ref is better for it, and the writing community that uses
> pre/post notes and biblatex is much better served as a result.
>
> Where does this leave me, org-ref and org-cite? I still have differences
> of opinion on design choices between them, and those differences are
> likely irreconcilable. These differences arise from my experiences in
> writing, teaching, using, developing and supporting org-ref. For those
> who need high fidelity LaTeX export like I do, I think org-ref is still
> a superior solution. For everyone else, and especially if you do not
> need sophisticated cross-references and don’t want the dependencies of
> org-ref, org-cite is likely the better solution.
>
> I am content to agree to disagree on these points and move forward with
> both packages because they solve different problems, are suitable for
> different communities, and they continue to benefit each other. I can
> see not everyone sees this as a positive situation though, and that has
> weighed heavily upon me lately. These times are heavy enough. Anyway,
> this turned out much longer than I expected, so thanks everyone who has
> contributed to making org better, I hope I got things mostly correct,
> you found it a fair assessment, we might still be friends, and thanks
> for reading to the end.
>
> j

  reply	other threads:[~2022-03-21  1:58 UTC|newest]

Thread overview: 73+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-03-20 12:08 citations: org-cite vs org-ref 3.0 Vikas Rawal
2022-03-20 13:19 ` Nicolas Goaziou
2022-03-20 14:08   ` Vikas Rawal
2022-03-20 14:38     ` Bruce D'Arcus
2022-03-21  0:31   ` John Kitchin
2022-03-21  1:39     ` Timothy [this message]
2022-03-21  8:16       ` Dominik Schrempf
2022-03-21 11:51         ` Bruce D'Arcus
2022-03-21 12:34           ` Dominik Schrempf
2022-03-21 12:52             ` Bruce D'Arcus
2022-03-21 13:05               ` Dominik Schrempf
2022-03-21 13:24                 ` Bruce D'Arcus
2022-03-23 21:27                 ` Nicolas Goaziou
2022-03-23 21:53                   ` Bruce D'Arcus
2022-03-23 22:04                     ` Nicolas Goaziou
2022-03-23 22:47                       ` Bruce D'Arcus
2022-03-24 10:04                         ` Dominik Schrempf
2022-03-21 12:19       ` John Kitchin
2022-03-21 12:42         ` Bruce D'Arcus
2022-03-21 14:06           ` John Kitchin
2022-04-19 22:37             ` Bruce D'Arcus
2022-03-21  3:27     ` Vikas Rawal
2022-03-21 11:51       ` John Kitchin
2022-03-21 17:20         ` Vikas Rawal
2022-03-25 15:53         ` Max Nikulin
2022-03-27 15:33           ` John Kitchin
2022-03-27 15:44             ` Vikas Rawal
2022-03-25 17:10         ` Max Nikulin
2022-03-26 12:41           ` Bruce D'Arcus
2022-03-27 19:40           ` John Kitchin
2022-03-28 12:34             ` Max Nikulin
2022-03-28 13:16               ` Bruce D'Arcus
2022-03-29 15:22                 ` Max Nikulin
2022-03-29 16:14                   ` Bruce D'Arcus
2022-03-30 13:50                     ` Denis Maier
2022-03-31 15:10                     ` Max Nikulin
2022-03-31 17:27                       ` Bruce D'Arcus
2022-04-02 11:41                         ` org-cite, CSL styles and space before citation Max Nikulin
2022-03-30 21:43                   ` citations: org-cite vs org-ref 3.0 John Kitchin
2022-03-21 12:59     ` juh
2022-03-22 13:03       ` indieterminacy
2022-03-23 21:06     ` Nicolas Goaziou
2022-03-27 17:00       ` John Kitchin
2022-03-27 23:17         ` Bruce D'Arcus
2022-03-21 14:40   ` Max Nikulin
2022-03-21 15:19     ` Bruce D'Arcus
2022-03-21 17:00       ` John Kitchin
2022-03-25 15:21         ` Max Nikulin
2022-03-22 14:41       ` Max Nikulin
2022-03-22 17:20         ` Bruce D'Arcus
2022-03-23 12:44           ` Max Nikulin
2022-03-23 14:39             ` Bruce D'Arcus
2022-03-23 15:26               ` Eric S Fraga
2022-03-23 17:17               ` Max Nikulin
2022-03-23 22:50                 ` Bruce D'Arcus
2022-03-26 19:08               ` M. Pger
2022-03-22 23:52     ` Nicolas Goaziou
2022-03-23 16:30       ` Max Nikulin
2022-03-23 23:04         ` Nicolas Goaziou
2022-03-25 16:30           ` Max Nikulin
2022-03-27 15:38           ` John Kitchin
2022-03-27 23:18             ` Bruce D'Arcus
2022-03-20 13:32 ` Bruce D'Arcus
2022-03-20 13:42 ` Ihor Radchenko
2022-03-20 18:12   ` Thomas S. Dye
2022-03-20 20:13     ` Dominik Schrempf
2022-03-20 20:30       ` Vikas Rawal
2022-03-20 20:34       ` Bruce D'Arcus
2022-03-20 22:10         ` Dominik Schrempf
2022-03-20 19:44   ` Bruce D'Arcus
2022-03-20 21:14     ` chris
2022-03-21 14:21       ` John Kitchin
2022-03-21 14:10     ` John Kitchin

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=87r16wukx0.fsf@gmail.com \
    --to=tecosaur@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --cc=jkitchin@andrew.cmu.edu \
    --cc=mail@nicolasgoaziou.fr \
    --cc=vikasrawal@gmail.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).