Re: Let's discuss citation and Org syntax

[Rasmus <rasmus@gmx.us>]

A lot of people more clever than me have thought about this topic.
Here I'll just summarize the "org-exp-bibtex missing in
git?"-thread.  The ordering more or less follows how it was
displayed in my Gnus.  I've tried to "stay honest" to the people
I've quoted and hopefully I've not failed too badly.  Also, I hope
I've not forgotten valuable suggestions.  I've not quoted Thomas,
but he gave some insights of what one would want in citation here
http://mid.gmane.org/m1a9qczekf.fsf%40tsdye.com.
   

There were approximately three types of suggestions:
1. the new-type approach, which I've tried to generalize more
   above.  Aaron made valueable suggestions here.  Nicolas gave it
   some support.
2. The extending link approach, notably Bastien, Andreas and Aaron
   even supplied patches!
I've also included some quick references to the "current frontier"
using links.  Lastly, there's some links to implementation in other
formats.

The "new-type" approach
   - Nicolas: 
     #+BEGIN_QUOTE
     It would be good to integrate citations in export framework
     [...]
     Maybe something like [cite:....]. org-element could parse this, and
     ox.el provide some tools to access data. Then each back-end could deal
     with them.
     [...]
     I favor [cite:PROPERTIES] over [[cite:PROPERTIES]], because the latter
     (link syntax) implies a (optional) description part. I don't think
     a description is ever meaningful in citations.
     #+END_QUOTE
     Ref: http://mid.gmane.org/87ehfwwgdd.fsf%40gmail.com and
     http://mid.gmane.org/874ngkzjt6.fsf%40gmail.com

   - Much of my discussion in the previoues post is similar to Aaron's
     response to my original post
     #+BEGIN_QUOTE
     So, a citation like [cite:doi:parens:some-doi:key=val&key2=val2] would be
     displayed by:
     1. call (org-lookup-cite-doi "some-doi") -> (:author "Foo" :title "bar" ...)
     2. call (org-display-cite-parens '(:author "Foo" :title "bar" ...)) ->
     "(Foo 2000)"
     3. (font-lock puts an overlay over the citation markup, with the
     returned string)
   
     If you click on the citation, org would open the location (URL or local
     file) returned by (org-resolve-cite-doi "some-doi")
   
     A citation could exported by calling (org-export-cite-parens 'doi
     "some-doi" (:author "foo" :title "bar") current-backend).  This function
     could just return \parencite{foo} if exporting to latex and the citation
     was already in a bibtex file.  But it could also just return “Foo 2000”
     as a static string for dumb backends like ASCII, or write the
     information to a temporary bibtex file (so that latex can atomatically
     use the bibliographic info looked up from a DOI citation).
     #+END_QUOTE
     Ref: http://mid.gmane.org/87txolk7qk.fsf%40gmail.com


    - Jamuthan's take on viewing citation as footnotes
     #+BEGIN_QUOTE
     I view Citations as closer to Footnotes.  The syntax should parallels
     footnotes syntax.
     
     1. PROPERTIES should be opaque to Org.  It is a key or a list of
        keys possibly bibtex but Org doesn't take stand on how it
        looks like.
   
     2. There will be a org-BACKEND-citation-reference.
     3. There will be a org-BACKEND-bibliography.
   
     2, 3 more likely with interface with respective citation processor
     (citation processor as opposed to a database) via CLI.  Citation
     processor could be whatever org-exp-bibtex interfaces with right now.  I
     also have some proof-of-concept - see zotcite - for zotero.
   
     2, 3 will parallel footnote-reference and footnote-section callbacks in
     HTML backend.
   
     4. Footnotes can be introduced with either fn: prefix or cite:
        prefix.  There should be a way to put fn: and cite: in same
        enumeration context.  There should be a way to put fn: and
        cite: in different enumeration context.  The former case could
        be a degenerate mode where Org can transcode what is seen in
        the buffer where everything is footnotes.  The latter case
        will result in Citations and Bibliography being generated by
        the above backend transcoders.
       
     5. Citation definitions in Org buffer will be *ignored*.  (It
        could be considered when the exporter works in a degenerate
        footnote only mode where plain text transcoding is resorted to
        because there is no suitable application available for the
        backend format.)  Plain text citation definitions are only to
        help the author have a glimpse of what he is doing, it has
        only UI-value but no contents value.
   
     6. There may be an advisory citation style - say APA, Chicago
        etc - which the backends may honor or ignore.
      #+END_QUOTE


The "extend-link" suggestions:

   - Andreas Leha suggest something like what I suggested above, but
     extending upon the link syntax.  What I agree strongly with is:

       citations are more than links but also include information on
       formatting
     
     I.e. (in my words): cite alone doesn't cut it. 

     Here's Eric/Andreas' suggestion for a syntax:
     #+BEGIN_QUOTE
       \footfullcite[prenote][postnote]{key}
       
       Eric suggested/uses this format (thanks for sharing, Eric):
         [[cite:jones-etal-2000][Jones et al., 2000]]
                ^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^
                    key           displayed in org
       
       So, a possible extension of that could, for instance,
       use a third pair of [] as in
         [[cite:jones-etal-2000][Jones et al., 2000][[citationcommand][prenote][postnote]]]
                ^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^
                key           displayed in org
     #+END_QUOTE
     
     Reference:  http://mid.gmane.org/87ppzcfy2e.fsf%40med.uni-goettingen.de
   - Bastien suggests leveraging on links 
     #+BEGIN_QUOTE
       1. Allow more syntax for #+LINK:
       
          ,#+LINK: bib;%s;%s file:my.bib::%s org-bib-follow-link org-bib-export-link
       
       If `org-bib-follow-link' is nil, it'll follow [[bib:my.bib::key][key]]
       like it does right now, jumping to the "key" line in the my.bib file.
       
       If `org-bib-follow-link' is non-nil, it will operate on
       [[bib:my.bib::key;prenote;postnote][key]] and find the correct key.
       
       If `org-bib-export-link' is non-nil, it will operate on
       [[bib:my.bib::key;prenote;postnote][key]] and export it correctly
       depending on the backend.
       
       [...]
       
       I see two advantages:
       
       - adding new types will be easier -- e.g.:
         ,#+LINK: cite file:my.bib::%s org-bib-follow-link org-bib-export-link
       
       - users can decide what syntactic glue they want to their abbreviated
         links (using ";" or another separator).
       
       [...]
       
       See for example this new link type (or "protocol"):
       
       ,#+LINK: with-title::%s http://orgmode.org/worg/doc.html# nil org-html-link-with-title
       
         [[with-title::org-mode::A link title][org-mode]]
       
       org-html-link-with-title would then take care of exporting this
       as a link like <a href="..." title="A link title">org-mode</a>.
       
       There are really two changes here:
       
       1. extending #+LINK so that the third and fourth strings are
          recognized as follow and export functions
       
       2. extending #+LINK so that a formatting string in the link
          abbreviation name is handle later on by those functions.

     [...]	  
     In general, the idea is just to be able to hook an export
     function to a link after it has been expanded, and maybe 
     this can be useful beyond this use-case.  For example:

     #+LINK: local file://%s org-odt-local-link
     #+LINK: local file://%s org-odt-global-link
     #+END_QUOTE
     this suggestion is from
     http://mid.gmane.org/87wqtjo6h6.fsf%40bzg.ath.cx and extends upon
     http://mid.gmane.org/87lia0s7wi.fsf%40bzg.ath.cx.  Also
     http://mid.gmane.org/876213laso.fsf%40bzg.ath.cx. And finally
     http://mid.gmane.org/871ubrr4ou.fsf%40bzg.ath.cx.

   - Aaron supplied patches as mention in the post above, and
     suggests the syntax
     #+BEGIN_SRC org
       [[type:key;pre;post][desc]]
       or
       [[type:address;key1=value1,key2=value2][description]]
     #+END_SRC
     His patches are just for citation and only for LaTeX but they
     are there right now(!).  They are quite substational posts and
     I didn't find a good way to quote it here.  In addition to the
     two links in the post above also check out
     http://mid.gmane.org/CAFcZrT2mG0tFZRTrx5tKhm2SURHte-fCnDa+PyGCZhWwTQwxNA%40mail.gmail.com


The current "frontier": 
   - was summarized by Eric F,
     #+BEGIN_QUOTE
     I have the following defined in my org customisation:
      
     #+begin_src org
       (org-add-link-type "cite" 'ebib
                          (lambda (path desc format)
                            (cond
                             ((eq format 'latex)
                             (format "\\cite{%s}" path)))))
                              
     #+end_src
     which allows me to insert links like
     [[cite:jones-etal-2000][Jones et al., 2000]]
     #+END_QUOTE
     this is also on the Worg LaTeX page (it's what I use currently,
     but much more extensively).
     
     Here's a link for how I use Reftex:
     http://mid.gmane.org/878v5xhe8w.fsf%40pank.eu.

   - I pointed out that for citation we should use Reftex but as
     Aaron pointed out it might be too convoluted for use non-tex
     buffers and he suggests bibtex.el instead.  However, Reftex has
     a very nice interface and ships with Emacs which is a plus.  In
     my current setup I insert org citation links with Reftex.
     


Other implementations: 
  1. for html (pointed out by Aaron):
     https://bitbucket.org/fbennett/citeproc-js/wiki/Home
  2. citation in R-Markdown/Knitr-Markdown:
     https://github.com/cboettig/knitcitations
  3. Citation in Wordpress: http://wordpress.org/extend/plugins/kcite/

-- 
El Rey ha muerto. ¡Larga vida al Rey!