From f4d5b9f7d2a57a588fd72c4074a6b1ed018cf29f Mon Sep 17 00:00:00 2001 From: Emmanuel Charpentier 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