emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: "Bruce D'Arcus" <bdarcus@gmail.com>
Cc: "emacs-orgmode@gnu.org" <emacs-orgmode@gnu.org>,
	"András Simonyi" <andras.simonyi@gmail.com>
Subject: Re: wip-cite status question and feedback
Date: Mon, 12 Apr 2021 15:19:34 +0200	[thread overview]
Message-ID: <87czuzprmh.fsf@nicolasgoaziou.fr> (raw)
In-Reply-To: <CAF-FPGMY214x+c8P8tUm0wNTvDt2O8G_8KK9jKE0VbzZvzASYg@mail.gmail.com> (Bruce D'Arcus's message of "Sun, 11 Apr 2021 19:15:44 -0400")

Hello,

"Bruce D'Arcus" writes:

> Maybe since Nicolas has been around lately, he can weigh in?

I guess I can make a summary about the current state of the citations
branch, i.e., what is done, what is missing.

There are three major steps to complete in order to add citations in
Org: defining the syntax, designing the Org API for citation processors,
and writing a default processor.

The syntax is complete in "wip-cite-new" branch. For the record, in its
full glory, it can look like this:

  [cite/style: global prefix; prefix -@key suffix ; ... ; global suffix]

"/style", "global prefix", "prefix", "-" marker, "suffix" and "global
suffix" are all optional. So, in its minimal form, it can be as simple
as:

  [cite:@Doe:1995a]

The syntax also includes a new #+bibliography keyword, which, when
paired with a new `org-cite-global-bibliography', defines global or
local bibliographies.

For exporting needs, I also introduced #+print_bibliography,
#+citation_style and #+bibliography_style keywords.

Now about the API, which is partly implemented on a local branch.

Citations processors, in addition to any tools they may provide, can
integrate into Org in three distinct areas: opening (with
`org-open-at-point'), fontification, and export.

  - "opening" action is straightforward. All is needed for the processor
    is to provide a function accepting two arguments: the citation key,
    as a string, and possibly a universal argument, which it may ignore,
    or not.

    All this is already implemented locally.

  - "exporting" action is trickier, because there are multiple ways to
    do the integration, and, since I'm not an implementor for citation
    processors, I don't have an accurate view about what is the best
    design. Anyway, here is the

    First, export happens as pre-process, before export back-ends are
    introduced. IOW, export back-ends are never going to see a citation
    object, which means no support whatsoever is needed on their end.

    Support export requires two functions. The first function is
    responsible for rendering a bibliography. Its arguments are the list
    of citations in the document, the list of bibliography files, the
    style, if any, and the export back-end. It should return a string.

    The second mandatory function is obviously responsible for rendering
    citations. It is called with a citation object, the desired style,
    if any, and the export back-end, the full list of citations objets
    in the document, and the list of bibliography files. It should also
    return a string. Org provides a helper function to determine the
    footnote containing a citation (and its label, or number) from
    a citation object.

    In the functions described above, I don't know if the arguments are
    sufficient. I would love to hear about citeproc-org and org-ref
    developers about this.

    Also, note that style is an indication. Export is requested to
    handle regular [cite:...] syntax. Unknown styles should fall-back to
    this.

  - "fontification" is meant to give full access to face selection, what
    is really displayed, additional keymaps, all using a single
    function.

    At the moment, I have no idea about what arguments would be useful.
    I think John Kitchin gave ideas about this already on this ML.
    I have to re-read his posts on the subject. In any case, feedback
    welcome.

    This not implemented yet.

