emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
To: Org Mode List <emacs-orgmode@gnu.org>
Subject: Notes about citations in Org (part 3)
Date: Thu, 29 Apr 2021 16:04:17 +0200	[thread overview]
Message-ID: <8735v91926.fsf@nicolasgoaziou.fr> (raw)

Hello,

This post is an update about "wip-cite-new" branch, which I rebased
a few minutes ago. It introduces changes that make previous reports
obsolete. In particular, the "demo" I wrote in the previous thread is no
longer applicable directly, even though the ideas developed there still
hold. Please comment on this thread from now on.

The first noteworthy changes are about the syntax. 

1. I re-introduced objects in prefixes and suffixes, which can again
   contain usual emphasis (bold, italic, strike-through, underscore,
   code, verbatim), subscript, superscript, entities and LaTeX
   fragments.

2. I removed support for "suppress author" minus symbol.

The complete syntax is now

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

Everything is optional, except the brackets, "cite" and the colon. Also
the citation must contain at least a key. So its minimal form is:

  [cite:@key]

Spaces are meaningful in prefixes and suffixes, except for those right
after the colon and those before the closing bracket.

As a reminder, the syntax also supports the following keywords.

  #+bibliography: file
  #+cite_export: [processor] [bibliography-style] [citation-style]
  #+print_bibliography: [style]

For complete information about styles, please refer to the last post,
"(Not so) Short note about citations in Org".

From a technical standpoint, as a consequence of item 1,

  (org-element-property :prefix citation)

or

  (org-element-property :prefix citation-reference)

may return so-called "secondary strings", i.e., lists of strings and
objects. In order to deal with this additional complexity, I implemented
some specific tooling in "oc.el": `org-cite-concat' and
`org-cite-mapconcat' are similar to `concat' and `mapconcat', but can
also operate on secondary strings and objects. For example, a processor
developer could write:

  (org-cite-concat "(" (org-element-property :prefix citation) ")")

and later export the result with `org-export-data' as if the central
argument were a string.

This new revision also introduces additional tooling, which I won't
comment but is worth looking at if you consider giving a try at writing
a citation processor: `org-cite-key-number', `org-cite-wrap-citation',
`org-cite-make-paragraph', and `org-cite-emphasize'.

The other incompatibility is about function signatures for
`:export-bibliography' and `:export-finalizer' keywords. This change
should not be an issue at this point in the development. Citation
processors are registered using `org-cite-register-processor'. Its
docstring follows:

--8<---------------cut here---------------start------------->8---
Mark citation processor NAME as available.

NAME is a symbol.  BODY is a property list, where the following optional keys
can be set:

  `:activate'

    Function activating a citation.  It is called with a single argument: a
    citation object extracted from the current buffer.  It may add text
    properties to the buffer.  If it is not provided, `org-cite-fontify-default'
    is used.

  `:export-bibliography'

    Function rendering a bibliography.  It is called with five arguments:
    the list of citation keys used in the document, as strings, a list
    of bibliography files, the style, as a string or nil, the export back-end,
    as a symbol, and the communication channel, as a property list.

    It is called at each \"print_bibliography\" keyword in the parse tree.
    It may return a string or nil.  When it returns nil, the keyword is ignored.
    Otherwise, the string it returns replaces the keyword in the export output.

  `:export-citation'    (mandatory for \"export\" capability)

    Function rendering citations.  It is called with four arguments: a citation
    object, the style, as a string or nil, the export back-end, as a symbol,
    and the communication channel, as a property list.

    It is called on each citation object in the parse tree.  It may return
    a string or nil.  When it returns nil, the citation is ignored.  Otherwise,
    the string it returns replaces the citation object in the export output.

  `:export-finalizer'

    Function called at the end of export process.  It must accept six arguments:
    the output, as a string, a list of citation keys used in the document,
    a list of bibliography files, a list of bibliography styles requested by
    \"print_bibliography\" keywords, as strings or nil, the export back-end,
    as a symbol, and the communication channel, as a property list

    It must return a string, which will become the final output from the export
    process, barring subsequent modifications from export filters.

  `:follow'

    Function called to follow a citation.  It accepts two arguments, the
    citation or citation reference object at point, and any prefix argument
    received during interactive call of `org-open-at-point'.
--8<---------------cut here---------------end--------------->8---

Ah! I almost forgot… This new revision introduces a poor man citation
processor for BibTeX bibliography files, named "basic", in the file
"oc-basic.el". Here is its commentary section:

--8<---------------cut here---------------start------------->8---
The `basic' citation processor provides "activate", "follow" and
"export" capabilities.

More specifically, "activate" capability re-uses default
fontification, but highlights with `error' face any unknown
citation key according to the bibliography defined in the document.

