Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]

Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]

[Emmanuel Charpentier]

[-- Attachment #1.1: Type: text/plain, Size: 2040 bytes --]

As reported by Bastien, I started a documentation for the current state
of the citation engine(s). I intended to complete it, but got "a
little" sidetracked.

Enclosed is a patch of where I was in August.

Bastien made the following remarks, which I mostly intended to follow :

===========================================

Je pense qu'à ce stade, le mieux est de soumettre ce document sur la
liste de diffusion.

En attendant, j'ai quelques remarques, en vrac :

- Je pense que le titre "Working with…" n'est pas assez explicite. Par
  ailleurs, le chapitre précédent commence aussi par "Working with…".
  Par conséquent, je propose d'intervertir la description et le titre :

    * Citations and references
    :PROPERTIES:
    :DESCRIPTION: Working with other people's work
    :END:

- Il faut penser à mettre deux espaces entre deux phrases.

- =Org= -> Org

- J'enlèverais la partie introductive expliquant pourquoi il est utile
  de citer le travail d'autrui. Ceci dit, il vaut mieux attendre l'avis
  d'autres personnes concernées par la fonctionnalité.

[ Emmanuel Charpentier : I think that this justification may be helpful
to a lot of non-scholar org users, who could benefit from org-cite.
Advice sollicited... ]

- Je pense qu'il faut éviter de parler ce "citation link", car cela
peut
  engendrer de la confusion avec "link" qui est une structure proche,
  mais différent. Peut-être faut-il parler de "citation object".

- Dans Texinfo, les phrases doivent être séparées par deux espaces.

===========================================

What still lacks :
 * an explanation of the four possible functions of an engine ;
 * current functionalities of the currently available engines ;
 * an org-guide sized summary.

Anyone is welcome to propose modifications. Someone should take the
task of collating the propositions and consolidate a final text ; I am
reluctant to take this task, given my RL tasks...

Comments, remarks, criticisms, lazzi, etc... all welcome.

--
Emmanuel Charpentier

[-- Attachment #1.2: Type: text/html, Size: 7414 bytes --]

[-- Attachment #2: 0001-Embryo-of-a-doc-for-the-citation-engine-s.patch --]
[-- Type: text/x-patch, Size: 11524 bytes --]

From f4d5b9f7d2a57a588fd72c4074a6b1ed018cf29f Mon Sep 17 00:00:00 2001
From: Emmanuel Charpentier <emm.charpentier@free.fr>
Date: Mon, 27 Sep 2021 15:46:51 +0200
Subject: [PATCH] Embryo of a doc for the citation engine(s).

---
 doc/org-manual.org | 239 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 239 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index d34d33561..265d5f33a 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18622,6 +18622,245 @@ emacs -Q --batch --eval "
   " "$@"
 #+end_example
 
+* Working with other people's work
+:PROPERTIES:
+:DESCRIPTION:  Manage citations and references
+:END:
+#+cindex: other people's work, working with
+
+Citations and references are a crucial part of almost any writing
+(scholarly or otherwise): citing previous works relieves you from the
+burden of discussing or defending what you cite. This relief comes at
+a price: referring your reader to your source (thus transferring the
+burden to check your statements in the original source to
+him/her). This is usually done by separing a brief indication of the
+work you use (a /citation/), part of the text, from the detailed
+description of this work and of the means to retrieve it (the
+/reference/), given out of the text (in footnotes and/or at the end of
+the text).
+
+In everyday writing, citations and references may be vague, often
+reduced to a handwave. In many domains, however, and most notably in
+academic writing, precision in citing and referring is crucial. Citing
+and referring conventions have therefore evolved since the beginnings
+of writing, and are highly formalized in many domains.
+
+These conventions, answering different needs in different domains, are
+different from domain to domain. For various reasons, they also vary
+according to the intended use of the writing (academic work,
+scientific paper, report, journal article, book or book chapter,
+etc...).  Following these sets of conventions (aka /styles/) can be
+highly labor intensive.
+
+=Org= bibliographic tools use sets of reference informations and
+formatting directives to easily insert succinct indications of a work
+and forat theminto style-compliant citation and reference and insert
+them in the correct place in the text.
+
+** Overview
+:PROPERTIES:
+:DESCRIPTION: Basic concepts of citation handling
+:END:
+#+cindex: bibliography
+#+cindex: citation
+#+cindex: reference
+#+cindex: style
+
+A few definitions are in order :
+
+  * Bibliography :: Conceptually, it is the set of /all/ previous
+    works supporting one's work, /whether you cite them explicitly or
+    not/. It might also denote a list of all such work, possibly with
+    notes related to each of them.
+
+    This word also denotes a bibliography list referring /all/ the
+    works (cited or not) used in the development of one's work ; this
+    is a requirement of some (mostly scholarly) styles.
+
+  * Reference :: The information the information pertaining to a given
+    work, necessary an sufficient to retrieve it, formatted according
+    to some fixed set of conventions.
+
+  * Citation :: The act of referring concisely the reader to a given
+    work, possibly adapted to the citing context (grammatical,
+    syntactic and stylistic constraints).
+
+  * Style :: The set of conventions used to format a citation or a
+    reference, allowing for brevity, ease of reading and ease of use
+    in a given context.
+
+  * References list :: a list of all works /explicitly cited/ in
+    the text, formatted according to a given style.
+
+    In some styles using footnotes to carry references, the references
+    list is optional or absent.
+
+From =Org= point of view, the central element is the /citation/, which
+is done by inserting a /citation link/ at the place of your text you
+want to see this citation appear. =Org= will manage the generation of
+citation(s) and the insertion of the corresponding reference in a
+footnote or reference list. The specification of the bibliography, the citation and reference styles and the position of an eventual reference list is supporting information.
+
+This /modus operandi/ is, not coincidentally, close to what is used in
+previous text processing systems such as LaTeX or =markdown=
+extensions such as =pandoc=. This compatibility is enhanced by the use of several /backends/, adapted to the re-use of various data and format files.
+
+** Bibliography
+:PROPERTIES:
+:DESCRIPTION: Bibliographical sources specifications
+:END:
+
+The *bibliography* is a (set of) file(s) specified:
+  * by setting the =org-cite-global-bibliography= variable, and/or
+  * by one or more uses of the keyword =#+bibliography:= :
+
+#+begin_example
+#+bibliography: SomeFile.bib
+#+bibliography: /some/other/file.json
+#+bibliography: "/some/file/with spaces/in its name.bib"
+#+end_example
+
+ =Org= can treat several bibliographic file formats:
+  * =bib= :: the file format used by =bibtex= and =biber=, the bibliography compilers used in conjunction with LaTeX, also used by several text processor such as =pandoc= ;
+  * =json= :: a javascript-compatible wrapping of an XML encoding of bibliographic data.
+
+** Styles, bibliograhic backends
+
+There are many sets of conventions used to denote a citation in a text
+(the /citation style/), as well as to format the corresponding
+reference (the /reference style/). Here are some examples :
+  * Numeric :: citations are numbered (usually by their order of
+    appearance _n the text, and that number (usually typeset in a
+    fashion distinguishing it from the surrounding text) denotes the
+    citation.
+  * Label :: the names(s) of the author(s) (and possibly the year of
+    publication) are used to derive a unique label denoting the
+    citation.
+  * Author-year :: a citation is denoted by the (last) name of the
+    (first) author and the year of publication, typeset with
+    separators distinguisthing the citation from the surrounding text
+    (usually parentheses or brackets).
+
+    The latter citation style may be subject to stylistic variations
+    according to its place in the text. For example, the name of the
+    author may be used textually, and the citation is reduced to the
+    publication date.
+
+Similarly, the references, related to the text by a common citation,
+can be placed in footnotes and/or grouped in one or several /reference
+list(s)/.
+
+There also exist numerous sets of conventions for the formatting of
+references (the /reference style/), specifying the typesetting and
+punctuation of the parts of the reference, according to the nature of
+the work referenced convetions are different for, say, books, journal
+articles and films because the ways these documents are stored and
+retrieved are different).
+
+The citation and reference styles have to be consistent. For example :
+
+  * a numeric citation style implies the presence of a numeric
+    reference in the references list and (usually) sorting the latter
+    in (first) citation order ;
+
+  * a label citation style implies the appearance of the same label in
+    the reference list (and, usually, using this label to sort the
+    reference list) ;
+
+  * an author-year citation style implies sorting the reference list
+    (if any) in the same fashion.
+
+The available styles depend on the specific engine (the
+bibibliographic /backend/ used to format the references and
+bibliographies).
+
+At the time of this writing, four bibliograhic backends are available :
+
+  * Two backends can export to a variety of formats, including =latex=
+    (therefore =pdf=), =html=, =odt= and plain (UTF8) text :
+
+    - basic :: a basic backend, well adapted to situations where
+      backward compatibility is not a requirement and formatting needs
+      are minimal ;
+
+    - csl :: this backend uses format files written in [[https://en.wikipedia.org/wiki/Citation_Style_Language][Citation Style
+      Language]], an XML-based bibliographic style description format,
+      used in various word processors such as Word and LibreOffice,
+      and has been widely adopted by publishers, which publish their
+      preferred formats along with their "Instructions to Authors".
+
+  * In contrast, two other use LaTeX bibliographic tools installed on
+    your computer (thus providing results identical to those obtained
+    by these tools in a LaTeX document), but export only to LaTeX and
+    LaTeX-derived formats :
+
+    - natbib :: this backend 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 the
+      citing 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 backend and the citation (and possibly reference) style(s) are specified by the =#+cite_export:= keyword (all arguments are optional) ; for example : 
+
+#+begin_example
+#+cite_export: basic author author-year
+#+end_example
+
+specifies management by the basic backend 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 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 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.
+
+** Citations
+
+A /citation link/ is built around one or more citation /key(s)/, elements identifying a reference in the bibliography.
+
+  * Each citation link is surrounded by brackets and uses the =cite= type.
+
+  * Each keys starts with the character =@= (a convention inherited
+    from =bibtex=).
+
+  * 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)
+
+/Possibly give examples of the prefixes, suffixes and stylistic variations.../
+
 * Miscellaneous
 :PROPERTIES:
 :DESCRIPTION: All the rest which did not fit elsewhere.
-- 
2.33.0

Re: Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]

[Bruce D'Arcus]

Great start!

A few quick comments:

1. I'm not sure we should call them "citation links", since they
aren't really links.

2. "four bibliograhic backends are available": a) note typo (which I
think I saw elsewhere; there are a number of spelling errors
throughout), b) "available" -> "included" (in org)

