lisp/org-bibtex.el

   1 ;;; org-bibtex.el --- Org links to BibTeX entries
   2 ;;
   3 ;; Copyright 2007, 2008 Free Software Foundation, Inc.
   4 ;;
   5 ;; Author: Bastien Guerry <bzg at altern dot org>
   6 ;;         Carsten Dominik <carsten dot dominik at gmail dot com>
   7 ;; Keywords: org, wp, remember
   8 ;; Version: 6.02b
   9 ;;
  10 ;; This file is part of GNU Emacs.
  11 ;;
  12 ;; GNU Emacs is free software; you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation; either version 3, or (at your option)
  15 ;; any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  24 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  25 ;; Boston, MA 02110-1301, USA.
  26 ;;
  27 ;;; Commentary:
  28 ;;
  29 ;; This file implements links to database entries in BibTeX files.
  30 ;; Instead of defining a special link prefix, it uses the normal file
  31 ;; links combined with a custom search mechanism to find entries
  32 ;; by reference key.  And it constucts a nice description tag for
  33 ;; the link that contains the author name, the year and a short title.
  34 ;;
  35 ;; It also stores detailed information about the entry so that
  36 ;; remember templates can access and enter this information easily.
  37 ;;
  38 ;; The available properties for each entry are listed here:
  39 ;;
  40 ;; :author        :publisher      :volume      :pages
  41 ;; :editor        :url            :number      :journal
  42 ;; :title         :year           :series      :address
  43 ;; :booktitle     :month          :annote      :abstract
  44 ;; :key           :btype
  45 ;;
  46 ;; Here is an example of a remember template that use some of this
  47 ;; information (:author :year :title :journal :pages):
  48 ;;
  49 ;; (setq org-remember-templates
  50 ;;   '((?b "* READ %?\n\n%a\n\n%:author (%:year): %:title\n   \
  51 ;;          In %:journal, %:pages.")))
  52 ;;
  53 ;; Let's say you want to remember this BibTeX entry:
  54 ;;
  55 ;; @Article{dolev83,
  56 ;;   author =    {Danny Dolev and Andrew C. Yao},
  57 ;;   title =     {On the security of public-key protocols},
  58 ;;   journal =   {IEEE Transaction on Information Theory},
  59 ;;   year =      1983,
  60 ;;   volume =    2,
  61 ;;   number =    29,
  62 ;;   pages =     {198--208},
  63 ;;   month =     {Mars}
  64 ;; }
  65 ;;
  66 ;; M-x `org-remember' on this entry will produce this buffer:
  67 ;;
  68 ;; =====================================================================
  69 ;; * READ <== [point here]
  70 ;;
  71 ;; [[file:/file.bib::dolev83][Dolev & Yao 1983: security of public key protocols]]
  72 ;;
  73 ;; Danny Dolev and Andrew C. Yao (1983): On the security of public-key protocols
  74 ;; In IEEE Transaction on Information Theory, 198--208.
  75 ;; =====================================================================
  76 ;;
  77 ;;; History:
  78 ;;
  79 ;; The link creation part has been part of Org-mode for a long time.
  80 ;;
  81 ;; Creating better remember template information was inspired by a request
  82 ;; of Austin Frank: http://article.gmane.org/gmane.emacs.orgmode/4112
  83 ;; and then imlemented by Bastien Guerry.
  84 ;;
  85 ;; Org-mode loads this module by default - if this is not what you want,
  86 ;; configure the variable `org-modules'.
  87
  88 ;;; Code:
  89
  90 (require 'org)
  91
  92 (defvar description nil) ; dynamically scoped from org.el
  93
  94 (declare-function bibtex-beginning-of-entry "bibtex" ())
  95 (declare-function bibtex-generate-autokey "bibtex" ())
  96 (declare-function bibtex-parse-entry "bibtex" (&optional content))
  97 (declare-function bibtex-url "bibtex" (&optional pos no-browse))
  98
  99 (org-add-link-type "bibtex" 'org-bibtex-open)
 100 (add-hook 'org-store-link-functions 'org-bibtex-store-link)
 101
 102 ;; (defun org-bibtex-publish (path)
 103 ;;   "Build the description of the BibTeX entry for publishing."
 104 ;;   (let* ((search (when (string-match "::\\(.+\\)\\'" path)
 105 ;;                 (match-string 1 path)))
 106 ;;       (path (substring path 0 (match-beginning 0)))
 107 ;;       key)
 108 ;;     (with-temp-buffer
 109 ;;       (org-open-file path t nil search)
 110 ;;       (setq key (org-create-file-search-functions)))
 111 ;;     (or description key)))
 112
 113 (defun org-bibtex-open (path)
 114   "Visit the bibliography entry on PATH."
 115   (let* ((search (when (string-match "::\\(.+\\)\\'" path)
 116                    (match-string 1 path)))
 117          (path (substring path 0 (match-beginning 0))))
 118     (org-open-file path t nil search)))
 119
 120 (defun org-bibtex-store-link ()
 121   "Store a link to a BibTeX entry."
 122   (when (eq major-mode 'bibtex-mode)
 123     (let* ((search (org-create-file-search-in-bibtex))
 124            (link (concat "file:" (abbreviate-file-name buffer-file-name)
 125                          "::" search))
 126            (entry (mapcar ; repair strings enclosed in "..." or {...}
 127                    (lambda(c)
 128                      (if (string-match
 129                           "^\\(?:{\\|\"\\)\\(.*\\)\\(?:}\\|\"\\)$" (cdr c))
 130                          (cons (car c) (match-string 1 (cdr c))) c))
 131                    (save-excursion
 132                      (bibtex-beginning-of-entry)
 133                      (bibtex-parse-entry)))))
 134       (org-store-link-props
 135        :key (cdr (assoc "=key=" entry))
 136        :author (or (cdr (assoc "author" entry)) "[no author]")
 137        :editor (or (cdr (assoc "editor" entry)) "[no editor]")
 138        :title (or (cdr (assoc "title" entry)) "[no title]")
 139        :booktitle (or (cdr (assoc "booktitle" entry)) "[no booktitle]")
 140        :journal (or (cdr (assoc "journal" entry)) "[no journal]")
 141        :publisher (or (cdr (assoc "publisher" entry)) "[no publisher]")
 142        :pages (or (cdr (assoc "pages" entry)) "[no pages]")
 143        :url (or (cdr (assoc "url" entry)) "[no url]")
 144        :year (or (cdr (assoc "year" entry)) "[no year]")
 145        :month (or (cdr (assoc "month" entry)) "[no month]")
 146        :address (or (cdr (assoc "address" entry)) "[no address]")
 147        :volume (or (cdr (assoc "volume" entry)) "[no volume]")
 148        :number (or (cdr (assoc "number" entry)) "[no number]")
 149        :annote (or (cdr (assoc "annote" entry)) "[no annotation]")
 150        :series (or (cdr (assoc "series" entry)) "[no series]")
 151        :abstract (or (cdr (assoc "abstract" entry)) "[no abstract]")
 152        :btype (or (cdr (assoc "=type=" entry)) "[no type]")
 153        :type "bibtex"
 154        :link link
 155        :description description))))
 156
 157 (defun org-create-file-search-in-bibtex ()
 158   "Create the search string and description for a BibTeX database entry."
 159   ;; Make a good description for this entry, using names, year and the title
 160   ;; Put it into the `description' variable which is dynamically scoped.
 161   (let ((bibtex-autokey-names 1)
 162         (bibtex-autokey-names-stretch 1)
 163         (bibtex-autokey-name-case-convert-function 'identity)
 164         (bibtex-autokey-name-separator " & ")
 165         (bibtex-autokey-additional-names " et al.")
 166         (bibtex-autokey-year-length 4)
 167         (bibtex-autokey-name-year-separator " ")
 168         (bibtex-autokey-titlewords 3)
 169         (bibtex-autokey-titleword-separator " ")
 170         (bibtex-autokey-titleword-case-convert-function 'identity)
 171         (bibtex-autokey-titleword-length 'infty)
 172         (bibtex-autokey-year-title-separator ": "))
 173     (setq description (bibtex-generate-autokey)))
 174   ;; Now parse the entry, get the key and return it.
 175   (save-excursion
 176     (bibtex-beginning-of-entry)
 177     (cdr (assoc "=key=" (bibtex-parse-entry)))))
 178
 179 (defun org-execute-file-search-in-bibtex (s)
 180   "Find the link search string S as a key for a database entry."
 181   (when (eq major-mode 'bibtex-mode)
 182     ;; Yes, we want to do the search in this file.
 183     ;; We construct a regexp that searches for "@entrytype{" followed by the key
 184     (goto-char (point-min))
 185     (and (re-search-forward (concat "@[a-zA-Z]+[ \t\n]*{[ \t\n]*"
 186                                     (regexp-quote s) "[ \t\n]*,") nil t)
 187          (goto-char (match-beginning 0)))
 188     (if (and (match-beginning 0) (equal current-prefix-arg '(16)))
 189         ;; Use double prefix to indicate that any web link should be browsed
 190         (let ((b (current-buffer)) (p (point)))
 191           ;; Restore the window configuration because we just use the web link
 192           (set-window-configuration org-window-config-before-follow-link)
 193           (save-excursion (set-buffer b) (goto-char p)
 194             (bibtex-url)))
 195       (recenter 0))  ; Move entry start to beginning of window
 196   ;; return t to indicate that the search is done.
 197     t))
 198
 199 ;; Finally add the link search function to the right hook.
 200 (add-hook 'org-execute-file-search-functions 'org-execute-file-search-in-bibtex)
 201
 202 (provide 'org-bibtex)
 203
 204 ;; arch-tag: 83987d5a-01b8-41c7-85bc-77700f1285f5
 205
 206 ;;; org-bibtex.el ends here