Re: Citations, continued

[Rasmus <rasmus@gmx.us>]

Hi,

Richard Lawrence <richard.lawrence@berkeley.edu> writes:

> Here is the citation syntax proposal I have mentioned in a couple of
> posts now.

Thanks.  I think it's a good start, but I find it too far away from Org in
some respects.  Hence comments follow.

> ** Backend-agnostic formatting properties
> *** Selecting specific fields
> Selecting specific fields to display could be done by appending field
> names to cite keys after colons, much like Org tags:
> #+BEGIN_QUOTE
> [See @Doe99, pp. 34--45; also @Doe00:year, section 6] 
>
> [See their article in @Doe99:journal:year.] 
> #+END_QUOTE

First, I think we should use @key for inline and (@key) for parenthesis
expressions.  This give us two short keys.  [@Key ⋯] can be reserved for
complicated references.

I don't like "@Doe99:journal:year".  It's too unlike existing syntax.

Rather, I'd just introduce types as hinted previously, [@Doe99 :type
my-journal-year-type].  Org can provide as many predefined :type as we
care for, and let the user define the rest as necessary.

> Note that this would make for an extension of Pandoc syntax.  This
> extension is not a strict superset, since Pandoc allows internal `:'
> characters in cite keys, and thus would treat `@Doe99:journal:year' as
> a single key, rather than treating the key as ending at the first
> colon, with other data afterward.

Compatibility with pandoc is a non-issue IMO.  If that's necessary we can
use ox.

> When specific fields are requested, ONLY data from those fields should
> appear in the exported document.  Backends would choose how to export
> these citations based on the selected fields.

What happens when a field is undefined?

> *** Non-cited works that should appear in the bibliography
> A special field selector `:nocite' would be one way to achieve
> citations that, for whatever reason, should appear in the Org source
> and in the exported bibliography, but should not appear in the
> exported text where they are placed.  This would allow referencing
> them at relevant places in the document, like:
> #+BEGIN_QUOTE
> Smith said a lot of things, but no one can remember what they
> were. [@Smith79:nocite]
> #+END_QUOTE

I think R-markdown uses something like [-@Smith79].  Again, I don't like
the [@key:nocite].


> One drawback of this syntax is that it does not provide an easy way to
> list all the nocite references, since the user would have to add
> `:nocite' to each one individually.  This is not a huge problem for
> small numbers of refernces, but it would also be nice to have some
> equivalent of LaTeX's \nocite{*}.  On this point, see the proposal for
> non-inline citation definitions below.

#+NOCITE: key1 ⋯ keyN

> ** Non-inline citation definitions and backend-specific formatting
> [...]
> #+BEGIN_QUOTE
>     Doe provides an interesting analysis. [cite:1]
>     ...
>     * Citations
>     [cite:1] See @Doe99, pp. 34--45; also @Doe2000:year, ch. 1.
> #+END_QUOTE

This is cool.  I'd use it in some cases.

> That is, a citation /pointer/ would occur inline in the document text,
> which refers (via a number or a label) to a citation /definition/ in a
> specially-named subtree.

It would refer to it anywhere.  No reason to make it different from
footnotes.

> *** Backend-specific formatting
> In general, it would be nice to avoid formatting properties which are
> specific to a particular export backend when a backend-agnostic
> solution is available, but some backend-specific formatting needs are
> probably inevitable, so we need a syntax for specifying them.
>
> Another advantage of the non-inline citation syntax is that it would
> allow using the existing #+ATTR_BACKEND syntax to specify
> backend-specific formatting properties, since the citation definitions
> would be block-level elements:
> #+BEGIN_QUOTE
>     * Citations
>
>     #+ATTR_LATEX: :command citet
>     #+ATTR_HTML: :class my-citation
>     [cite:1] See @Doe99, pp. 34--45; @Foobar2000, ch.1.
> #+END_QUOTE

Why not.  Since footnote-definition is a greater element it /does/ take
affiliated keywords, but I have never seen this used.

For inline maybe something like this:
    [@Key :type_html my-citation :type_latex citet] 


> *** Bibliography-only entries
> Non-inline definitions would also provide a convenient place to list
> non-cited references that should appear in the bibliography.  For
> example:
> #+BEGIN_QUOTE
>     * Citations
>     ...
>     [nocite:] @Doe99; @Foobar2000; @Baz98.
> #+END_QUOTE

As stated above, I find #+NOCITE more in line with current syntax.

> * Document metadata
> In addition to the syntax of citations themselves, the Org document
> would also need to represent the following metadata to support
> citations:
> 7. [@7] a pointer to one or more backend reference databases,
>    including in-document databases in org-bibtex format

If org-bibtex entries are present they should just take precedence.  That
way you can easily insert new entries and customize them for your project
and have a portable document.

> 8. a reference to a citation style or style file

> 9. a reference to a locale file

#+BIBLIOGRAPHY_FILES: file1 file2

> 10. an indication of where the bibliography should be found in the
>     exported document (equivalent to \printbibliography, etc. in
>     LaTeX)

From experience, the biblatex model of separating the loading of files,
styles and printing into different commands is a great advantage.

> ** #+BIBLIOGRAPHY: reference database, style, locale

I think more keywords are better.

> The point of specifying the style and locale as part of
> the #+BIBLIOGRAPHY definition is for compatibility with both LaTeX and
> Citation Style Language bibliography and citation formatting.

Local is defined by #+LANGUAGE.  AFAIK, Org doesn't support many
languages.  E.g. here's the definition of LANGUAGE in ox.el:

(:language "LANGUAGE" nil org-export-default-language t)

> In keeping with other metadata keyword lines (like #+OPTIONS), I
> suggest a key:value syntax for the arguments to #+BIBLIOGRAPHY, like
> so:
> #+BEGIN_QUOTE
> #+BIBLIOGRAPHY: db:/path/to/some/file.bib style:chicago

The db is redundant.  E.g. #+INCLUDE automatically knows that the first
word is the file in question.

There may be many bib files, so there should be a #+BIBLIOGRAPHY_FILES.

I prefer :style chicago to be consistent with #+INCLUDE.

> #+BIBLIOGRAPHY: db:/path/to/some/file.bib style:plain locale:en_GB

Locale is "dangerous" as it can get out of sync with LANGUAGE.

> #+BIBLIOGRAPHY: db:"*Reference DB"

If the citation-key is defined in document use it.  Otherwise check
BIBLIOGRAPHY_FILES.

> In the last example, the leading "*" is meant to indicate that the
> reference database is a subtree with headline "Reference DB", whose
> branches are in org-bibtex format.

Too much micromanagement.  I prefer how footnote-definition works. 


> ** Bibliography placement
> The simplest solution seems to be just allowing the #+BIBLIOGRAPHY
> keyword to appear anywhere in the document, to be replaced on export
> with the formatted bibliography.  I think this is what ox-bibtex now
> does.  

#+TOC works the same way.

—Rasmus

-- 
C is for Cookie