More generally, it has also occurred to me that some of what Timothy
wrote for this might be repurposed for here:

https://blog.tecosaur.com/tmio/2021-07-31-citations.html

Finally, a question: what's the best way to do complex-ish
documentation like this collaboratively? Is there an alternative to
email + patches for the create, comment, revise cycle of refining
this?

And related: if the goal is to finish this week (?), do we have time
to do comprehensive documentation? I'm a little skeptical.


On Mon, Sep 27, 2021 at 10:04 AM Emmanuel Charpentier
<emm.charpentier@free.fr> wrote:
>
> As reported by Bastien, I started a documentation for the current state of the citation engine(s). I intended to complete it, but got "a little" sidetracked.
>
> Enclosed is a patch of where I was in August.
>
> Bastien made the following remarks, which I mostly intended to follow :
>
> ===========================================
>
> Je pense qu'à ce stade, le mieux est de soumettre ce document sur la
> liste de diffusion.
>
> En attendant, j'ai quelques remarques, en vrac :
>
> - Je pense que le titre "Working with…" n'est pas assez explicite. Par
>   ailleurs, le chapitre précédent commence aussi par "Working with…".
>   Par conséquent, je propose d'intervertir la description et le titre :
>
>     * Citations and references
>     :PROPERTIES:
>     :DESCRIPTION: Working with other people's work
>     :END:
>
> - Il faut penser à mettre deux espaces entre deux phrases.
>
> - =Org= -> Org
>
> - J'enlèverais la partie introductive expliquant pourquoi il est utile
>   de citer le travail d'autrui. Ceci dit, il vaut mieux attendre l'avis
>   d'autres personnes concernées par la fonctionnalité.
>
> [ Emmanuel Charpentier : I think that this justification may be helpful to a lot of non-scholar org users, who could benefit from org-cite. Advice sollicited... ]
>
> - Je pense qu'il faut éviter de parler ce "citation link", car cela peut
>   engendrer de la confusion avec "link" qui est une structure proche,
>   mais différent. Peut-être faut-il parler de "citation object".
>
> - Dans Texinfo, les phrases doivent être séparées par deux espaces.
>
> ===========================================
>
> What still lacks :
>
> an explanation of the four possible functions of an engine ;
> current functionalities of the currently available engines ;
> an org-guide sized summary.
>
>
> Anyone is welcome to propose modifications. Someone should take the task of collating the propositions and consolidate a final text ; I am reluctant to take this task, given my RL tasks...
>
> Comments, remarks, criticisms, lazzi, etc... all welcome.
>
> --
> Emmanuel Charpentier

