Re: Citations, continued

[Richard Lawrence <richard.lawrence@berkeley.edu>]

Hi Rasmus and all,

Thanks for your comments!

Rasmus <rasmus@gmx.us> writes:

>> ** 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.

That sounds fine to me.  I think you may be using `inline' differently
than me, though: do you mean `author's name appears in the text (not in
parentheses)'?  (I was using it to talk about where the citation
definition appears in the document, not where the author's name appears
relative to parentheses.)

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

I agree it's a little clunky, but I think most of the time there would
just be one selector.  I was thinking of this on analogy with heading
properties and tags...is there a better existing syntax to refer to a
property value?

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

I don't like this, because it seems like a lot more work for me as a
user to achieve something that should be simple, and it trades 
specifying /what/ data I want for describing it more indirectly.

Suppose I'm writing a document, and I know I just want to reference the
journal and year of a particular publication, in that order.  Being a
studious keeper of my org-bibtex database, I already know that these
fields are called "journal" and "year".  But if, in addition to
reference database field names, I have to remember names for /types/ of
/combinations/ of field names, that's too much.  I'll end up taking
endless trips to the manual to figure out which type I need in this
case.  Do I need :type journal-before-year? :type journal-and-year?
etc.  This feels a bit too much like having to remember (or look up) all
the different LaTeX citation commands.

I expect that many of the common cases would have the same name, but
then I still have to remember which of my uses are `common'.  And
[@Doe99:year] is less verbose than [@Doe99 :type year].

What about just separating the field names off, as keys?  Like:

[See Doe's review @Doe99 :journal :year]

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

I guess I would suggest the same thing as happens in LaTeX: you get a
nice, bold "??" in the output where the missing data should be. 

>> *** 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].

Doesn't [-@Smith79] mean something different, namely, "cite @Smith79
without the author name"?  It produces output like: "(1979)".

The idea is that the :nocite selector produces no output, like LaTeX's
\nocite.  I don't know how important it is to have this, though.

>> *** 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.

Right, that's the point here...(were you disagreeing?)

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

Actually, this is a lot like the syntax I was thinking about for the
inline case, but in the end I thought it was too complicated and new to
be worth it, when the #+ATTR_BACKEND syntax will already work for the
out-of-line case.  I'm not opposed to something like this in principle,
but I really think we should try to keep the inline case very simple and
obvious to use, even if that means restricting its expressiveness a bit.

>> *** 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.

That's fine with me.

>> * 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.

I can't think of any reason why that wouldn't work.

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

OK.  I'd even be happy with

#+BIBLIOGRAPHY:
#+BIBLIGRAPHY_STYLE:
#+PRINT_BIBLIOGRAPHY:

where the first could be specified as many times as desired, to indicate
external reference databases.

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

Ah, OK, I didn't know about #+LANGUAGE.  Is there any reason why the
locale of the bibliography might be different than the locale of the
document?  (I'm monolingual, I'm afraid, so I doubt I could think of one
if there were...)

Best,
Richard