A citation processor does not need to provide integration in all these
areas. Users may be able to mix and match processors. This is another
(minor) point which is yet to be designed. How is a user supposed to
select a processor for each integration area? It could be done through
three variables, e.g.,

  (setq org-cite-display-processor 'org-ref)
  (setq org-cite-export-processor 'citeproc)
  (setq org-cite-follow-processor 'default)

I think it is unlikely for a user to locally select "display" and
"follow" processors. However, we need a way to use a local export
processor for a given document. I may need to introduce
a #+citation_processor keyword during export. Any other idea?

The last step is implementing a default processor. The point is to
provide a self-contained, very basic processor handling all three areas
described above.

I started implementing one. It relies on built-in bibtex.el library, so
it assumes bibliography is written as a BibTex file. At the moment it
properly "follows" citations. It also exports citations as (Name, date).
However, it doesn't export bibliographies yet. It does not fontify
either.

As a conclusion, besides the syntax, the branch is not ready for
inclusion yet. There are a few design questions about the API to answer.
Once done, and as long as no one has high expectations about the default
processor, this last part should not be too hard to complete.


Regards,
-- 
Nicolas Goaziou


  reply	other threads:[~2021-04-12 13:20 UTC|newest]

Thread overview: 139+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-04-07 15:15 Bruce D'Arcus
2020-04-07 17:51 ` Nicolas Goaziou
2020-04-07 18:27   ` Bruce D'Arcus
2020-04-07 18:31     ` Bruce D'Arcus
2020-04-07 21:13     ` Joost Kremers
2020-04-08  0:01       ` Bruce D'Arcus
2020-04-08  9:16         ` Joost Kremers
2020-04-08  9:32     ` Nicolas Goaziou
2020-04-08 12:19       ` Bruce D'Arcus
2020-04-08 13:39         ` John Kitchin
2020-04-08 16:12           ` Bruce D'Arcus
2020-04-09  7:38         ` Albert Krewinkel
2020-04-09  9:30           ` Bruce D'Arcus
2020-04-09  9:46             ` Bruce D'Arcus
2020-04-09 10:05               ` Bruce D'Arcus
2020-04-09 23:17                 ` Nicolas Goaziou
2020-04-10  1:17                   ` Bruce D'Arcus
2020-04-10  5:38             ` Albert Krewinkel
2020-04-11 11:41       ` Bruce D'Arcus
2020-04-13 12:05       ` Gustav Wikström
2020-04-13 12:33         ` Bruce D'Arcus
2020-05-24 12:12           ` Bastien
2020-05-24 13:17             ` Bruce D'Arcus
2020-05-29 21:59               ` András Simonyi
2020-05-29 22:24                 ` Bruce D'Arcus
2020-05-29 22:58                 ` Bruce D'Arcus
2020-06-03 14:40                   ` Bastien
2020-06-03 14:53                     ` Bruce D'Arcus
2020-12-14 21:24                       ` Bruce D'Arcus
2021-03-24 13:22                       ` Bruce D'Arcus
2021-03-24 18:27                         ` M. ‘quintus’ Gülker
2021-04-11 23:15                           ` Bruce D'Arcus
2021-04-12 13:19                             ` Nicolas Goaziou [this message]
2021-04-12 18:53                               ` András Simonyi
2021-04-16 17:05                               ` András Simonyi
2021-04-16 17:23                                 ` Bruce D'Arcus
2021-04-18 13:11                                 ` Nicolas Goaziou
2021-04-18 13:35                                   ` Ihor Radchenko
2021-04-18 13:37                                     ` Bruce D'Arcus
2021-04-21 19:57                                     ` John Kitchin
2021-04-21 20:09                                       ` Bruce D'Arcus
2021-04-21 20:57                                         ` John Kitchin
2021-04-21 20:26                                   ` John Kitchin
2021-04-21 20:54                                     ` Bruce D'Arcus
2021-04-22  2:47                                     ` Timothy
2021-04-22 12:07                                       ` Bruce D'Arcus
2021-04-22 12:34                                         ` Timothy
2021-04-21 21:47                                   ` András Simonyi
2021-04-21 23:51                                     ` Nicolas Goaziou
2021-04-22  0:01                                       ` Bruce D'Arcus
2021-04-22  0:15                                         ` Nicolas Goaziou
2021-04-23 11:49                                           ` Nicolas Goaziou
2021-04-23 12:55                                             ` András Simonyi
2021-04-23 13:10                                               ` Bruce D'Arcus
2021-04-23 13:24                                                 ` Bruce D'Arcus
2021-04-23 14:50                                                   ` András Simonyi
2021-04-23 22:08                                                   ` Bruce D'Arcus
2021-04-24 17:37                                                   ` M. ‘quintus’ Gülker
2021-04-24 17:47                                                   ` Nicolas Goaziou
2021-04-24 18:39                                                     ` Bruce D'Arcus
2021-04-26 14:54                                                       ` Bruce D'Arcus
2021-04-26 20:35                                                         ` Denis Maier
2021-04-27 10:12                                                           ` Bruce D'Arcus
2021-04-27 10:20                                                             ` Timothy
2021-04-27 11:44                                                             ` Denis Maier
2021-04-27 12:32                                                               ` Bruce D'Arcus
2021-04-27 13:58                                                                 ` Denis Maier
2021-04-27 14:07                                                                   ` Bruce D'Arcus
2021-04-27 14:50                                                                     ` Denis Maier
2021-04-30 13:28                                                       ` Nicolas Goaziou
2021-04-30 21:47                                                         ` Denis Maier
2021-05-01 11:09                                                           ` Nicolas Goaziou
2021-05-01 13:26                                                           ` Bruce D'Arcus
2021-05-02 21:58                                                             ` Denis Maier
2021-05-02 22:18                                                               ` Bruce D'Arcus
2021-05-02 23:30                                                                 ` Bruce D'Arcus
2021-05-05 13:46                                                                 ` Bruce D'Arcus
2021-05-05 18:14                                                                   ` M. ‘quintus’ Gülker
2021-05-05 18:27                                                                     ` Bruce D'Arcus
2021-05-06 17:05                                                                       ` M. ‘quintus’ Gülker
2021-05-06  8:08                                                                     ` Denis Maier
2021-04-24 13:14                                               ` Nicolas Goaziou
2021-04-23 12:03                                     ` Nicolas Goaziou
2021-04-23 13:34                                       ` András Simonyi
2021-04-17 19:13                               ` M. ‘quintus’ Gülker
2021-04-18 16:17                                 ` Nicolas Goaziou
2021-04-20 13:32                                   ` Matt Price
2021-04-21 17:07                                     ` Nicolas Goaziou
2021-04-21 17:53                                       ` Bruce D'Arcus
2020-04-10  9:29 denis.maier.lists
2020-04-10 12:22 ` Bruce D'Arcus
2020-04-10 22:56 ` Nicolas Goaziou
2020-04-11 21:42   ` denis.maier.lists
2020-04-11 22:05     ` Bruce D'Arcus
2020-04-12 10:38       ` Nicolas Goaziou
2020-04-12 11:15         ` Bruce D'Arcus
2020-04-12 14:02           ` Nicolas Goaziou
2020-04-12 14:25             ` Bruce D'Arcus
2020-04-12 15:32               ` Nicolas Goaziou
2020-04-12 15:44                 ` Bruce D'Arcus
2020-04-12 15:57                   ` Nicolas Goaziou
2020-04-12 17:17                     ` Bruce D'Arcus
2020-04-12 20:49                 ` denis.maier.lists
2020-04-12 22:19                   ` Nicolas Goaziou
2020-04-13  8:33                     ` Stefan Nobis
2020-04-13 10:02                       ` Denis Maier
2020-04-13 10:11                         ` denis.maier.lists
2020-04-13 10:05                       ` Bruce D'Arcus
2020-04-13 10:14                       ` denis.maier.lists
2020-04-13  9:58                     ` Bruce D'Arcus
2020-04-13 10:09                     ` denis.maier.lists
2020-04-13 10:10                     ` Joost Kremers
2020-04-13 10:46                       ` Stefan Nobis
2020-04-15  5:54                       ` Richard Lawrence
2020-04-15 10:07                         ` Joost Kremers
2020-04-18  9:34                           ` Richard Lawrence
2020-04-18 10:56                         ` Bruce D'Arcus
2020-04-18 12:48                           ` Richard Lawrence
2020-04-18 13:17                             ` Bruce D'Arcus
2020-04-18 13:22                               ` Bruce D'Arcus
2020-04-18 20:23                                 ` Denis Maier
2020-04-18 20:28                                 ` denis.maier.lists
2020-04-19  9:11                               ` Richard Lawrence
2020-04-25 16:19                                 ` Nicolas Goaziou
2020-04-25 17:00                                   ` Bruce D'Arcus
2020-04-25 20:03                                     ` Nicolas Goaziou
2020-04-25 21:18                                       ` Bruce D'Arcus
2020-05-01 17:38                                         ` Richard Lawrence
2020-05-01 17:54                                           ` Bruce D'Arcus
2020-05-02 14:06                                             ` Nicolas Goaziou
     [not found]                                               ` <2fbf14cf-ae8c-4f7c-27f7-33771aa99492@mailbox.org>
2020-05-02 16:34                                                 ` Nicolas Goaziou
2020-05-02 17:24                                                   ` Denis Maier
2020-05-02 13:13                                           ` Nicolas Goaziou
2020-05-02 13:45                                             ` Bruce D'Arcus
2020-05-02 20:45                                             ` Richard Lawrence
2020-04-29  9:14                                   ` Denis Maier
2020-05-02  9:51                                     ` Nicolas Goaziou
2020-05-02 11:53                                       ` Bruce D'Arcus
2020-04-18 20:38                           ` Joost Kremers

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=87czuzprmh.fsf@nicolasgoaziou.fr \
    --to=mail@nicolasgoaziou.fr \
    --cc=andras.simonyi@gmail.com \
    --cc=bdarcus@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    --subject='Re: wip-cite status question and feedback' \
    /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).