Re: Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]

[Bastien Guerry]

Hi Bruce and Emmanuel,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> Finally, a question: what's the best way to do complex-ish
> documentation like this collaboratively? Is there an alternative to
> email + patches for the create, comment, revise cycle of refining
> this?

I'm sending you (and Timothy and Nicolas) a link off-list.

> And related: if the goal is to finish this week (?), do we have time
> to do comprehensive documentation? I'm a little skeptical.

The goal is to have something by tomorrow afternoon, of course it does
not need to be "finished" in any sense, it just needs to be better
than what is already committed.

*Thanks*!

-- 
 Bastien

Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]

[CHARPENTIER Emmanuel via General discussions about Org-mode.]

[-- Attachment #1.1: Type: text/plain, Size: 2082 bytes --]

As reported by Bastien, I started a documentation for the current state of the citation engine(s). I intended to complete it, but got "a little" sidetracked.

Enclosed is a patch of where I was in August.

Bastien made the following remarks, which I mostly intended to follow :

===========================================

Je pense qu'à ce stade, le mieux est de soumettre ce document sur la
liste de diffusion.

En attendant, j'ai quelques remarques, en vrac :

- Je pense que le titre "Working with…" n'est pas assez explicite. Par
  ailleurs, le chapitre précédent commence aussi par "Working with…".
  Par conséquent, je propose d'intervertir la description et le titre :

    * Citations and references
    :PROPERTIES:
    :DESCRIPTION: Working with other people's work
    :END:

- Il faut penser à mettre deux espaces entre deux phrases.

- =Org= -> Org

- J'enlèverais la partie introductive expliquant pourquoi il est utile
  de citer le travail d'autrui. Ceci dit, il vaut mieux attendre l'avis
  d'autres personnes concernées par la fonctionnalité.

[ Emmanuel Charpentier : I think that this justification may be helpful to a lot of non-scholar org users, who could benefit from org-cite. Advice sollicited... ]

- Je pense qu'il faut éviter de parler ce "citation link", car cela peut
  engendrer de la confusion avec "link" qui est une structure proche,
  mais différent. Peut-être faut-il parler de "citation object".

- Dans Texinfo, les phrases doivent être séparées par deux espaces.

===========================================

What still lacks :

  *   an explanation of the four possible functions of an engine ;
  *   current functionalities of the currently available engines ;
  *   an org-guide sized summary.

Anyone is welcome to propose modifications. Someone should take the task of collating the propositions and consolidate a final text ; I am reluctant to take this task, given my RL tasks...

Comments, remarks, criticisms, lazzi, etc... all welcome.

--
Emmanuel Charpentier

[-- Attachment #1.2: Type: text/html, Size: 7678 bytes --]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Embryo-of-a-doc-for-the-citation-engine-s.patch --]
[-- Type: text/x-patch; name="0001-Embryo-of-a-doc-for-the-citation-engine-s.patch", Size: 11524 bytes --]

From f4d5b9f7d2a57a588fd72c4074a6b1ed018cf29f Mon Sep 17 00:00:00 2001
From: Emmanuel Charpentier <emm.charpentier@free.fr>
Date: Mon, 27 Sep 2021 15:46:51 +0200
Subject: [PATCH] Embryo of a doc for the citation engine(s).

---
 doc/org-manual.org | 239 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 239 insertions(+)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index d34d33561..265d5f33a 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18622,6 +18622,245 @@ emacs -Q --batch --eval "
   " "$@"
 #+end_example
 
+* Working with other people's work
+:PROPERTIES:
+:DESCRIPTION:  Manage citations and references
+:END:
+#+cindex: other people's work, working with
+
+Citations and references are a crucial part of almost any writing
+(scholarly or otherwise): citing previous works relieves you from the
+burden of discussing or defending what you cite. This relief comes at
+a price: referring your reader to your source (thus transferring the
+burden to check your statements in the original source to
+him/her). This is usually done by separing a brief indication of the
+work you use (a /citation/), part of the text, from the detailed
+description of this work and of the means to retrieve it (the
+/reference/), given out of the text (in footnotes and/or at the end of
+the text).
+
+In everyday writing, citations and references may be vague, often
+reduced to a handwave. In many domains, however, and most notably in
+academic writing, precision in citing and referring is crucial. Citing
+and referring conventions have therefore evolved since the beginnings
+of writing, and are highly formalized in many domains.
+
+These conventions, answering different needs in different domains, are
+different from domain to domain. For various reasons, they also vary
+according to the intended use of the writing (academic work,
+scientific paper, report, journal article, book or book chapter,
+etc...).  Following these sets of conventions (aka /styles/) can be
+highly labor intensive.
+
+=Org= bibliographic tools use sets of reference informations and
+formatting directives to easily insert succinct indications of a work
+and forat theminto style-compliant citation and reference and insert
+them in the correct place in the text.
+
+** Overview
+:PROPERTIES:
+:DESCRIPTION: Basic concepts of citation handling
+:END:
+#+cindex: bibliography
+#+cindex: citation
+#+cindex: reference
+#+cindex: style
+
+A few definitions are in order :
+
+  * Bibliography :: Conceptually, it is the set of /all/ previous
+    works supporting one's work, /whether you cite them explicitly or
+    not/. It might also denote a list of all such work, possibly with
+    notes related to each of them.
+
+    This word also denotes a bibliography list referring /all/ the
+    works (cited or not) used in the development of one's work ; this
+    is a requirement of some (mostly scholarly) styles.
+
+  * Reference :: The information the information pertaining to a given
+    work, necessary an sufficient to retrieve it, formatted according
+    to some fixed set of conventions.
+
+  * Citation :: The act of referring concisely the reader to a given
+    work, possibly adapted to the citing context (grammatical,
+    syntactic and stylistic constraints).
+
+  * Style :: The set of conventions used to format a citation or a
+    reference, allowing for brevity, ease of reading and ease of use
+    in a given context.
+
+  * References list :: a list of all works /explicitly cited/ in
+    the text, formatted according to a given style.
+
+    In some styles using footnotes to carry references, the references
+    list is optional or absent.
+
+From =Org= point of view, the central element is the /citation/, which
+is done by inserting a /citation link/ at the place of your text you
+want to see this citation appear. =Org= will manage the generation of
+citation(s) and the insertion of the corresponding reference in a
+footnote or reference list. The specification of the bibliography, the citation and reference styles and the position of an eventual reference list is supporting information.
+
+This /modus operandi/ is, not coincidentally, close to what is used in
+previous text processing systems such as LaTeX or =markdown=
+extensions such as =pandoc=. This compatibility is enhanced by the use of several /backends/, adapted to the re-use of various data and format files.
+
+** Bibliography
+:PROPERTIES:
+:DESCRIPTION: Bibliographical sources specifications
+:END:
+
+The *bibliography* is a (set of) file(s) specified:
+  * by setting the =org-cite-global-bibliography= variable, and/or
+  * by one or more uses of the keyword =#+bibliography:= :
+
+#+begin_example
+#+bibliography: SomeFile.bib
+#+bibliography: /some/other/file.json
+#+bibliography: "/some/file/with spaces/in its name.bib"
+#+end_example
+
+ =Org= can treat several bibliographic file formats:
+  * =bib= :: the file format used by =bibtex= and =biber=, the bibliography compilers used in conjunction with LaTeX, also used by several text processor such as =pandoc= ;
+  * =json= :: a javascript-compatible wrapping of an XML encoding of bibliographic data.
+
+** Styles, bibliograhic backends
+
+There are many sets of conventions used to denote a citation in a text
+(the /citation style/), as well as to format the corresponding
+reference (the /reference style/). Here are some examples :
+  * Numeric :: citations are numbered (usually by their order of
+    appearance _n the text, and that number (usually typeset in a
+    fashion distinguishing it from the surrounding text) denotes the
+    citation.
+  * Label :: the names(s) of the author(s) (and possibly the year of
+    publication) are used to derive a unique label denoting the
+    citation.
+  * Author-year :: a citation is denoted by the (last) name of the
+    (first) author and the year of publication, typeset with
+    separators distinguisthing the citation from the surrounding text
+    (usually parentheses or brackets).
+
+    The latter citation style may be subject to stylistic variations
+    according to its place in the text. For example, the name of the
+    author may be used textually, and the citation is reduced to the
+    publication date.
+
+Similarly, the references, related to the text by a common citation,
+can be placed in footnotes and/or grouped in one or several /reference
+list(s)/.
+
+There also exist numerous sets of conventions for the formatting of
+references (the /reference style/), specifying the typesetting and
+punctuation of the parts of the reference, according to the nature of
+the work referenced convetions are different for, say, books, journal
+articles and films because the ways these documents are stored and
+retrieved are different).
+
+The citation and reference styles have to be consistent. For example :
+
+  * a numeric citation style implies the presence of a numeric
+    reference in the references list and (usually) sorting the latter
+    in (first) citation order ;
+
+  * a label citation style implies the appearance of the same label in
+    the reference list (and, usually, using this label to sort the
+    reference list) ;
+
+  * an author-year citation style implies sorting the reference list
+    (if any) in the same fashion.
+
+The available styles depend on the specific engine (the
+bibibliographic /backend/ used to format the references and
+bibliographies).
+
+At the time of this writing, four bibliograhic backends are available :
+
+  * Two backends can export to a variety of formats, including =latex=
+    (therefore =pdf=), =html=, =odt= and plain (UTF8) text :
+
+    - basic :: a basic backend, well adapted to situations where
+      backward compatibility is not a requirement and formatting needs
+      are minimal ;
+
+    - csl :: this backend uses format files written in [[https://en.wikipedia.org/wiki/Citation_Style_Language][Citation Style
+      Language]], an XML-based bibliographic style description format,
+      used in various word processors such as Word and LibreOffice,
+      and has been widely adopted by publishers, which publish their
+      preferred formats along with their "Instructions to Authors".
+
+  * In contrast, two other use LaTeX bibliographic tools installed on
+    your computer (thus providing results identical to those obtained
+    by these tools in a LaTeX document), but export only to LaTeX and
+    LaTeX-derived formats :
+
+    - natbib :: this backend 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 the
+      citing 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 backend and the citation (and possibly reference) style(s) are specified by the =#+cite_export:= keyword (all arguments are optional) ; for example : 
+
+#+begin_example
+#+cite_export: basic author author-year
+#+end_example
+
+specifies management by the basic backend 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 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 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.
+
+** Citations
+
+A /citation link/ is built around one or more citation /key(s)/, elements identifying a reference in the bibliography.
+
+  * Each citation link is surrounded by brackets and uses the =cite= type.
+
+  * Each keys starts with the character =@= (a convention inherited
+    from =bibtex=).
+
+  * 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)
+
+/Possibly give examples of the prefixes, suffixes and stylistic variations.../
+
 * Miscellaneous
 :PROPERTIES:
 :DESCRIPTION: All the rest which did not fit elsewhere.
-- 
2.33.0