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 ;; The usage is as follows:
  32 ;;
  33 ;;   #+BIBLIOGRAPHY: bibfilebasename stylename optional-options
  34 ;;
  35 ;; e.g. given foo.bib and using style plain:
  36 ;;
  37 ;;   #+BIBLIOGRAPHY: foo plain option:-d
  38 ;;
  39 ;; Optional options are of the form:
  40 ;;
  41 ;;   option:-foobar pass '-foobar' to bibtex2html
  42 ;;
  43 ;; e.g.,
  44 ;;
  45 ;;   option:-d    sort by date
  46 ;;   option:-a    sort as BibTeX (usually by author) *default*
  47 ;;   option:-u    unsorted i.e. same order as in .bib file
  48 ;;   option:-r    reverse the sort
  49 ;;
  50 ;; See the bibtex2html man page for more.  Multiple options can be
  51 ;; combined like:
  52 ;;
  53 ;;   option:-d option:-r
  54 ;;
  55 ;; Limiting to only the entries cited in the document:
  56 ;;
  57 ;;   limit:t
  58 ;;
  59 ;; For LaTeX export this simply inserts the lines
  60 ;;
  61 ;;   \bibliographystyle{plain}
  62 ;;   \bibliography{foo}
  63 ;;
  64 ;; into the TeX file when exporting.
  65 ;;
  66 ;; For HTML export it:
  67 ;; 1) converts all \cite{foo} to links to the bibliography,
  68 ;; 2) creates a foo.html and foo_bib.html,
  69 ;; 3) includes the contents of foo.html in the exported HTML file.
  70
  71
  72 ;;; Internal Functions
  73
  74 (defun org-bibtex-get-file (keyword)
  75   "Return bibliography file as a string.
  76 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no file is found,
  77 return nil instead."
  78   (let ((value (org-element-property :value keyword)))
  79     (and value
  80          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
  81          (match-string 1 value))))
  82
  83 (defun org-bibtex-get-style (keyword)
  84   "Return bibliography style as a string.
  85 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no style is found,
  86 return nil instead."
  87   (let ((value (org-element-property :value keyword)))
  88     (and value
  89          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
  90          (match-string 2 value))))
  91
  92 (defun org-bibtex-get-arguments (keyword)
  93   "Return \"bibtex2html\" arguments specified by the user.
  94 KEYWORD is a \"BIBLIOGRAPHY\" keyword. Return value is a plist
  95 containing `:options' and `:limit' properties. The former
  96 contains a list of strings to be passed as options ot
  97 \"bibtex2html\" process. The latter contains a boolean."
  98   (let ((value (org-element-property :value keyword)))
  99     (and value
 100          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 101          (let (options limit)
 102            (dolist (arg (org-split-string (match-string 3 value))
 103                         ;; Return value.
 104                         (list :options (nreverse options) :limit limit))
 105              (let* ((s (split-string arg ":"))
 106                     (key (car s))
 107                     (value (nth 1 s)))
 108                (cond ((equal "limit" key)
 109                       (setq limit (not (equal "nil" value))))
 110                      ((equal "option" key) (push value options)))))))))
 111
 112 (defun org-bibtex-citation-p (fragment)
 113   "Non-nil when a LaTeX macro is a citation.
 114 FRAGMENT is a `latex-fragment' type object."
 115   (string-match "\\`\\\\cite{" (org-element-property :value fragment)))
 116
 117 (defun org-bibtex-get-citation-key (citation)
 118   "Return key for a given citation, as a string.
 119 CITATION is a `latex-fragment' type object satisfying to
 120 `org-bibtex-citation-p' predicate."
 121   (let ((value (org-element-property :value citation)))
 122     (and (string-match "\\`\\\\cite{" value)
 123          (substring value (match-end 0) -1))))
 124
 125
 126 \f
 127 ;;; LaTeX Part
 128
 129 (defadvice org-latex-keyword (around bibtex-keyword)
 130   "Translate \"BIBLIOGRAPHY\" keywords into LaTeX syntax.
 131 Fallback to `latex' back-end for other keywords."
 132   (let ((keyword (ad-get-arg 0)))
 133     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 134         ad-do-it
 135       (let ((file (org-bibtex-get-file keyword))
 136             (style (org-bibtex-get-style keyword)))
 137         (setq ad-return-value
 138               (when file
 139                 (concat (and style (format "\\bibliographystyle{%s}\n" style))
 140                         (format "\\bibliography{%s}" file))))))))
 141
 142 (ad-activate 'org-latex-keyword)
 143
 144
 145 \f
 146 ;;; HTML Part
 147
 148 (defvar org-bibtex-html-entries-alist nil)  ; Dynamically scoped.
 149 (defvar org-bibtex-html-keywords-alist nil) ; Dynamically scoped.
 150
 151
 152 ;;;; Advices
 153
 154 (defadvice org-html-keyword (around bibtex-keyword)
 155   "Translate \"BIBLIOGRAPHY\" keywords into HTML syntax.
 156 Fallback to `html' back-end for other keywords."
 157   (let ((keyword (ad-get-arg 0)))
 158     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 159         ad-do-it
 160       (setq ad-return-value
 161             (cdr (assq keyword org-bibtex-html-keywords-alist))))))
 162
 163 (defadvice org-html-latex-fragment (around bibtex-citation)
 164   "Translate \"\\cite\" LaTeX fragments into HTML syntax.
 165 Fallback to `html' back-end for other keywords."
 166   (let ((fragment (ad-get-arg 0)))
 167     (if (not (org-bibtex-citation-p fragment)) ad-do-it
 168       (setq ad-return-value
 169             (mapconcat
 170              (lambda (key)
 171                (let ((key (org-trim key)))
 172                  (format "[<a href=\"#%s\">%s</a>]"
 173                          key
 174                          (or (cdr (assoc key org-bibtex-html-entries-alist))
 175                              key))))
 176              (org-split-string (org-bibtex-get-citation-key fragment) ",")
 177              "")))))
 178
 179 (ad-activate 'org-html-keyword)
 180 (ad-activate 'org-html-latex-fragment)
 181
 182
 183 ;;;; Filter
 184
 185 (defun org-bibtex-process-bib-files (tree backend info)
 186   "Send each bibliography in parse tree to \"bibtex2html\" process.
 187 Return new parse tree.  This function assumes current back-end is HTML."
 188   ;; Initialize dynamically scoped variables.  The first one
 189   ;; contain an alist between keyword objects and their HTML
 190   ;; translation.  The second one will contain an alist between
 191   ;; citation keys and names in the output (according to style).
 192   (setq org-bibtex-html-entries-alist nil
 193         org-bibtex-html-keywords-alist nil)
 194   (org-element-map tree 'keyword
 195     (lambda (keyword)
 196       (when (equal (org-element-property :key keyword) "BIBLIOGRAPHY")
 197         (let ((arguments (org-bibtex-get-arguments keyword))
 198               (file (org-bibtex-get-file keyword))
 199               temp-file)
 200           ;; limit is set: collect citations throughout the document
 201           ;; in TEMP-FILE and pass it to "bibtex2html" as "-citefile"
 202           ;; argument.
 203           (when (plist-get arguments :limit)
 204             (let ((citations
 205                    (org-element-map tree 'latex-fragment
 206                      (lambda (fragment)
 207                        (and (org-bibtex-citation-p fragment)
 208                             (org-bibtex-get-citation-key fragment))))))
 209               (with-temp-file (setq temp-file (make-temp-file "ox-bibtex"))
 210                 (insert (mapconcat 'identity citations "\n")))
 211               (setq arguments
 212                     (plist-put arguments
 213                                :options
 214                                (append (plist-get arguments :options)
 215                                        (list "-citefile" temp-file))))))
 216           ;; Call "bibtex2html" on specified file.
 217           (unless (eq 0 (apply 'call-process
 218                                (append '("bibtex2html" nil nil nil)
 219                                        '("-a" "-nodoc" "-noheader" "-nofooter")
 220                                        (list "--style"
 221                                              (org-bibtex-get-style keyword))
 222                                        (plist-get arguments :options)
 223                                        (list (concat file ".bib")))))
 224             (error "Executing bibtex2html failed"))
 225           (and temp-file (delete-file temp-file))
 226           ;; Open produced HTML file, wrap references within a block and
 227           ;; return it.
 228           (with-temp-buffer
 229             (insert "<div id=\"bibliography\">\n<h2>References</h2>\n")
 230             (insert-file-contents (concat file ".html"))
 231             (insert "\n</div>")
 232             ;; Update `org-bibtex-html-keywords-alist'.
 233             (push (cons keyword (buffer-string))
 234                   org-bibtex-html-keywords-alist)
 235             ;; Update `org-bibtex-html-entries-alist'.
 236             (goto-char (point-min))
 237             (while (re-search-forward
 238                     "a name=\"\\([-_a-zA-Z0-9:]+\\)\">\\(\\w+\\)" nil t)
 239               (push (cons (match-string 1) (match-string 2))
 240                     org-bibtex-html-entries-alist)))))))
 241   ;; Return parse tree unchanged.
 242   tree)
 243
 244 (eval-after-load 'ox
 245   '(add-to-list 'org-export-filter-parse-tree-functions
 246                 'org-bibtex-process-bib-files))
 247
 248
 249
 250 (provide 'ox-bibtex)
 251
 252 ;;; ox-bibtex.el ends here