From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rasmus Subject: Re: Citations, continued Date: Mon, 02 Feb 2015 20:55:11 +0100 Message-ID: <87iofkdr6o.fsf@pank.eu> References: <87vbjmn6wy.fsf@berkeley.edu> <87sieokx8e.fsf@berkeley.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:57658) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YIN5e-00066A-Uc for emacs-orgmode@gnu.org; Mon, 02 Feb 2015 14:55:28 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YIN5b-00038l-87 for emacs-orgmode@gnu.org; Mon, 02 Feb 2015 14:55:22 -0500 Received: from plane.gmane.org ([80.91.229.3]:46687) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YIN5a-000388-UD for emacs-orgmode@gnu.org; Mon, 02 Feb 2015 14:55:19 -0500 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1YIN5Y-0008Nj-MP for emacs-orgmode@gnu.org; Mon, 02 Feb 2015 20:55:16 +0100 Received: from 46-253-188-95.dynamic.monzoon.net ([46.253.188.95]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 02 Feb 2015 20:55:16 +0100 Received: from rasmus by 46-253-188-95.dynamic.monzoon.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Mon, 02 Feb 2015 20:55:16 +0100 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Hi, Richard Lawrence 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