Aloha Nicolas,
Good news! I'm looking forward to using this facility.
Thanks to all the contributors.
All the best,
Tom
Nicolas Goaziou <m...@nicolasgoaziou.fr> writes:
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,
--
Thomas S. Dye
https://tsdye.online/tsdye