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
  93 ;;; Internal Functions
  94
  95 (defun org-bibtex-get-file (keyword)
  96   "Return bibliography file as a string.
  97 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no file is found,
  98 return nil instead."
  99   (let ((value (org-element-property :value keyword)))
 100     (and value
 101          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 102          (match-string 1 value))))
 103
 104 (defun org-bibtex-get-style (keyword)
 105   "Return bibliography style as a string.
 106 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no style is found,
 107 return nil instead."
 108   (let ((value (org-element-property :value keyword)))
 109     (and value
 110          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 111          (match-string 2 value))))
 112
 113 (defun org-bibtex-get-arguments (keyword)
 114   "Return \"bibtex2html\" arguments specified by the user.
 115 KEYWORD is a \"BIBLIOGRAPHY\" keyword. Return value is a plist
 116 containing `:options' and `:limit' properties.  The former
 117 contains a list of strings to be passed as options to
 118 \"bibtex2html\" process.  The latter contains a boolean."
 119   (let ((value (org-element-property :value keyword)))
 120     (and value
 121          (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value)
 122          (let (options limit)
 123            (dolist (arg (org-split-string (match-string 3 value))
 124                         ;; Return value.
 125                         (list :options (nreverse options) :limit limit))
 126              (let* ((s (split-string arg ":"))
 127                     (key (car s))
 128                     (value (nth 1 s)))
 129                (cond ((equal "limit" key)
 130                       (setq limit (not (equal "nil" value))))
 131                      ((equal "option" key) (push value options)))))))))
 132
 133 (defun org-bibtex-citation-p (object)
 134   "Non-nil when OBJECT is a citation."
 135   (case (org-element-type object)
 136     (link (equal (org-element-property :type object) "cite"))
 137     (latex-fragment
 138      (string-match "\\`\\\\cite{" (org-element-property :value object)))))
 139
 140 (defun org-bibtex-get-citation-key (citation)
 141   "Return key for a given citation, as a string.
 142 CITATION is a `latex-fragment' or `link' type object satisfying
 143 to `org-bibtex-citation-p' predicate."
 144   (if (eq (org-element-type citation) 'link)
 145       (org-element-property :path citation)
 146     (let ((value (org-element-property :value citation)))
 147       (and (string-match "\\`\\\\cite{" value)
 148            (substring value (match-end 0) -1)))))
 149
 150 \f
 151 ;;; Follow cite: links
 152
 153 (defun org-bibtex-file nil "Org-mode file of bibtex entries.")
 154
 155 (defun org-bibtex-goto-citation (&optional citation)
 156   "Visit a citation given its ID."
 157   (interactive)
 158   (let ((citation (or citation
 159                       (org-icompleting-read "Citation: "
 160                                             (obe-citations)))))
 161     (find-file (or org-bibtex-file
 162                    (error "`org-bibtex-file' has not been configured")))
 163     (goto-char (point-min))
 164     (when (re-search-forward (format "  :CUSTOM_ID: %s" citation) nil t)
 165       (outline-previous-visible-heading 1)
 166       t)))
 167
 168 (let ((jump-fn (car (org-remove-if-not #'fboundp '(ebib org-bibtex-goto-citation)))))
 169   (org-add-link-type "cite" jump-fn))
 170
 171
 172 \f
 173 ;;; Filters
 174
 175 (defun org-bibtex-process-bib-files (tree backend info)
 176   "Send each bibliography in parse tree to \"bibtex2html\" process.
 177 Return new parse tree."
 178   (when (org-export-derived-backend-p backend 'ascii 'html)
 179     ;; Initialize dynamically scoped variables.  The first one
 180     ;; contain an alist between keyword objects and their HTML
 181     ;; translation.  The second one will contain an alist between
 182     ;; citation keys and names in the output (according to style).
 183     (setq org-bibtex-html-entries-alist nil
 184           org-bibtex-html-keywords-alist nil)
 185     (org-element-map tree 'keyword
 186       (lambda (keyword)
 187         (when (equal (org-element-property :key keyword) "BIBLIOGRAPHY")
 188           (let ((arguments (org-bibtex-get-arguments keyword))
 189                 (file (org-bibtex-get-file keyword))
 190                 temp-file)
 191             ;; limit is set: collect citations throughout the document
 192             ;; in TEMP-FILE and pass it to "bibtex2html" as "-citefile"
 193             ;; argument.
 194             (when (plist-get arguments :limit)
 195               (let ((citations
 196                      (org-element-map tree '(latex-fragment link)
 197                        (lambda (object)
 198                          (and (org-bibtex-citation-p object)
 199                               (org-bibtex-get-citation-key object))))))
 200                 (with-temp-file (setq temp-file (make-temp-file "ox-bibtex"))
 201                   (insert (mapconcat 'identity citations "\n")))
 202                 (setq arguments
 203                       (plist-put arguments
 204                                  :options
 205                                  (append (plist-get arguments :options)
 206                                          (list "-citefile" temp-file))))))
 207             ;; Call "bibtex2html" on specified file.
 208             (unless (eq 0 (apply
 209                            'call-process
 210                            (append '("bibtex2html" nil nil nil)
 211                                    '("-a" "-nodoc" "-noheader" "-nofooter")
 212                                    (let ((style
 213                                           (org-not-nil
 214                                            (org-bibtex-get-style keyword))))
 215                                      (and style (list "--style" style)))
 216                                    (plist-get arguments :options)
 217                                    (list (concat file ".bib")))))
 218               (error "Executing bibtex2html failed"))
 219             (and temp-file (delete-file temp-file))
 220             ;; Open produced HTML file, and collect Bibtex key names
 221             (with-temp-buffer
 222               (insert-file-contents (concat file ".html"))
 223               ;; Update `org-bibtex-html-entries-alist'.
 224               (goto-char (point-min))
 225               (while (re-search-forward
 226                       "a name=\"\\([-_a-zA-Z0-9:]+\\)\">\\(\\w+\\)" nil t)
 227                 (push (cons (match-string 1) (match-string 2))
 228                       org-bibtex-html-entries-alist)))
 229             ;; Open produced HTML file, wrap references within a block and
 230             ;; return it.
 231             (with-temp-buffer
 232               (cond
 233                ((org-export-derived-backend-p backend 'html)
 234                 (insert (format "<div id=\"bibliography\">\n<h2>%s</h2>\n"
 235                                 (org-export-translate "References" :html info)))
 236                 (insert-file-contents (concat file ".html"))
 237                 (insert "\n</div>"))
 238                ((org-export-derived-backend-p backend 'ascii)
 239                 ;; convert HTML references to text w/pandoc
 240                 (unless (eq 0 (call-process "pandoc" nil nil nil
 241                                             (concat file ".html")
 242                                             "-o"
 243                                             (concat file ".txt")))
 244                   (error "Executing pandoc failed"))
 245                 (insert
 246                  (format
 247                   "%s\n==========\n\n"
 248                   (org-export-translate
 249                    "References"
 250                    (intern (format ":%s" (plist-get info :ascii-charset)))
 251                    info)))
 252                 (insert-file-contents (concat file ".txt"))
 253                 (goto-char (point-min))
 254                 (while (re-search-forward
 255                         "\\[ \\[bib\\][^ ]+ \\(\\]\\||[\n\r]\\)" nil t)
 256                   (replace-match ""))
 257                 (goto-char (point-min))
 258                 (while (re-search-forward "\\( \\]\\| \\]\\| |\\)" nil t)
 259                   (replace-match ""))
 260                 (goto-char (point-min))
 261                 (while (re-search-forward "[\n\r]\\([\n\r][\n\r]\\)" nil t)
 262                   (replace-match "\\1"))))
 263               ;; Update `org-bibtex-html-keywords-alist'.
 264               (push (cons keyword (buffer-string))
 265                     org-bibtex-html-keywords-alist)))))))
 266   ;; Return parse tree unchanged.
 267   tree)
 268
 269 (defun org-bibtex-merge-contiguous-citations (tree backend info)
 270   "Merge all contiguous citation in parse tree.
 271 As a side effect, this filter will also turn all \"cite\" links
 272 into \"\\cite{...}\" LaTeX fragments and will extract options.
 273 Cite options are placed into square brackets at the beginning of
 274 the \"\\cite\" command for the LaTeX backend, and are removed for
 275 the HTML and ASCII backends."
 276   (when (org-export-derived-backend-p backend 'html 'latex 'ascii)
 277     (org-element-map tree '(link latex-fragment)
 278       (lambda (object)
 279         (when (org-bibtex-citation-p object)
 280           (let ((new-citation (list 'latex-fragment
 281                                     (list :value ""
 282                                           :post-blank (org-element-property
 283                                                        :post-blank object))))
 284                 option)
 285             ;; Insert NEW-CITATION right before OBJECT.
 286             (org-element-insert-before new-citation object)
 287             ;; Remove all subsequent contiguous citations from parse
 288             ;; tree, keeping only their citation key.
 289             (let ((keys (list (org-bibtex-get-citation-key object)))
 290                   next)
 291               (while (and (setq next (org-export-get-next-element object info))
 292                           (or (and (stringp next)
 293                                    (not (org-string-match-p "\\S-" next)))
 294                               (org-bibtex-citation-p next)))
 295                 (unless (stringp next)
 296                   (push (org-bibtex-get-citation-key next) keys))
 297                 (org-element-extract-element object)
 298                 (setq object next))
 299               ;; Find any options in keys, e.g., "(Chapter 2)key" has
 300               ;; the option "Chapter 2".
 301               (setq keys
 302                     (mapcar
 303                      (lambda (k)
 304                        (if (string-match "^(\\([^)]\+\\))\\(.*\\)" k)
 305                            (progn
 306                              (when (org-export-derived-backend-p backend 'latex)
 307                                (setq option (format "[%s]" (match-string 1 k))))
 308                              (match-string 2 k))
 309                          k))
 310                      keys))
 311               (org-element-extract-element object)
 312               ;; Eventually merge all keys within NEW-CITATION.  Also
 313               ;; ensure NEW-CITATION has the same :post-blank property
 314               ;; as the last citation removed.
 315               (org-element-put-property
 316                new-citation
 317                :post-blank (org-element-property :post-blank object))
 318               (org-element-put-property
 319                new-citation
 320                :value (format "\\cite%s{%s}"
 321                               (or option "")
 322                               (mapconcat 'identity (nreverse keys) ",")))))))))
 323   tree)
 324
 325 (eval-after-load 'ox
 326   '(progn (add-to-list 'org-export-filter-parse-tree-functions
 327                        'org-bibtex-process-bib-files)
 328           (add-to-list 'org-export-filter-parse-tree-functions
 329                        'org-bibtex-merge-contiguous-citations)))
 330
 331
 332 \f
 333 ;;; LaTeX Part
 334
 335 (defadvice org-latex-keyword (around bibtex-keyword)
 336   "Translate \"BIBLIOGRAPHY\" keywords into LaTeX syntax.
 337 Fallback to `latex' back-end for other keywords."
 338   (let ((keyword (ad-get-arg 0)))
 339     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 340         ad-do-it
 341       (let ((file (org-bibtex-get-file keyword))
 342             (style (org-not-nil (org-bibtex-get-style keyword))))
 343         (setq ad-return-value
 344               (when file
 345                 (concat (and style (format "\\bibliographystyle{%s}\n" style))
 346                         (format "\\bibliography{%s}" file))))))))
 347
 348 (ad-activate 'org-latex-keyword)
 349
 350
 351 \f
 352 ;;; HTML Part
 353
 354 (defvar org-bibtex-html-entries-alist nil)  ; Dynamically scoped.
 355 (defvar org-bibtex-html-keywords-alist nil) ; Dynamically scoped.
 356
 357
 358 ;;;; Advices
 359
 360 (defadvice org-html-keyword (around bibtex-keyword)
 361   "Translate \"BIBLIOGRAPHY\" keywords into HTML syntax.
 362 Fallback to `html' back-end for other keywords."
 363   (let ((keyword (ad-get-arg 0)))
 364     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 365         ad-do-it
 366       (setq ad-return-value
 367             (cdr (assq keyword org-bibtex-html-keywords-alist))))))
 368
 369 (defadvice org-html-latex-fragment (around bibtex-citation)
 370   "Translate \"\\cite\" LaTeX fragments into HTML syntax.
 371 Fallback to `html' back-end for other keywords."
 372   (let ((fragment (ad-get-arg 0)))
 373     (if (not (org-bibtex-citation-p fragment)) ad-do-it
 374       (setq ad-return-value
 375             (format "[%s]"
 376                     (mapconcat
 377                      (lambda (key)
 378                        (format "<a href=\"#%s\">%s</a>"
 379                                key
 380                                (or (cdr (assoc key org-bibtex-html-entries-alist))
 381                                    key)))
 382                      (org-split-string
 383                       (org-bibtex-get-citation-key fragment) ",") ","))))))
 384
 385 (ad-activate 'org-html-keyword)
 386 (ad-activate 'org-html-latex-fragment)
 387
 388 \f
 389 ;;; Ascii Part
 390 (defadvice org-ascii-keyword (around bibtex-keyword)
 391   "Translate \"BIBLIOGRAPHY\" keywords into ascii syntax.
 392 Fallback to `ascii' back-end for other keywords."
 393   (let ((keyword (ad-get-arg 0)))
 394     (if (not (equal (org-element-property :key keyword) "BIBLIOGRAPHY"))
 395         ad-do-it
 396       (setq ad-return-value
 397             (cdr (assq keyword org-bibtex-html-keywords-alist))))))
 398
 399 (defadvice org-ascii-latex-fragment (around bibtex-citation)
 400   "Translate \"\\cite\" LaTeX fragments into ascii syntax.
 401 Fallback to `ascii' back-end for other keywords."
 402   (let ((fragment (ad-get-arg 0)))
 403     (if (not (org-bibtex-citation-p fragment)) ad-do-it
 404       (setq ad-return-value
 405             (format "[%s]"
 406                     (mapconcat
 407                      (lambda (key)
 408                        (or (cdr (assoc key org-bibtex-html-entries-alist))
 409                            key))
 410                      (org-split-string
 411                       (org-bibtex-get-citation-key fragment) ",") ","))))))
 412
 413 (ad-activate 'org-ascii-keyword)
 414 (ad-activate 'org-ascii-latex-fragment)
 415
 416 (provide 'ox-bibtex)
 417
 418 ;;; ox-bibtex.el ends here