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

[Emmanuel Charpentier <emm.charpentier@free.fr>]

[-- 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