1 ;;; ox-bibtex.el --- Export bibtex fragments
3 ;; Copyright (C) 2009-2014 Taru Karttunen
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.
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.
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.
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.
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:
29 ;; http://www.lri.fr/~filliatr/bibtex2html/
31 ;; For ascii it uses the pandoc software from:
33 ;; http://johnmacfarlane.net/pandoc/
35 ;; It also introduces "cite" syntax for Org links.
37 ;; The usage is as follows:
39 ;; #+BIBLIOGRAPHY: bibfilename stylename optional-options
41 ;; e.g. given foo.bib and using style plain:
43 ;; #+BIBLIOGRAPHY: foo plain option:-d
45 ;; "stylename" can also be "nil", in which case no style will be used.
47 ;; Full filepaths are also possible:
49 ;; #+BIBLIOGRAPHY: /home/user/Literature/foo.bib plain option:-d
51 ;; Optional options are of the form:
53 ;; option:-foobar pass '-foobar' to bibtex2html
57 ;; option:-d sort by date
58 ;; option:-a sort as BibTeX (usually by author) *default*
59 ;; option:-u unsorted i.e. same order as in .bib file
60 ;; option:-r reverse the sort
62 ;; See the bibtex2html man page for more. Multiple options can be
65 ;; option:-d option:-r
67 ;; Limiting to only the entries cited in the document:
71 ;; For LaTeX export this simply inserts the lines
73 ;; \bibliographystyle{plain}
76 ;; into the TeX file when exporting.
78 ;; For HTML export it:
79 ;; 1) converts all \cite{foo} and [[cite:foo]] to links to the
81 ;; 2) creates a foo.html and foo_bib.html,
82 ;; 3) includes the contents of foo.html in the exported HTML file.
84 ;; For ascii export it:
85 ;; 1) converts all \cite{foo} and [[cite:foo]] to links to the
87 ;; 2) creates a foo.txt and foo_bib.html,
88 ;; 3) includes the contents of foo.txt in the exported ascii file.
90 ;; For LaTeX export it:
91 ;; 1) converts all [[cite:foo]] to \cite{foo}.
97 ;;; Internal Functions
99 (defun org-bibtex-get-file (keyword)
100 "Return bibliography file as a string.
101 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no file is found,
103 (let ((value (org-element-property :value keyword
)))
105 (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value
)
106 (match-string 1 value
))))
108 (defun org-bibtex-get-style (keyword)
109 "Return bibliography style as a string.
110 KEYWORD is a \"BIBLIOGRAPHY\" keyword. If no style is found,
112 (let ((value (org-element-property :value keyword
)))
114 (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value
)
115 (match-string 2 value
))))
117 (defun org-bibtex-get-arguments (keyword)
118 "Return \"bibtex2html\" arguments specified by the user.
119 KEYWORD is a \"BIBLIOGRAPHY\" keyword. Return value is a plist
120 containing `:options' and `:limit' properties. The former
121 contains a list of strings to be passed as options to
122 \"bibtex2html\" process. The latter contains a boolean."
123 (let ((value (org-element-property :value keyword
)))
125 (string-match "\\(\\S-+\\)[ \t]+\\(\\S-+\\)\\(.*\\)" value
)
127 (dolist (arg (org-split-string (match-string 3 value
))
129 (list :options
(nreverse options
) :limit limit
))
130 (let* ((s (split-string arg
":"))
133 (cond ((equal "limit" key
)
134 (setq limit
(not (equal "nil" value
))))
135 ((equal "option" key
) (push value options
)))))))))
137 (defun org-bibtex-citation-p (object)
138 "Non-nil when OBJECT is a citation."
139 (cl-case (org-element-type object
)
140 (link (equal (org-element-property :type object
) "cite"))
142 (string-match "\\`\\\\cite{" (org-element-property :value object
)))))
144 (defun org-bibtex-get-citation-key (citation)
145 "Return key for a given citation, as a string.
146 CITATION is a `latex-fragment' or `link' type object satisfying
147 to `org-bibtex-citation-p' predicate."
148 (if (eq (org-element-type citation
) 'link
)
149 (org-element-property :path citation
)
150 (let ((value (org-element-property :value citation
)))
151 (and (string-match "\\`\\\\cite{" value
)
152 (substring value
(match-end 0) -
1)))))
155 ;;; Follow cite: links
157 (defun org-bibtex-file nil
"Org-mode file of bibtex entries.")
159 (defun org-bibtex-goto-citation (&optional citation
)
160 "Visit a citation given its ID."
162 (let ((citation (or citation
(completing-read "Citation: " (obe-citations)))))
163 (find-file (or org-bibtex-file
164 (error "`org-bibtex-file' has not been configured")))
165 (goto-char (point-min))
166 (when (re-search-forward (format " :CUSTOM_ID: %s" citation
) nil t
)
167 (outline-previous-visible-heading 1)
170 (let ((jump-fn (car (cl-remove-if-not #'fboundp
'(ebib org-bibtex-goto-citation
)))))
171 (org-add-link-type "cite" jump-fn
))
177 (defun org-bibtex-process-bib-files (tree backend info
)
178 "Send each bibliography in parse tree to \"bibtex2html\" process.
179 Return new parse tree."
180 (when (org-export-derived-backend-p backend
'ascii
'html
)
181 ;; Initialize dynamically scoped variables. The first one
182 ;; contain an alist between keyword objects and their HTML
183 ;; translation. The second one will contain an alist between
184 ;; citation keys and names in the output (according to style).
185 (setq org-bibtex-html-entries-alist nil
186 org-bibtex-html-keywords-alist nil
)
187 (org-element-map tree
'keyword
189 (when (equal (org-element-property :key keyword
) "BIBLIOGRAPHY")
190 (let ((arguments (org-bibtex-get-arguments keyword
))
191 (file (org-bibtex-get-file keyword
))
194 ;; Test if filename is given with .bib-extension and strip
195 ;; it off. Filenames with another extensions will be
196 ;; untouched and will finally rise an error in bibtex2html.
197 (setq file
(if (equal (file-name-extension file
) "bib")
198 (file-name-sans-extension file
) file
))
199 ;; Outpufiles of bibtex2html will be put into current working directory
200 ;; so define a variable for this.
201 (setq out-file
(file-name-sans-extension
202 (file-name-nondirectory file
)))
203 ;; limit is set: collect citations throughout the document
204 ;; in TEMP-FILE and pass it to "bibtex2html" as "-citefile"
206 (when (plist-get arguments
:limit
)
208 (org-element-map tree
'(latex-fragment link
)
210 (and (org-bibtex-citation-p object
)
211 (org-bibtex-get-citation-key object
))))))
212 (with-temp-file (setq temp-file
(make-temp-file "ox-bibtex"))
213 (insert (mapconcat 'identity citations
"\n")))
217 (append (plist-get arguments
:options
)
218 (list "-citefile" temp-file
))))))
219 ;; Call "bibtex2html" on specified file.
222 (append '("bibtex2html" nil nil nil
)
223 '("-a" "-nodoc" "-noheader" "-nofooter")
226 (org-bibtex-get-style keyword
))))
227 (and style
(list "--style" style
)))
228 (plist-get arguments
:options
)
229 (list (concat file
".bib")))))
230 (error "Executing bibtex2html failed"))
231 (and temp-file
(delete-file temp-file
))
232 ;; Open produced HTML file, and collect Bibtex key names
234 (insert-file-contents (concat out-file
".html"))
235 ;; Update `org-bibtex-html-entries-alist'.
236 (goto-char (point-min))
237 (while (re-search-forward
238 "a name=\"\\([-_a-zA-Z0-9:]+\\)\">\\([^<]+\\)" nil t
)
239 (push (cons (match-string 1) (match-string 2))
240 org-bibtex-html-entries-alist
)))
241 ;; Open produced HTML file, wrap references within a block and
245 ((org-export-derived-backend-p backend
'html
)
246 (insert (format "<div id=\"bibliography\">\n<h2>%s</h2>\n"
247 (org-export-translate "References" :html info
)))
248 (insert-file-contents (concat out-file
".html"))
249 (goto-char (point-max))
251 ((org-export-derived-backend-p backend
'ascii
)
252 ;; convert HTML references to text w/pandoc
253 (unless (eq 0 (call-process "pandoc" nil nil nil
254 (concat out-file
".html")
256 (concat out-file
".txt")))
257 (error "Executing pandoc failed"))
261 (org-export-translate
263 (intern (format ":%s" (plist-get info
:ascii-charset
)))
265 (insert-file-contents (concat out-file
".txt"))
266 (goto-char (point-min))
267 (while (re-search-forward
268 "\\[ \\[bib\\][^ ]+ \\(\\]\\||[\n\r]\\)" nil t
)
270 (goto-char (point-min))
271 (while (re-search-forward "\\( \\]\\| \\]\\| |\\)" nil t
)
273 (goto-char (point-min))
274 (while (re-search-forward "[\n\r]\\([\n\r][\n\r]\\)" nil t
)
275 (replace-match "\\1"))))
276 ;; Update `org-bibtex-html-keywords-alist'.
277 (push (cons keyword
(buffer-string))
278 org-bibtex-html-keywords-alist
)))))))
279 ;; Return parse tree unchanged.
282 (defun org-bibtex-merge-contiguous-citations (tree backend info
)
283 "Merge all contiguous citation in parse tree.
284 As a side effect, this filter will also turn all \"cite\" links
285 into \"\\cite{...}\" LaTeX fragments and will extract options.
286 Cite options are placed into square brackets at the beginning of
287 the \"\\cite\" command for the LaTeX backend, and are removed for
288 the HTML and ASCII backends."
289 (when (org-export-derived-backend-p backend
'html
'latex
'ascii
)
290 (org-element-map tree
'(link latex-fragment
)
292 (when (org-bibtex-citation-p object
)
293 (let ((new-citation (list 'latex-fragment
295 :post-blank
(org-element-property
296 :post-blank object
))))
298 ;; Insert NEW-CITATION right before OBJECT.
299 (org-element-insert-before new-citation object
)
300 ;; Remove all subsequent contiguous citations from parse
301 ;; tree, keeping only their citation key.
302 (let ((keys (list (org-bibtex-get-citation-key object
)))
304 (while (and (setq next
(org-export-get-next-element object info
))
305 (or (and (stringp next
)
306 (not (string-match-p "\\S-" next
)))
307 (org-bibtex-citation-p next
)))
308 (unless (stringp next
)
309 (push (org-bibtex-get-citation-key next
) keys
))
310 (org-element-extract-element object
)
312 ;; Find any options in keys, e.g., "(Chapter 2)key" has
313 ;; the option "Chapter 2".
317 (if (string-match "^(\\([^)]\+\\))\\(.*\\)" k
)
319 (when (org-export-derived-backend-p backend
'latex
)
320 (setq option
(format "[%s]" (match-string 1 k
))))
324 (org-element-extract-element object
)
325 ;; Eventually merge all keys within NEW-CITATION. Also
326 ;; ensure NEW-CITATION has the same :post-blank property
327 ;; as the last citation removed.
328 (org-element-put-property
330 :post-blank
(org-element-property :post-blank object
))
331 (org-element-put-property
333 :value
(format "\\cite%s{%s}"
335 (mapconcat 'identity
(nreverse keys
) ",")))))))))
339 '(progn (add-to-list 'org-export-filter-parse-tree-functions
340 'org-bibtex-process-bib-files
)
341 (add-to-list 'org-export-filter-parse-tree-functions
342 'org-bibtex-merge-contiguous-citations
)))
348 (defadvice org-latex-keyword
(around bibtex-keyword
)
349 "Translate \"BIBLIOGRAPHY\" keywords into LaTeX syntax.
350 Fallback to `latex' back-end for other keywords."
351 (let ((keyword (ad-get-arg 0)))
352 (if (not (equal (org-element-property :key keyword
) "BIBLIOGRAPHY"))
354 (let ((file (org-bibtex-get-file keyword
))
355 (style (org-not-nil (org-bibtex-get-style keyword
))))
356 (setq ad-return-value
358 (concat (and style
(format "\\bibliographystyle{%s}\n" style
))
359 (format "\\bibliography{%s}" file
))))))))
361 (ad-activate 'org-latex-keyword
)
367 (defvar org-bibtex-html-entries-alist nil
) ; Dynamically scoped.
368 (defvar org-bibtex-html-keywords-alist nil
) ; Dynamically scoped.
373 (defadvice org-html-keyword
(around bibtex-keyword
)
374 "Translate \"BIBLIOGRAPHY\" keywords into HTML syntax.
375 Fallback to `html' back-end for other keywords."
376 (let ((keyword (ad-get-arg 0)))
377 (if (not (equal (org-element-property :key keyword
) "BIBLIOGRAPHY"))
379 (setq ad-return-value
380 (cdr (assq keyword org-bibtex-html-keywords-alist
))))))
382 (defadvice org-html-latex-fragment
(around bibtex-citation
)
383 "Translate \"\\cite\" LaTeX fragments into HTML syntax.
384 Fallback to `html' back-end for other keywords."
385 (let ((fragment (ad-get-arg 0)))
386 (if (not (org-bibtex-citation-p fragment
)) ad-do-it
387 (setq ad-return-value
391 (format "<a href=\"#%s\">%s</a>"
393 (or (cdr (assoc key org-bibtex-html-entries-alist
))
396 (org-bibtex-get-citation-key fragment
) ",") ","))))))
398 (ad-activate 'org-html-keyword
)
399 (ad-activate 'org-html-latex-fragment
)
403 (defadvice org-ascii-keyword
(around bibtex-keyword
)
404 "Translate \"BIBLIOGRAPHY\" keywords into ascii syntax.
405 Fallback to `ascii' back-end for other keywords."
406 (let ((keyword (ad-get-arg 0)))
407 (if (not (equal (org-element-property :key keyword
) "BIBLIOGRAPHY"))
409 (setq ad-return-value
410 (cdr (assq keyword org-bibtex-html-keywords-alist
))))))
412 (defadvice org-ascii-latex-fragment
(around bibtex-citation
)
413 "Translate \"\\cite\" LaTeX fragments into ascii syntax.
414 Fallback to `ascii' back-end for other keywords."
415 (let ((fragment (ad-get-arg 0)))
416 (if (not (org-bibtex-citation-p fragment
)) ad-do-it
417 (setq ad-return-value
421 (or (cdr (assoc key org-bibtex-html-entries-alist
))
424 (org-bibtex-get-citation-key fragment
) ",") ","))))))
426 (ad-activate 'org-ascii-keyword
)
427 (ad-activate 'org-ascii-latex-fragment
)
431 ;;; ox-bibtex.el ends here