Re: [ANN] Bibliography support ODT + JabRef

[Jambunathan K <kjambunathan@gmail.com>]

I have finalized the JabRef + ODT export.  The changes can be pulled
from my own repo at

        HomePage: http://repo.or.cz/w/org-mode/org-kjn.git

        Pull URL: git://repo.or.cz/org-mode/org-kjn.git
                  http://repo.or.cz/r/org-mode/org-kjn.git

For purposes of quick testing, the files attached in the parent should
be good enough.

Here goes the commmit log.

    ox-odt: Add support for JabRef

    * contrib/lisp/ox-jabref.el: New file.

    * lisp/org.el (org-modules): Add ox-jabref.

    * etc/styles/OrgOdtStyles.xml (Bibliography_20_Heading)
    (Bibliography, OrgBibliographyList): New styles.

    * lisp/ox-odt.el (org-export-define-backend): New non-standard
    element `citation-reference'.  Register
    `org-odt--translate-cite-fragments'.
    (org-odt--translate-cite-fragments):  New filter.
    (org-odt-citation-transcoders): New user option.
    (org-odt-citation-reference, org-odt-citation-reference/numbered):
    Stock transcoders for `citation-reference' elements.
    (org-odt-keyword): Handle BIBLIOGRAPHY.
    (org-odt--export-wrap): Make the condition case debuggable.

    Also add autoloads for citation transcoders provided by
    ox-jabref.el.

    NOTE: Review all the above changes once ox.el provides standard
    tools for handling citaitons.

----------------------------------------------------------------

                            _______________

                               ORG-JABREF

                             Jambunathan K
                            _______________


Table of Contents
_________________

1 Quick start guide:
2 Developer (or Implementation) notes


1 Quick start guide:
====================

  1. Install [JabRef]

     This module is tested with version JabRef-2.9.2.jar.

  2. Install the JabRef plugin [Chicago Export filters for Org-mode].

  3. Configure ox-jabref.el

     ,----
     | M-x customize-group RET org-jabref RET
     `----

     Review the settings.

  4. Configure ox-odt.el

     ,----
     | M-x customize-variable RET org-odt-citation-transcoders RET
     `----

     Following settings are recommended.

     1. No citation support

        ,----
        | (setq org-odt-citation-transcoders
        |       '(org-odt-latex-fragment . ignore))
        `----

        This is the default setting.

        - #+BIBLIOGRAPHY is ignored.
        - \cite{} directives are typeset as plain text.

     2. Numeric Citations

        ,----
        | (setq org-odt-citation-transcoders
        |       '(org-odt-citation-reference/numbered
        |       . org-jabref-odt-bibliography/numbered))
        `----

        - #+BIBLIOGRAPHY is replaced with numerical listing of
          Bibliographic entries.  The listing includes only cited keys
          and is sorted on the order in which the cite keys are seen in
          the Org file.

        - \cite{} directives are replaced with numeric links to the
          associated Bibliographic entry.

     3. Unnumbered (or Text) Citations with Filtered Bibliography

        ,----
        | (setq org-odt-citation-transcoders
        |       '(org-jabref-odt-citation-reference/text
        |       . org-jabref-odt-bibliography/filtered))
        `----

        - #+BIBLIOGRAPHY is replaced with listing of Bibliographic
          entries.  The listing is limited to just the cited keys.  The
          listing is sorted based on the order chosen by JabRef engine.

        - \cite{} directives are replaced with textual links to the
          associated Bibliographic entry.

     4. Unnumbered (or Text) Citations with Filtered Bibliography

        ,----
        | (setq org-odt-citation-transcoders
        |       '(org-jabref-odt-citation-reference/text
        |       . org-jabref-odt-bibliography/unfiltered))
        `----

        - #+BIBLIOGRAPHY is replaced with listing of *all* Bibliographic
          entries.  The listing is limited to just the cited keys.  The
          listing is sorted based on the order chosen by JabRef engine.

        - \cite{} directives are replaced with textual links to the
          associated Bibliographic entry.

     5. Add the following line to your Org file and export.

        ,----
        | #+BIBLIOGRAPHY: MyLibrary.bib
        `----


  [JabRef] http://jabref.sourceforge.net/

  [Chicago Export filters for Org-mode]
  http://repo.or.cz/w/JabRefChicagoForOrgmode.git/blob_plain/HEAD:/net.sf.jabref.export.Chicago.ODF(English)-1.2.jar


2 Developer (or Implementation) notes
=====================================

  The current #+BIBLIOGRAPHY is defined in contrib/lisp/ox-bibtex.el.
  The syntax defined therein, is specific to a particular Citation
  Processor (i.e., bibtex2html) and cannot be expected to be honored by
  all backends AND citation processors[1].

  1. So having a "style" specification in a keyword line that is shared
     across all backends is absurd.[2]

  2. It is unclear how well a "limit: " option can be honored by *ALL*
     citation processors.

  To keep things simple (and flexible), ox-jabref.el resorts to the
  following:

  1. *Always* use the first found style registered for the current
     backend in `org-jabref-export-formats'

  2. "Limit"-ed (or non-"limit"-ed) export of Bibliographic entries can
     be achieved by using a different transcoder. See ""Quick start
     guide" above.



Footnotes
_________

[1] Note that the same Citation Processor (for example, JabRef) can be
used for catering to *both* HTML, ODT and even ASCII backends.

[2] *If* one settles for Org-wide styles, a possible translation from
Org-specific style to Citation-specific style needs to be done by each
backend.  This is the sole purpose of `org-jabref-export-formats'.

Having an Org-wide styles is well-neigh impossible.  In that case, the
best option is to settle for a specification like

,----
| #+ATTR_HTML: :bib2html-style "plain"
| #+ATTR_ODT: :jabref-style "Chicago (author-date)"
| #+BIBLIOGRAPHY: MyLibrary.bib
`----

Note the keywords in #+ATTR_BACKEND lines are prefixed with the
Citation Processor.  This is important in light of earlier comments
[1].