forked from mirrors/org-mode
doc/org-manual.org (Citations): Enhance
* doc/org-manual.org (Citations): Enhance. This is based on a preliminary draft provided by Emmanuel Charpentier.
This commit is contained in:
Bruce D'Arcus
Bastien
parent
20c3b0e436
commit
3b4ab1c3e4
|
|
@ -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".
|
||||
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:
|
||||
|
||||
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.
|
||||
- "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.
|
||||
|
||||
As a user, the first thing to do is setting a bibliography, either
|
||||
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~.
|
||||
more "bibliography" keywords.
|
||||
|
||||
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.
|
||||
#+begin_example
|
||||
#+bibliography: SomeFile.bib
|
||||
#+bibliography: /some/other/file.json
|
||||
#+bibliography: "/some/file/with spaces/in its name.bib"
|
||||
#+end_example
|
||||
|
||||
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.
|
||||
One can then insert and edit citations using ~org-cite-insert~, called
|
||||
with {{{kbd(M-x org-cite-insert)}}}.
|
||||
|
||||
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=.
|
||||
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue