contrib/lisp/ox-bibtex.el

   1 ;;; ox-bibtex.el --- Export bibtex fragments
   2
   3 ;; Copyright (C) 2009-2014 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 LaTeX, html and ascii
  27 ;; exports.  For HTML and ascii it uses the bibtex2html software from:
  28 ;;
  29 ;;   http://www.lri.fr/~filliatr/bibtex2html/
  30 ;;
  31 ;; For ascii it uses the pandoc software from:
  32 ;;
  33 ;;   http://johnmacfarlane.net/pandoc/
  34 ;;
  35 ;; It also introduces "cite" syntax for Org links.
  36 ;;
  37 ;; The usage is as follows:
  38 ;;
  39 ;;   #+BIBLIOGRAPHY: bibfilebasename stylename optional-options
  40 ;;
  41 ;; e.g. given foo.bib and using style plain:
  42 ;;
  43 ;;   #+BIBLIOGRAPHY: foo plain option:-d
  44 ;;
  45 ;; "stylename" can also be "nil", in which case no style will be used.
  46 ;;
  47 ;; Optional options are of the form:
  48 ;;
  49 ;;   option:-foobar pass '-foobar' to bibtex2html
  50 ;;
  51 ;; e.g.,
  52 ;;
  53 ;;   option:-d    sort by date
  54 ;;   option:-a    sort as BibTeX (usually by author) *default*
  55 ;;   option:-u    unsorted i.e. same order as in .bib file
  56 ;;   option:-r    reverse the sort
  57 ;;
  58 ;; See the bibtex2html man page for more.  Multiple options can be
  59 ;; combined like:
  60 ;;
  61 ;;   option:-d option:-r
  62 ;;
  63 ;; Limiting to only the entries cited in the document:
  64 ;;
  65 ;;   limit:t
  66 ;;
  67 ;; For LaTeX export this simply inserts the lines
  68 ;;
  69 ;;   \bibliographystyle{plain}
  70 ;;   \bibliography{foo}
  71 ;;
  72 ;; into the TeX file when exporting.
  73 ;;
  74 ;; For HTML export it:
  75 ;; 1) converts all \cite{foo} and [[cite:foo]] to links to the
  76 ;;    bibliography,
  77 ;; 2) creates a foo.html and foo_bib.html,
  78 ;; 3) includes the contents of foo.html in the exported HTML file.
  79 ;;
  80 ;; For ascii export it:
  81 ;; 1) converts all \cite{foo} and [[cite:foo]] to links to the
  82 ;;    bibliography,
  83 ;; 2) creates a foo.txt and foo_bib.html,
  84 ;; 3) includes the contents of foo.txt in the exported ascii file.
  85 ;;
  86 ;; For LaTeX export it:
  87 ;; 1) converts all [[cite:foo]] to \cite{foo}.
  88
  89 ;; Initialization
  90
  91 (eval-when-compile (require 'cl))
  92 (let ((jump-fn (car (org-remove-if-not #'fboundp '(ebib obe-goto-citation)))))
  93   (org-add-link-type "cite" jump-fn))
  94
  95 ;;; Internal Functions
  96
  97 (defun org-bibtex-get-file (keyword)
  98   "Return bibliography file as a string.
  99 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no file is found,
 100 return nil instead."
 101   (let ((value (org-element-property :value keyword)))
 102     (and value
 103          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 104          (match-string 1 value))))
 105
 106 (defun org-bibtex-get-style (keyword)
 107   "Return bibliography style as a string.
 108 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no style is found,
 109 return nil instead."
 110   (let ((value (org-element-property :value keyword)))
 111     (and value
 112          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 113          (match-string 2 value))))
 114
 115 (defun org-bibtex-get-arguments (keyword)
 116   "Return \"bibtex2html\" arguments specified by the user.
 117 KEYWORD is a \"BIBLIOGRAPHY\" keyword. Return value is a plist
 118 containing `:options' and `:limit' properties.  The former
 119 contains a list of strings to be passed as options to
 120 \"bibtex2html\" process.  The latter contains a boolean."
 121   (let ((value (org-element-property :value keyword)))
 122     (and value
 123          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 124          (let (options limit)
 125            (dolist (arg (org-split-string (match-string 3 value))
 126                         ;; Return value.
 127                         (list :options (nreverse options) :limit limit))
 128              (let* ((s (split-string arg ":"))
 129                     (key (car s))
 130                     (value (nth 1 s)))
 131                (cond ((equal "limit" key)
 132                       (setq limit (not (equal "nil" value))))
 133                      ((equal "option" key) (push value options)))))))))
 134
 135 (defun org-bibtex-citation-p (object)
 136   "Non-nil when OBJECT is a citation."
 137   (case (org-element-type object)
 138     (link (equal (org-element-property :type object) "cite"))
 139     (latex-fragment
 140      (string-match "\\`\\\\cite{" (org-element-property :value object)))))
 141
 142 (defun org-bibtex-get-citation-key (citation)
 143   "Return key for a given citation, as a string.
 144 CITATION is a `latex-fragment' or `link' type object satisfying
 145 to `org-bibtex-citation-p' predicate."
 146   (if (eq (org-element-type citation) 'link)
 147       (org-element-property :path citation)
 148     (let ((value (org-element-property :value citation)))
 149       (and (string-match "\\`\\\\cite{" value)
 150            (substring value (match-end 0) -1)))))
 151
 152
 153 \f
 154 ;;; Filters
 155
 156 (defun org-bibtex-process-bib-files (tree backend info)
 157   "Send each bibliography in parse tree to \"bibtex2html\" process.
 158 Return new parse tree."
 159   (when (org-export-derived-backend-p backend 'ascii 'html)
 160     ;; Initialize dynamically scoped variables.  The first one
 161     ;; contain an alist between keyword objects and their HTML
 162     ;; translation.  The second one will contain an alist between
 163     ;; citation keys and names in the output (according to style).
 164     (setq org-bibtex-html-entries-alist nil
 165           org-bibtex-html-keywords-alist nil)
 166     (org-element-map tree 'keyword
 167       (lambda (keyword)
 168         (when (equal (org-element-property :key keyword) "BIBLIOGRAPHY")
 169           (let ((arguments (org-bibtex-get-arguments keyword))
 170                 (file (org-bibtex-get-file keyword))
 171                 temp-file)
 172             ;; limit is set: collect citations throughout the document
 173             ;; in TEMP-FILE and pass it to "bibtex2html" as "-citefile"
 174             ;; argument.
 175             (when (plist-get arguments :limit)
 176               (let ((citations
 177                      (org-element-map tree '(latex-fragment link)
 178                        (lambda (object)
 179                          (and (org-bibtex-citation-p object)
 180                               (org-bibtex-get-citation-key object))))))
 181                 (with-temp-file (setq temp-file (make-temp-file "ox-bibtex"))
 182                   (insert (mapconcat 'identity citations "\n")))
 183                 (setq arguments
 184                       (plist-put arguments
 185                                  :options
 186                                  (append (plist-get arguments :options)
 187                                          (list "-citefile" temp-file))))))
 188             ;; Call "bibtex2html" on specified file.
 189             (unless (eq 0 (apply
 190                            'call-process
 191                            (append '("bibtex2html" nil nil nil)
 192                                    '("-a" "-nodoc" "-noheader" "-nofooter")
 193                                    (let ((style
 194                                           (org-not-nil
 195                                            (org-bibtex-get-style keyword))))
 196                                      (and style (list "--style" style)))
 197                                    (plist-get arguments :options)
 198                                    (list (concat file ".bib")))))
 199               (error "Executing bibtex2html failed"))
 200             (and temp-file (delete-file temp-file))
 201             ;; Open produced HTML file, and collect Bibtex key names
 202             (with-temp-buffer
 203               (insert-file-contents (concat file ".html"))
 204               ;; Update `org-bibtex-html-entries-alist'.
 205               (goto-char (point-min))
 206               (while (re-search-forward
 207                       "a name=\"\\([-_a-zA-Z0-9:]+\\)\">\\(\\w+\\)" nil t)
 208                 (push (cons (match-string 1) (match-string 2))
 209                       org-bibtex-html-entries-alist)))
 210             ;; Open produced HTML file, wrap references within a block and
 211             ;; return it.
 212             (with-temp-buffer
 213               (cond
 214                ((org-export-derived-backend-p backend 'html)
 215                 (insert (format "<div id=\"bibliography\">\n<h2>%s</h2>\n"
 216                                 (org-export-translate "References" :html info)))
 217                 (insert-file-contents (concat file ".html"))
 218                 (insert "\n</div>"))
 219                ((org-export-derived-backend-p backend 'ascii)
 220                 ;; convert HTML references to text w/pandoc
 221                 (unless (eq 0 (call-process "pandoc" nil nil nil
 222                                             (concat file ".html")
 223                                             "-o"
 224                                             (concat file ".txt")))
 225                   (error "Executing pandoc failed"))
 226                 (insert
 227                  (format
 228                   "%s\n==========\n\n"
 229                   (org-export-translate
 230                    "References"
 231                    (intern (format ":%s" (plist-get info :ascii-charset)))
 232                    info)))
 233                 (insert-file-contents (concat file ".txt"))
 234                 (goto-char (point-min))
 235                 (while (re-search-forward
 236                         "\\[ \\[bib\\][^ ]+ \\(\\]\\||[\n\r]\\)" nil t)
 237                   (replace-match ""))
 238                 (goto-char (point-min))
 239                 (while (re-search-forward "\\( \\]\\| \\]\\| |\\)" nil t)
 240                   (replace-match ""))
 241                 (goto-char (point-min))
 242                 (while (re-search-forward "[\n\r]\\([\n\r][\n\r]\\)" nil t)
 243                   (replace-match "\\1"))))
 244               ;; Update `org-bibtex-html-keywords-alist'.
 245               (push (cons keyword (buffer-string))
 246                     org-bibtex-html-keywords-alist)))))))
 247   ;; Return parse tree unchanged.
 248   tree)
 249
 250 (defun org-bibtex-merge-contiguous-citations (tree backend info)
 251   "Merge all contiguous citation in parse tree.
 252 As a side effect, this filter will also turn all \"cite\" links
 253 into \"\\cite{...}\" LaTeX fragments and will extract options
 254 into square brackets at the beginning of the \"\\cite\" command."
 255   (when (org-export-derived-backend-p backend 'html 'latex 'ascii)
 256     (org-element-map tree '(link latex-fragment)
 257       (lambda (object)
 258         (when (org-bibtex-citation-p object)
 259           (let ((new-citation (list 'latex-fragment
 260                                     (list :value ""
 261                                           :post-blank (org-element-property
 262                                                        :post-blank object))))
 263                 option)
 264             ;; Insert NEW-CITATION right before OBJECT.
 265             (org-element-insert-before new-citation object)
 266             ;; Remove all subsequent contiguous citations from parse
 267             ;; tree, keeping only their citation key.
 268             (let ((keys (list (org-bibtex-get-citation-key object)))
 269                   next)
 270               (while (and (setq next (org-export-get-next-element object info))
 271                           (or (and (stringp next)
 272                                    (not (org-string-match-p "\\S-" next)))
 273                               (org-bibtex-citation-p next)))
 274                 (unless (stringp next)
 275                   (push (org-bibtex-get-citation-key next) keys))
 276                 (org-element-extract-element object)
 277                 (setq object next))
 278               ;; Find any options in keys, e.g., "(Chapter 2)key" has
 279               ;; the option "Chapter 2".
 280               (setq keys
 281                     (mapcar
 282                      (lambda (k)
 283                        (if (string-match "^(\\([^)]\+\\))\\(.*\\)" k)
 284                            (progn
 285                              (setq option (format "[%s]" (match-string 1 k)))
 286                              (match-string 2 k))
 287                          k))
 288                      keys))
 289               (org-element-extract-element object)
 290               ;; Eventually merge all keys within NEW-CITATION.  Also
 291               ;; ensure NEW-CITATION has the same :post-blank property
 292               ;; as the last citation removed.
 293               (org-element-put-property
 294                new-citation
 295                :post-blank (org-element-property :post-blank object))
 296               (org-element-put-property
 297                new-citation
 298                :value (format "\\cite%s{%s}"
 299                               (or option "")
 300                               (mapconcat 'identity (nreverse keys) ",")))))))))
 301   tree)
 302
 303 (eval-after-load 'ox
 304   '(progn (add-to-list 'org-export-filter-parse-tree-functions
 305                        'org-bibtex-process-bib-files)
 306           (add-to-list 'org-export-filter-parse-tree-functions
 307                        'org-bibtex-merge-contiguous-citations)))
 308
 309
 310 \f
 311 ;;; LaTeX Part
 312
 313 (defadvice org-latex-keyword (around bibtex-keyword)
 314   "Translate \"BIBLIOGRAPHY\" keywords into LaTeX syntax.
 315 Fallback to `latex' back-end for other keywords."
 316   (let ((keyword (ad-get-arg 0)))
 317     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 318         ad-do-it
 319       (let ((file (org-bibtex-get-file keyword))
 320             (style (org-not-nil (org-bibtex-get-style keyword))))
 321         (setq ad-return-value
 322               (when file
 323                 (concat (and style (format "\\bibliographystyle{%s}\n" style))
 324                         (format "\\bibliography{%s}" file))))))))
 325
 326 (ad-activate 'org-latex-keyword)
 327
 328
 329 \f
 330 ;;; HTML Part
 331
 332 (defvar org-bibtex-html-entries-alist nil)  ; Dynamically scoped.
 333 (defvar org-bibtex-html-keywords-alist nil) ; Dynamically scoped.
 334
 335
 336 ;;;; Advices
 337
 338 (defadvice org-html-keyword (around bibtex-keyword)
 339   "Translate \"BIBLIOGRAPHY\" keywords into HTML syntax.
 340 Fallback to `html' back-end for other keywords."
 341   (let ((keyword (ad-get-arg 0)))
 342     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 343         ad-do-it
 344       (setq ad-return-value
 345             (cdr (assq keyword org-bibtex-html-keywords-alist))))))
 346
 347 (defadvice org-html-latex-fragment (around bibtex-citation)
 348   "Translate \"\\cite\" LaTeX fragments into HTML syntax.
 349 Fallback to `html' back-end for other keywords."
 350   (let ((fragment (ad-get-arg 0)))
 351     (if (not (org-bibtex-citation-p fragment)) ad-do-it
 352       (setq ad-return-value
 353             (format "[%s]"
 354                     (mapconcat
 355                      (lambda (key)
 356                        (format "<a href=\"#%s\">%s</a>"
 357                                key
 358                                (or (cdr (assoc key org-bibtex-html-entries-alist))
 359                                    key)))
 360                      (org-split-string
 361                       (org-bibtex-get-citation-key fragment) ",") ","))))))
 362
 363 (ad-activate 'org-html-keyword)
 364 (ad-activate 'org-html-latex-fragment)
 365
 366 \f
 367 ;;; Ascii Part
 368 (defadvice org-ascii-keyword (around bibtex-keyword)
 369   "Translate \"BIBLIOGRAPHY\" keywords into ascii syntax.
 370 Fallback to `ascii' back-end for other keywords."
 371   (let ((keyword (ad-get-arg 0)))
 372     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 373         ad-do-it
 374       (setq ad-return-value
 375             (cdr (assq keyword org-bibtex-html-keywords-alist))))))
 376
 377 (defadvice org-ascii-latex-fragment (around bibtex-citation)
 378   "Translate \"\\cite\" LaTeX fragments into ascii syntax.
 379 Fallback to `ascii' back-end for other keywords."
 380   (let ((fragment (ad-get-arg 0)))
 381     (if (not (org-bibtex-citation-p fragment)) ad-do-it
 382       (setq ad-return-value
 383             (format "[%s]"
 384                     (mapconcat
 385                      (lambda (key)
 386                        (or (cdr (assoc key org-bibtex-html-entries-alist))
 387                            key))
 388                      (org-split-string
 389                       (org-bibtex-get-citation-key fragment) ",") ","))))))
 390
 391 (ad-activate 'org-ascii-keyword)
 392 (ad-activate 'org-ascii-latex-fragment)
 393
 394 (provide 'ox-bibtex)
 395
 396 ;;; ox-bibtex.el ends here