Re: [wip-cite-new] Merging tomorrow?

["Thomas S. Dye" <tsd@tsdye.online>]

Aloha Nicolas,

Good news! I'm looking forward to using this facility.

Thanks to all the contributors.

All the best,
Tom

Nicolas Goaziou <mail@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