Hello,

I think the "wip-cite-new" branch is in good shape now. As
a consequence, I'd like to merge it tomorrow.

It is documented, but the documentation is scattered across the various
"oc" libraries, and some threads in the mailing list. I'll do a summary
here, from a user point of view.

--8<---------------cut here---------------start------------->8---
Basically, in order to use it, you need to first set-up a bibliography,
using one or more "bibliography" keywords. <C-c '> on such a keyword
visits the related file. Out of the box, Org supports JSON-CSL and
BibTeX (or biblatex) bibliographies.

Then, citations can be inserted with the following syntax:

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

Spaces are meaningful except those after the initial colon and before
the closing bracket.

Every part of the syntax 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]

The "style" part is detailed below, in the part related to export.

Org can insert or edit citations with <C-c C-x @> (and delete them with
<C-u C-c C-x @>), follow them with <C-c C-o>, fontify them, and export
them. These four actions (insert, follow, activate, and export) are
called capabilities.  Libraries responsible for these capabilities are
called citation processors.

You can select one citation processor for each capability, independently
on the others, through the following variables:

- org-cite-activate-processor
- org-cite-export-processors
- org-cite-follow-processor
- org-cite-insert-processor

Out of the box, Org provides the "basic" (in "oc-basic.el") processor
for all of these tasks. It also boasts processors dedicated for export:
"csl", "natbib" and "biblatex".

During export, output for citations is controlled by their style, which
is an Org label that the export processor may recognize and associate to
a specific display, or fall-back to a default style (called "nil"). For
example, most processors support "noauthor" and "text" styles.

Some styles can accept a variant, with the syntax "style/variant".
Again, it's up to the processor to associate it to a specific display.
Common variants include "bare", "caps" or "full".  They also accept
short-hands, like "b", "c" and "f".  Please refer to the export
processors' libraries ("oc-basic.el", "oc-csl.el", …) for more information.

It is possible to define a default style for a whole document (with
"cite_export"), or for all documents (with `org-cite-export-processors').

References are displayed with the "print_bibliography" keyword. It is
possible to add parameters to its value, as some export processors could
make use of them.
--8<---------------cut here---------------end--------------->8---

Please let me know if there are any objections to the merge.

Regards,
--
Nicolas Goaziou