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 Cite options are placed into square brackets at the beginning of
 255 the \"\\cite\" command for the LaTeX backend, and are removed for
 256 the HTML and ASCII backends."
 257   (when (org-export-derived-backend-p backend 'html 'latex 'ascii)
 258     (org-element-map tree '(link latex-fragment)
 259       (lambda (object)
 260         (when (org-bibtex-citation-p object)
 261           (let ((new-citation (list 'latex-fragment
 262                                     (list :value ""
 263                                           :post-blank (org-element-property
 264                                                        :post-blank object))))
 265                 option)
 266             ;; Insert NEW-CITATION right before OBJECT.
 267             (org-element-insert-before new-citation object)
 268             ;; Remove all subsequent contiguous citations from parse
 269             ;; tree, keeping only their citation key.
 270             (let ((keys (list (org-bibtex-get-citation-key object)))
 271                   next)
 272               (while (and (setq next (org-export-get-next-element object info))
 273                           (or (and (stringp next)
 274                                    (not (org-string-match-p "\\S-" next)))
 275                               (org-bibtex-citation-p next)))
 276                 (unless (stringp next)
 277                   (push (org-bibtex-get-citation-key next) keys))
 278                 (org-element-extract-element object)
 279                 (setq object next))
 280               ;; Find any options in keys, e.g., "(Chapter 2)key" has
 281               ;; the option "Chapter 2".
 282               (setq keys
 283                     (mapcar
 284                      (lambda (k)
 285                        (if (string-match "^(\\([^)]\+\\))\\(.*\\)" k)
 286                            (progn
 287                              (when (org-export-derived-backend-p backend 'latex)
 288                                (setq option (format "[%s]" (match-string 1 k))))
 289                              (match-string 2 k))
 290                          k))
 291                      keys))
 292               (org-element-extract-element object)
 293               ;; Eventually merge all keys within NEW-CITATION.  Also
 294               ;; ensure NEW-CITATION has the same :post-blank property
 295               ;; as the last citation removed.
 296               (org-element-put-property
 297                new-citation
 298                :post-blank (org-element-property :post-blank object))
 299               (org-element-put-property
 300                new-citation
 301                :value (format "\\cite%s{%s}"
 302                               (or option "")
 303                               (mapconcat 'identity (nreverse keys) ",")))))))))
 304   tree)
 305
 306 (eval-after-load 'ox
 307   '(progn (add-to-list 'org-export-filter-parse-tree-functions
 308                        'org-bibtex-process-bib-files)
 309           (add-to-list 'org-export-filter-parse-tree-functions
 310                        'org-bibtex-merge-contiguous-citations)))
 311
 312
 313 \f
 314 ;;; LaTeX Part
 315
 316 (defadvice org-latex-keyword (around bibtex-keyword)
 317   "Translate \"BIBLIOGRAPHY\" keywords into LaTeX syntax.
 318 Fallback to `latex' back-end for other keywords."
 319   (let ((keyword (ad-get-arg 0)))
 320     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 321         ad-do-it
 322       (let ((file (org-bibtex-get-file keyword))
 323             (style (org-not-nil (org-bibtex-get-style keyword))))
 324         (setq ad-return-value
 325               (when file
 326                 (concat (and style (format "\\bibliographystyle{%s}\n" style))
 327                         (format "\\bibliography{%s}" file))))))))
 328
 329 (ad-activate 'org-latex-keyword)
 330
 331
 332 \f
 333 ;;; HTML Part
 334
 335 (defvar org-bibtex-html-entries-alist nil)  ; Dynamically scoped.
 336 (defvar org-bibtex-html-keywords-alist nil) ; Dynamically scoped.
 337
 338
 339 ;;;; Advices
 340
 341 (defadvice org-html-keyword (around bibtex-keyword)
 342   "Translate \"BIBLIOGRAPHY\" keywords into HTML syntax.
 343 Fallback to `html' back-end for other keywords."
 344   (let ((keyword (ad-get-arg 0)))
 345     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 346         ad-do-it
 347       (setq ad-return-value
 348             (cdr (assq keyword org-bibtex-html-keywords-alist))))))
 349
 350 (defadvice org-html-latex-fragment (around bibtex-citation)
 351   "Translate \"\\cite\" LaTeX fragments into HTML syntax.
 352 Fallback to `html' back-end for other keywords."
 353   (let ((fragment (ad-get-arg 0)))
 354     (if (not (org-bibtex-citation-p fragment)) ad-do-it
 355       (setq ad-return-value
 356             (format "[%s]"
 357                     (mapconcat
 358                      (lambda (key)
 359                        (format "<a href=\"#%s\">%s</a>"
 360                                key
 361                                (or (cdr (assoc key org-bibtex-html-entries-alist))
 362                                    key)))
 363                      (org-split-string
 364                       (org-bibtex-get-citation-key fragment) ",") ","))))))
 365
 366 (ad-activate 'org-html-keyword)
 367 (ad-activate 'org-html-latex-fragment)
 368
 369 \f
 370 ;;; Ascii Part
 371 (defadvice org-ascii-keyword (around bibtex-keyword)
 372   "Translate \"BIBLIOGRAPHY\" keywords into ascii syntax.
 373 Fallback to `ascii' back-end for other keywords."
 374   (let ((keyword (ad-get-arg 0)))
 375     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 376         ad-do-it
 377       (setq ad-return-value
 378             (cdr (assq keyword org-bibtex-html-keywords-alist))))))
 379
 380 (defadvice org-ascii-latex-fragment (around bibtex-citation)
 381   "Translate \"\\cite\" LaTeX fragments into ascii syntax.
 382 Fallback to `ascii' back-end for other keywords."
 383   (let ((fragment (ad-get-arg 0)))
 384     (if (not (org-bibtex-citation-p fragment)) ad-do-it
 385       (setq ad-return-value
 386             (format "[%s]"
 387                     (mapconcat
 388                      (lambda (key)
 389                        (or (cdr (assoc key org-bibtex-html-entries-alist))
 390                            key))
 391                      (org-split-string
 392                       (org-bibtex-get-citation-key fragment) ",") ","))))))
 393
 394 (ad-activate 'org-ascii-keyword)
 395 (ad-activate 'org-ascii-latex-fragment)
 396
 397 (provide 'ox-bibtex)
 398
 399 ;;; ox-bibtex.el ends here