doc/org-manual.org (Citations): Enhance

* doc/org-manual.org (Citations): Enhance.

This is based on a preliminary draft provided by Emmanuel Charpentier.

doc/org-manual.org

@@ -16515,43 +16515,122 @@ keywords.
 :END:
 #+cindex: citation
 
-Org 9.5 provides a new library =oc.el= which provides tooling to
-handle citations in Org, e.g., activate, follow, insert, and export
-them, respectively called "activate", "follow", "insert" and "export"
-capabilities.  Libraries responsible for providing some, or all, of
-these capabilities are called "citation processors".
-
-Such processors are defined using ~org-cite-register-processor~.
-Using this function, it is possible, in addition to giving it a name,
-to attach functions associated to capabilities.  As such, a processor
-handling citation export must set the ~:export-citation~ property to
-an appropriate function.  Likewise, "activate" capability requires an
-appropriate ~:activate~ property, "insert" requires ~:insert~ property
-and, unsurprisingly, "follow" capability implies ~:follow~ property.
-
-As a user, the first thing to do is setting a bibliography, either
+As of Org 9.5, a includes a new library =oc.el= provides tooling to
+handle citations in Org via "citation processors" that offer some or
+all of the following capabilities:
+
+- "activate" :: Fontification, tooltip preview, etc.
+- "follow" :: At-point actions on citations via ~org-open-at-point~.
+- "insert" :: Add and edit citations via ~org-cite-insert~.
+- "export" :: Via different libraries for different target formats.
+
+The user can configure these with ~org-cite-active-processor~,
+~org-cite-follow-processor~, ~org-cite-insert-processor~, and
+~org-cite-export-processors~ respectively.
+
+The included "basic" processor provides all four capabilities.
+
+** Citations
+
+Before adding citations, first set one-or-more bibliographies, either
 globally with ~org-cite-global-bibliography~, or locally using one or
-more "bibliography" keywords.  Then one can select any registered
-processor for each capability by providing a processor name to the
-variables ~org-cite-activate-processor~ and
-~org-cite-follow-processor~.
-
-The "export" capability is slightly more involved as one need to
-select the processor providing it, but may also provide a default
-style for citations and bibliography.  Also, the choice of an export
-processor may depend of the current export back-end.  The association
-between export back-ends and triplets of parameters can be set in
-~org-cite-export-processors~ variable, or in a document, through the
-"cite_export" keyword.
-
-Eventually, this library provides some tools, mainly targeted at
-processor implementors.  Most are export-specific and are located in
-the "Tools only available during export" and "Tools generating or
-operating on parsed data" sections.
-
-This section of this manual will be enhanced with more practical
-information.  In the meantime, if you need help, please send an email
-to the mailing list at =emacs-orgmode@gnu.org=.
+more "bibliography" keywords.
+
+#+begin_example
+#+bibliography: SomeFile.bib
+#+bibliography: /some/other/file.json
+#+bibliography: "/some/file/with spaces/in its name.bib"
+#+end_example
+
+One can then insert and edit citations using ~org-cite-insert~, called
+with {{{kbd(M-x org-cite-insert)}}}.
+
+A /citation/ requires one or more citation /key(s)/, elements
+identifying a reference in the bibliography.
+
+- Each citation is surrounded by brackets and uses the =cite= type.
+
+- Each key starts with the character =@=.
+
+- Each key can be qualified by a /prefix/ (e.g. "see ") and/or a
+  /suffix/ (e.g. "p. 123"), giving informations useful or necessary fo
+  the comprehension of the citation but not included in the reference.
+
+- A single citation can cite more than one reference ; the keys are
+  separated by semicolons ; the formatting of such citation groups is
+  specified by the style.
+
+- One can also specify a stylistic variation for the citations by
+  inserting a =/= and a style name between the =cite= keyword and the
+  colon ; this usially makes sense only for the author-year styles.
+
+#+begin_example
+[cite/style:common prefix ;prefix @key suffix; ... ; common suffix]
+#+end_example
+
+The only mandatory elements are:
+
+- The =cite= keyword and the colon.
+- The =@= character immediately preceding each key.
+- The brackets surrounding the citation(s) (group).
+
+** Citation export processors
+
+Org currently includes the following export processors:
+
+- Two processors can export to a variety of formats, including =latex=
+  (and therefore =pdf=), =html=, =odt= and plain (UTF8) text:
+
+  - basic :: a basic export processors, well adapted to situations
+    where backward compatibility is not a requirement and formatting
+    needs are minimal;
+
+  - csl :: this export processor uses format files written in [[https://en.wikipedia.org/wiki/Citation_Style_Language][Citation
+    Style Language]] via [[https://github.com/andras-simonyi/citeproc-el][citeproc-el]];
+
+- In contrast, two other processors target LaTeX and LaTeX-derived
+  formats exclusively:
+
+  - natbib :: this export processor uses =bibtex=, the historical
+    bibliographic processor used with LaTeX, thus allowing the use of
+    data and style files compatible with this processor (including a
+    large number of publishers' styles).  It uses citation commands
+    implemented in the LaTeX package =natbib=, allowing more stylistic
+    variants that LaTeX's =\cite= command.
+
+  - biblatex :: this backend allows the use of data and formats
+    prepared for =biblatex=, an alternate bibliographic processor used
+    with LaTeX, which overcomes some serious =bibtex= limitations, but
+    has not (yet?) been widely adopted by publishers.
+
+The =#+cite_export:= keyword specifies the export processor and the
+citation (and possibly reference) style(s); for example (all arguments
+are optional)
+
+#+begin_example
+#+cite_export: basic author author-year
+#+end_example
+
+specifies the "basic" export processor with citations inserted as
+author's name and references indexed by author's names and year;
+
+#+begin_example
+#+cite_export: csl /some/path/to/vancouver-brackets.csl
+#+end_example
+
+specifies the "csl" processor and CSL style, which in this case
+defines numeric citations and numeric references according to the
+=Vancouver= specification (as style used in many medical journals),
+following a typesetting variation putting citations between brackets;
+
+#+begin_example
+#+cite_export: natbib kluwer
+#+end_example
+
+specifies the "natbib" export processor with a label citation style
+conformant to the Harvard style and the specification of the
+Wolkers-Kluwer publisher; since it relies on the =bibtex= processor of
+your LaTeX installation, it won't export to anything but PDF.
 
 * Working with Source Code
 :PROPERTIES: