contrib/lisp/ox-bibtex.el

   1 ;;; ox-bibtex.el --- Export bibtex fragments
   2
   3 ;; Copyright (C) 2009-2013 Taru Karttunen
   4
   5 ;; Author: Taru Karttunen <taruti@taruti.net>
   6 ;;      Nicolas Goaziou <n dot goaziou at gmail dot com>
   7 ;; This file is not currently part of GNU Emacs.
   8
   9 ;; This program is free software; you can redistribute it and/or
  10 ;; modify it under the terms of the GNU General Public License as
  11 ;; published by the Free Software Foundation; either version 2, or (at
  12 ;; your option) any later version.
  13
  14 ;; This program is distributed in the hope that it will be useful, but
  15 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 ;; General Public License for more details.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with this program ; see the file COPYING.  If not, write to
  21 ;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  22 ;; Boston, MA 02111-1307, USA.
  23
  24 ;;; Commentary:
  25 ;;
  26 ;; This is an utility to handle BibTeX export to both LaTeX and html
  27 ;; exports.  It uses the bibtex2html software from:
  28 ;;
  29 ;;   http://www.lri.fr/~filliatr/bibtex2html/
  30 ;;
  31 ;; It also introduces "cite" syntax for Org links.
  32 ;;
  33 ;; The usage is as follows:
  34 ;;
  35 ;;   #+BIBLIOGRAPHY: bibfilebasename stylename optional-options
  36 ;;
  37 ;; e.g. given foo.bib and using style plain:
  38 ;;
  39 ;;   #+BIBLIOGRAPHY: foo plain option:-d
  40 ;;
  41 ;; Optional options are of the form:
  42 ;;
  43 ;;   option:-foobar pass '-foobar' to bibtex2html
  44 ;;
  45 ;; e.g.,
  46 ;;
  47 ;;   option:-d    sort by date
  48 ;;   option:-a    sort as BibTeX (usually by author) *default*
  49 ;;   option:-u    unsorted i.e. same order as in .bib file
  50 ;;   option:-r    reverse the sort
  51 ;;
  52 ;; See the bibtex2html man page for more.  Multiple options can be
  53 ;; combined like:
  54 ;;
  55 ;;   option:-d option:-r
  56 ;;
  57 ;; Limiting to only the entries cited in the document:
  58 ;;
  59 ;;   limit:t
  60 ;;
  61 ;; For LaTeX export this simply inserts the lines
  62 ;;
  63 ;;   \bibliographystyle{plain}
  64 ;;   \bibliography{foo}
  65 ;;
  66 ;; into the TeX file when exporting.
  67 ;;
  68 ;; For HTML export it:
  69 ;; 1) converts all \cite{foo} and [[cite:foo]] to links to the
  70 ;;    bibliography,
  71 ;; 2) creates a foo.html and foo_bib.html,
  72 ;; 3) includes the contents of foo.html in the exported HTML file.
  73 ;;
  74 ;; For LaTeX export it:
  75 ;; 1) converts all [[cite:foo]] to \cite{foo}.
  76
  77 ;; Initialization
  78
  79 (eval-when-compile (require 'cl))
  80 (let ((jump-fn (car (org-remove-if-not #'fboundp '(ebib obe-goto-citation)))))
  81   (org-add-link-type "cite" jump-fn))
  82
  83 ;;; Internal Functions
  84
  85 (defun org-bibtex-get-file (keyword)
  86   "Return bibliography file as a string.
  87 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no file is found,
  88 return nil instead."
  89   (let ((value (org-element-property :value keyword)))
  90     (and value
  91          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
  92          (match-string 1 value))))
  93
  94 (defun org-bibtex-get-style (keyword)
  95   "Return bibliography style as a string.
  96 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no style is found,
  97 return nil instead."
  98   (let ((value (org-element-property :value keyword)))
  99     (and value
 100          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 101          (match-string 2 value))))
 102
 103 (defun org-bibtex-get-arguments (keyword)
 104   "Return \"bibtex2html\" arguments specified by the user.
 105 KEYWORD is a \"BIBLIOGRAPHY\" keyword. Return value is a plist
 106 containing `:options' and `:limit' properties. The former
 107 contains a list of strings to be passed as options ot
 108 \"bibtex2html\" process. The latter contains a boolean."
 109   (let ((value (org-element-property :value keyword)))
 110     (and value
 111          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 112          (let (options limit)
 113            (dolist (arg (org-split-string (match-string 3 value))
 114                         ;; Return value.
 115                         (list :options (nreverse options) :limit limit))
 116              (let* ((s (split-string arg ":"))
 117                     (key (car s))
 118                     (value (nth 1 s)))
 119                (cond ((equal "limit" key)
 120                       (setq limit (not (equal "nil" value))))
 121                      ((equal "option" key) (push value options)))))))))
 122
 123 (defun org-bibtex-citation-p (object)
 124   "Non-nil when OBJECT is a citation."
 125   (case (org-element-type object)
 126     (link (equal (org-element-property :type object) "cite"))
 127     (latex-fragment
 128      (string-match "\\`\\\\cite{" (org-element-property :value object)))))
 129
 130 (defun org-bibtex-get-citation-key (citation)
 131   "Return key for a given citation, as a string.
 132 CITATION is a `latex-fragment' or `link' type object satisfying
 133 to `org-bibtex-citation-p' predicate."
 134   (if (eq (org-element-type citation) 'link)
 135       (org-element-property :path citation)
 136     (let ((value (org-element-property :value citation)))
 137       (and (string-match "\\`\\\\cite{" value)
 138            (substring value (match-end 0) -1)))))
 139
 140
 141 \f
 142 ;;; LaTeX Part
 143
 144 (defadvice org-latex-keyword (around bibtex-keyword)
 145   "Translate \"BIBLIOGRAPHY\" keywords into LaTeX syntax.
 146 Fallback to `latex' back-end for other keywords."
 147   (let ((keyword (ad-get-arg 0)))
 148     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 149         ad-do-it
 150       (let ((file (org-bibtex-get-file keyword))
 151             (style (org-bibtex-get-style keyword)))
 152         (setq ad-return-value
 153               (when file
 154                 (concat (and style (format "\\bibliographystyle{%s}\n" style))
 155                         (format "\\bibliography{%s}" file))))))))
 156
 157 (defadvice org-latex-link (around bibtex-link)
 158   "Translate \"cite\" type links into LaTeX syntax.
 159 Fallback to `latex' back-end for other keywords."
 160   (let ((link (ad-get-arg 0)))
 161     (if (not (org-bibtex-citation-p link)) ad-do-it
 162       (setq ad-return-value
 163             (format "\\cite{%s}" (org-bibtex-get-citation-key link))))))
 164
 165 (ad-activate 'org-latex-keyword)
 166 (ad-activate 'org-latex-link)
 167
 168
 169 \f
 170 ;;; HTML Part
 171
 172 (defvar org-bibtex-html-entries-alist nil)  ; Dynamically scoped.
 173 (defvar org-bibtex-html-keywords-alist nil) ; Dynamically scoped.
 174
 175
 176 ;;;; Advices
 177
 178 (defadvice org-html-keyword (around bibtex-keyword)
 179   "Translate \"BIBLIOGRAPHY\" keywords into HTML syntax.
 180 Fallback to `html' back-end for other keywords."
 181   (let ((keyword (ad-get-arg 0)))
 182     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 183         ad-do-it
 184       (setq ad-return-value
 185             (cdr (assq keyword org-bibtex-html-keywords-alist))))))
 186
 187 (defadvice org-html-latex-fragment (around bibtex-citation)
 188   "Translate \"\\cite\" LaTeX fragments into HTML syntax.
 189 Fallback to `html' back-end for other keywords."
 190   (let ((fragment (ad-get-arg 0)))
 191     (if (not (org-bibtex-citation-p fragment)) ad-do-it
 192       (setq ad-return-value
 193             (mapconcat
 194              (lambda (key)
 195                (let ((key (org-trim key)))
 196                  (format "[<a href=\"#%s\">%s</a>]"
 197                          key
 198                          (or (cdr (assoc key org-bibtex-html-entries-alist))
 199                              key))))
 200              (org-split-string (org-bibtex-get-citation-key fragment) ",")
 201              "")))))
 202
 203 (defadvice org-html-link (around bibtex-link)
 204   "Translate \"cite:\" type links into HTML syntax.
 205 Fallback to `html' back-end for other types."
 206   (let ((link (ad-get-arg 0)))
 207     (if (not (org-bibtex-citation-p link)) ad-do-it
 208       (setq ad-return-value
 209             (mapconcat
 210              (lambda (key)
 211                (format "[<a href=\"#%s\">%s</a>]"
 212                        key
 213                        (or (cdr (assoc key org-bibtex-html-entries-alist))
 214                            key)))
 215              (org-split-string (org-bibtex-get-citation-key link)
 216                                "[ \t]*,[ \t]*")
 217              "")))))
 218
 219 (ad-activate 'org-html-keyword)
 220 (ad-activate 'org-html-latex-fragment)
 221 (ad-activate 'org-html-link)
 222
 223
 224 ;;;; Filter
 225
 226 (defun org-bibtex-process-bib-files (tree backend info)
 227   "Send each bibliography in parse tree to \"bibtex2html\" process.
 228 Return new parse tree.  This function assumes current back-end is HTML."
 229   ;; Initialize dynamically scoped variables.  The first one
 230   ;; contain an alist between keyword objects and their HTML
 231   ;; translation.  The second one will contain an alist between
 232   ;; citation keys and names in the output (according to style).
 233   (setq org-bibtex-html-entries-alist nil
 234         org-bibtex-html-keywords-alist nil)
 235   (org-element-map tree 'keyword
 236     (lambda (keyword)
 237       (when (equal (org-element-property :key keyword) "BIBLIOGRAPHY")
 238         (let ((arguments (org-bibtex-get-arguments keyword))
 239               (file (org-bibtex-get-file keyword))
 240               temp-file)
 241           ;; limit is set: collect citations throughout the document
 242           ;; in TEMP-FILE and pass it to "bibtex2html" as "-citefile"
 243           ;; argument.
 244           (when (plist-get arguments :limit)
 245             (let ((citations
 246                    (org-element-map tree '(latex-fragment link)
 247                      (lambda (object)
 248                        (and (org-bibtex-citation-p object)
 249                             (org-bibtex-get-citation-key object))))))
 250               (with-temp-file (setq temp-file (make-temp-file "ox-bibtex"))
 251                 (insert (mapconcat 'identity citations "\n")))
 252               (setq arguments
 253                     (plist-put arguments
 254                                :options
 255                                (append (plist-get arguments :options)
 256                                        (list "-citefile" temp-file))))))
 257           ;; Call "bibtex2html" on specified file.
 258           (unless (eq 0 (apply 'call-process
 259                                (append '("bibtex2html" nil nil nil)
 260                                        '("-a" "-nodoc" "-noheader" "-nofooter")
 261                                        (list "--style"
 262                                              (org-bibtex-get-style keyword))
 263                                        (plist-get arguments :options)
 264                                        (list (concat file ".bib")))))
 265             (error "Executing bibtex2html failed"))
 266           (and temp-file (delete-file temp-file))
 267           ;; Open produced HTML file, wrap references within a block and
 268           ;; return it.
 269           (with-temp-buffer
 270             (insert "<div id=\"bibliography\">\n<h2>References</h2>\n")
 271             (insert-file-contents (concat file ".html"))
 272             (insert "\n</div>")
 273             ;; Update `org-bibtex-html-keywords-alist'.
 274             (push (cons keyword (buffer-string))
 275                   org-bibtex-html-keywords-alist)
 276             ;; Update `org-bibtex-html-entries-alist'.
 277             (goto-char (point-min))
 278             (while (re-search-forward
 279                     "a name=\"\\([-_a-zA-Z0-9:]+\\)\">\\(\\w+\\)" nil t)
 280               (push (cons (match-string 1) (match-string 2))
 281                     org-bibtex-html-entries-alist)))))))
 282   ;; Return parse tree unchanged.
 283   tree)
 284
 285 (eval-after-load 'ox
 286   '(add-to-list 'org-export-filter-parse-tree-functions
 287                 (lambda (e b i) (when (eql b 'html)
 288                              (org-bibtex-process-bib-files e b i)))))
 289
 290
 291
 292 (provide 'ox-bibtex)
 293
 294 ;;; ox-bibtex.el ends here