On a citation key, "follow" capability moves point to the
corresponding entry in the current bibliography.  Elsewhere on the
citation, it asks the user to follow any of the keys cited there,
with completion.

"export" capability supports the following styles for citations:
  - author
  - nocite
  - note
  - numeric
  - text
  - year
  - author-year (default)
It also supports the following styles for bibliography:
  - plain
  - numeric
  - author-year (default)

It assumes bibliography files are in BibTex format.

Disclaimer: this citation processor is meant to be a proof of
concept, and possibly a fall-back mechanism when nothing else is
available. It is too limited for any serious use case.

With that out of the way, if you still want to use this processor,
you may set `org-cite-activate-processor',
`org-cite-follow-processor', or `org-cite-export-processor' to
`basic'.
--8<---------------cut here---------------end--------------->8---

As pointed out above, don't expect too much from it. Nevertheless,
feedback is welcome. Improvements are welcome too, but at this point,
I would suggest to spend energy porting "citeproc-org" or "org-ref" to
this API instead.

Regards,
-- 
Nicolas Goaziou


             reply	other threads:[~2021-04-29 14:06 UTC|newest]

Thread overview: 56+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-04-29 14:04 Nicolas Goaziou [this message]
2021-04-29 14:31 ` Notes about citations in Org (part 3) Bruce D'Arcus
2021-05-01  5:46 ` Bastien
2021-05-03 13:47   ` Eric S Fraga
2021-05-03 13:58     ` Bruce D'Arcus
2021-05-04  7:45       ` Eric S Fraga
2021-05-03 16:48     ` Nicolas Goaziou
2021-05-03 17:46       ` Bruce D'Arcus
2021-05-04  7:46       ` Eric S Fraga
2021-05-04  9:33       ` Nicolas Goaziou
2021-05-04  9:51         ` Eric S Fraga
2021-05-04 10:10           ` Joost Kremers
2021-05-04 10:31             ` Denis Maier
2021-05-04 12:05             ` Eric S Fraga
2021-05-04 10:11           ` Bruce D'Arcus
2021-05-04 12:06             ` Eric S Fraga
2021-05-04 10:17           ` Nicolas Goaziou
2021-05-04 10:48             ` Bruce D'Arcus
2021-05-04 11:58               ` Bruce D'Arcus
2021-05-04 12:16                 ` Eric S Fraga
2021-05-04 13:15                   ` Nicolas Goaziou
2021-05-04 13:21                     ` Bruce D'Arcus
2021-05-04 13:28                       ` Bruce D'Arcus
2021-05-04 15:20                         ` Bruce D'Arcus
2021-05-04 15:46                           ` Eric S Fraga
2021-05-04 15:54                             ` Bruce D'Arcus
2021-05-04 16:59                               ` Nicolas Goaziou
2021-05-04 17:28                                 ` Bruce D'Arcus
2021-05-04 20:22                                   ` Nicolas Goaziou
2021-05-05  5:50                                     ` Eric S Fraga
2021-05-04 18:24                                 ` Bruce D'Arcus
2021-05-04 19:04                                   ` András Simonyi
2021-05-05  6:10                                     ` Eric S Fraga
2021-05-05 14:24                                     ` Nicolas Goaziou
2021-05-05 14:13                                   ` Nicolas Goaziou
2021-05-05  5:48                                 ` Eric S Fraga
2021-05-05  9:37                                   ` Bruce D'Arcus
2021-05-05  9:46                                     ` Denis Maier
2021-05-05 11:08                                     ` Eric S Fraga
2021-05-05 16:50                                 ` Maxim Nikulin
2021-05-05 17:16                                   ` Bruce D'Arcus
2021-05-06  6:20                                     ` Eric S Fraga
2021-05-06 11:36                                     ` Maxim Nikulin
2021-05-06 11:53                                       ` Bruce D'Arcus
2021-05-06 15:57                                         ` Maxim Nikulin
2021-05-06 16:14                                           ` Bruce D'Arcus
2021-05-02 14:41 ` Bruce D'Arcus
2021-05-02 14:51   ` Nicolas Goaziou
2021-05-02 15:19     ` Bruce D'Arcus
2021-05-02 19:32       ` Nicolas Goaziou
2021-05-02 19:55         ` Bruce D'Arcus
2021-05-03 16:42           ` Nicolas Goaziou
2021-05-03 22:25             ` Bruce D'Arcus
2021-05-04  6:47               ` Nicolas Goaziou
2021-05-04  7:21                 ` Denis Maier
2021-05-04 10:54                 ` Bruce D'Arcus

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=8735v91926.fsf@nicolasgoaziou.fr \
    --to=mail@nicolasgoaziou.fr \
    --cc=emacs-orgmode@gnu.org \
    /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).