Re: wip-cite status question and feedback

[Nicolas Goaziou]

Hello,

I cannot answer all open questions as the thread would spread too thin.
So, I'll try to subsume where Org is at the moment, and what need to be
decided.

First things first, I pushed a new branch, "wip-cite-new" in the
repository, with an modified implementation of citation syntax,
hopefully taking into consideration remarks made so far. I didn't squash
"wip-cite" because citeproc-org library suggests to use it, and I didn't
want to break it.

Instead of formally describing the syntax, here are a few boring
examples:

  [cite:@key]
  [cite:-@key]
  [cite:pre @key post]
  [cite:pre @key post; pre -@key2 post]
  [cite: common prefix; pre @key post; pre @key2 post; common suffix]

There is a limitation for prefixes and suffixes: they cannot contain
semicolons or closing square brackets. I'm not sure it is worth
implementing some character escape mechanism, tho.

Now with styles:

  [cite/style: ...]
  [cite/style/substyle: ...]
  [cite/mycitationprocessor/fullcite: ...]
  [cite/foot/text: ...]
  [cite/style/substyle/subsubstyle/OMG: ...]

The forward slash separator gives us local citation style and a name
space. There's no limit on the depth of sub-styles. However style
strings are limited to alphanumeric characters only.

I also removed short citations: 

  Lorem ipsum @doe09 dolor sit amet

They look nice, but I realized this was the same mistake as allowing [1]
to be a footnote reference. False positives are way too common. This
could generate frustration upon export.

I assume [cite:...] is the default citation style, defined at the
citation processor's level. Styled citations override locally the
default style. Again, a processor not handling a given style is expected
to fallback to default style.

As a consequence, there is no special syntax for "author-in-text" style.
But we can suggest one for back-end processors. We might want to stick
to the most complete one, BibLaTeX, IIUC, and /require/ processors to
support, at least:

  [cite/text: ...]
  [cite/paren: ...]

With this bare minimum, we ensure documents are somehow portable between
processors, and, therefore, export back-ends.

Again, this is only a proposal, feedback is welcome. Hopefully we can
move onto the next step: how should we interface citation processors and
Org?

First, I think we agreed on the BIBLIOGRAPHY keyword, with the following
syntax:

  #+BIBLIOGRAPHY: file
  #+BIBLIOGRAPHY: "file"

There can be multiple BIBLIOGRAPHY keywords in a document (and
equivalent node properties). Also, I think Org should support a global
variable, e.g., `org-citation-default-bibliography'.

I also think we defined a keyword to insert a bibliography:

  #+PRINT_BIBLIOGRAPHY: ... options ... (may be specific to citation processors)

I expect the processors to provide Org with a maximum two different
actions: manage and export. For example, AFAIK, Org Ref manages and
exports, citeproc-org/citeproc-el only exports, and a default processor
might realistically limit export to LaTeX and derived and management to
a default fontification of citations.

- Management :: 

  As suggested by John Kitchin, we want something like
  `org-link-parameters'. However, I don't think it makes much sense to
  let different citation processors handle different citations in the
  same buffer.

  Instead we can provide one global function for each of these features:
  - completion
  - fontification (possibly special keymaps, help-echo, etc)
  - following
  - am I missing something?

  Citation processors may operate on the bibliography file, but that's
  out of the scope of Org.
  
  For example, we could introduce the variable
  `org-citation-follow-function', which contains a function called with
  two arguments: the key of the citation to follow, and the list of
  bibliography files active in the buffer. Each citation processor could
  set this function. By default, it would probably be

    (defun org-citation-follow-default (&rest _)
      (message "Please activate a citation processor to follow citations")
      nil)
  
- Export :: 

  In this case, we may want to allow multiple processors for various
  export back-ends. I thought about declaring active processors in
  a document with a keyword, e.g.,

    #+CITATION_PROCESSOR: org-ref :default-style foo :back-ends (latex)
    #+CITATION_PROCESSOR: citeproc :default-style bar 

  and with a global variable, e.g., `org-citation-export-default' which
  could be, e.g.,

    '((default :defaut-style "authoryear" :back-ends (latex)))

  but could become, with appropriate libraries

    '((org-ref :defaut-style "authoryear" :back-ends (latex))
      (citeproc-org :default-style "style-file.csl" :back-ends nil))

  where more specialized back-ends are used first. Note that `latex'
  would mean `latex' and derived back-ends, e.g., `beamer'.

Well, that's all for now. Again, I am not a citation specialist, so
I need feedback. Let's keep the ball rolling!


Regards,

-- 
Nicolas Goaziou