;;; reftex-cite.el --- creating citations with RefTeX
-;; Copyright (C) 1997-2013 Free Software Foundation, Inc.
+;; Copyright (C) 1997-2014 Free Software Foundation, Inc.
;; Author: Carsten Dominik <dominik@science.uva.nl>
;; Maintainer: auctex-devel@gnu.org
;;; Code:
(eval-when-compile (require 'cl))
-(provide 'reftex-cite)
-(require 'reftex)
-;;;
-;; Variables and constants
+(require 'reftex)
-;; The history list of regular expressions used for citations
-(defvar reftex-cite-regexp-hist nil)
+;;; Variables and constants
+(defvar reftex-cite-regexp-hist nil
+ "The history list of regular expressions used for citations")
-;; Prompt and help string for citation selection
(defconst reftex-citation-prompt
- "Select: [n]ext [p]revious [r]estrict [ ]full_entry [q]uit RET [?]Help+more")
+ "Select: [n]ext [p]revious [r]estrict [ ]full_entry [q]uit RET [?]Help+more"
+ "Prompt and help string for citation selection")
(defconst reftex-citation-help
" n / p Go to next/previous entry (Cursor motion works as well).
e / E Create BibTeX file with all (marked/unmarked) entries
a / A Put all (marked) entries into one/many \\cite commands.")
-;; Find bibtex files
-
+;;; Find bibtex files
(defmacro reftex-with-special-syntax-for-bib (&rest body)
`(let ((saved-syntax (syntax-table)))
(unwind-protect
,@body)
(set-syntax-table saved-syntax))))
+;;;###autoload
(defun reftex-default-bibliography ()
- ;; Return the expanded value of `reftex-default-bibliography'.
- ;; The expanded value is cached.
+ "Return the expanded value of variable `reftex-default-bibliography'.
+The expanded value is cached."
(unless (eq (get 'reftex-default-bibliography :reftex-raw)
reftex-default-bibliography)
(put 'reftex-default-bibliography :reftex-expanded
reftex-default-bibliography))
(get 'reftex-default-bibliography :reftex-expanded))
+;;;###autoload
(defun reftex-bib-or-thebib ()
- ;; Tests if BibTeX or \begin{thebibliography} should be used for the
- ;; citation
- ;; Find the bof of the current file
+ "Test if BibTeX or \begin{thebibliography} should be used for the citation.
+Find the bof of the current file"
(let* ((docstruct (symbol-value reftex-docstruct-symbol))
(rest (or (member (list 'bof (buffer-file-name)) docstruct)
docstruct))
(if bib 'bib nil)
(if thebib 'thebib nil))))
+;;;###autoload
(defun reftex-get-bibfile-list ()
- ;; Return list of bibfiles for current document.
- ;; When using the chapterbib or bibunits package you should either
- ;; use the same database files everywhere, or separate parts using
- ;; different databases into different files (included into the mater file).
- ;; Then this function will return the applicable database files.
+ "Return list of bibfiles for current document.
+When using the chapterbib or bibunits package you should either
+use the same database files everywhere, or separate parts using
+different databases into different files (included into the mater file).
+Then this function will return the applicable database files."
;; Ensure access to scanning info
(reftex-access-scan-info)
(cdr (assq 'bib (symbol-value reftex-docstruct-symbol)))
(error "\\bibliography statement missing or .bib files not found")))
-;; Find a certain reference in any of the BibTeX files.
-
+;;; Find a certain reference in any of the BibTeX files.
+;;;###autoload
(defun reftex-pop-to-bibtex-entry (key file-list &optional mark-to-kill
highlight item return)
- ;; Find BibTeX KEY in any file in FILE-LIST in another window.
- ;; If MARK-TO-KILL is non-nil, mark new buffer to kill.
- ;; If HIGHLIGHT is non-nil, highlight the match.
- ;; If ITEM in non-nil, search for bibitem instead of database entry.
- ;; If RETURN is non-nil, just return the entry and restore point.
-
+ "Find BibTeX KEY in any file in FILE-LIST in another window.
+If MARK-TO-KILL is non-nil, mark new buffer to kill.
+If HIGHLIGHT is non-nil, highlight the match.
+If ITEM in non-nil, search for bibitem instead of database entry.
+If RETURN is non-nil, just return the entry and restore point."
(let* ((re
(if item
(concat "\\\\bibitem[ \t]*\\(\\[[^]]*\\]\\)?[ \t]*{"
(error "No \\bibitem with citation key %s" key)
(error "No BibTeX entry with citation key %s" key)))))
+;;;###autoload
(defun reftex-end-of-bib-entry (item)
(save-excursion
(condition-case nil
(progn (forward-list 1) (point)))
(error (min (point-max) (+ 300 (point)))))))
-;; Parse bibtex buffers
-
+;;; Parse bibtex buffers
(defun reftex-extract-bib-entries (buffers)
- ;; Extract bib entries which match regexps from BUFFERS.
- ;; BUFFERS is a list of buffers or file names.
- ;; Return list with entries."
+ "Extract bib entries which match regexps from BUFFERS.
+BUFFERS is a list of buffers or file names.
+Return list with entries."
(let* (re-list first-re rest-re
(buffer-list (if (listp buffers) buffers (list buffers)))
found-list entry buffer1 buffer alist
(t found-list))))
(defun reftex-bib-sort-author (e1 e2)
+ "Compare bib entries E1 and E2 by author.
+The name of the first different author/editor is used."
(let ((al1 (reftex-get-bib-names "author" e1))
(al2 (reftex-get-bib-names "author" e2)))
(while (and al1 al2 (string= (car al1) (car al2)))
(not (stringp (car al1))))))
(defun reftex-bib-sort-year (e1 e2)
+ "Compare bib entries E1 and E2 by year in ascending order."
(< (string-to-number (or (cdr (assoc "year" e1)) "0"))
(string-to-number (or (cdr (assoc "year" e2)) "0"))))
(defun reftex-bib-sort-year-reverse (e1 e2)
+ "Compare bib entries E1 and E2 by year in descending order."
(> (string-to-number (or (cdr (assoc "year" e1)) "0"))
(string-to-number (or (cdr (assoc "year" e2)) "0"))))
(defun reftex-get-crossref-alist (entry)
- ;; return the alist from a crossref entry
+ "Return the alist from a crossref ENTRY."
(let ((crkey (cdr (assoc "crossref" entry)))
start)
(save-excursion
;; Parse the bibliography environment
(defun reftex-extract-bib-entries-from-thebibliography (files)
- ;; Extract bib-entries from the \begin{thebibliography} environment.
- ;; Parsing is not as good as for the BibTeX database stuff.
- ;; The environment should be located in file FILE.
-
+ "Extract bib-entries from the \begin{thebibliography} environment.
+Parsing is not as good as for the BibTeX database stuff.
+The environment should be located in FILES."
(let* (start end buf entries re re-list file default)
(unless files
(error "Need file name to find thebibliography environment"))
entries))
(defun reftex-get-bibkey-default ()
- ;; Return the word before the cursor. If the cursor is in a
- ;; citation macro, return the word before the macro.
+ "Return the word before the cursor.
+If the cursor is in a citation macro, return the word before the macro."
(let* ((macro (reftex-what-macro 1)))
(save-excursion
(if (and macro (string-match "cite" (car macro)))
(skip-chars-backward "^a-zA-Z0-9")
(reftex-this-word))))
-;; Parse and format individual entries
-
+;;; Parse and format individual entries
(defun reftex-get-bib-names (field entry)
- ;; Return a list with the author or editor names in ENTRY
+ "Return a list with the author or editor names in ENTRY.
+If FIELD is empty try \"editor\" field."
(let ((names (reftex-get-bib-field field entry)))
(if (equal "" names)
(setq names (reftex-get-bib-field "editor" entry)))
(setq names (replace-match " " nil t names)))
(split-string names "\n")))
+;;;###autoload
(defun reftex-parse-bibtex-entry (entry &optional from to raw)
- ; if RAW is non-nil, keep double quotes/curly braces delimiting fields
+ "Parse BibTeX ENTRY.
+If ENTRY is nil then parse the entry in current buffer between FROM and TO.
+If RAW is non-nil, keep double quotes/curly braces delimiting fields."
(let (alist key start field)
(save-excursion
(save-restriction
;; remove extra whitespace
(while (string-match "[\n\t\r]\\|[ \t][ \t]+" field)
(setq field (replace-match " " nil t field)))
- ;; remove leading garbage
- (if (string-match (if raw "^[ \t]+" "^[ \t{]+") field)
- (setq field (replace-match "" nil t field)))
- ;; remove trailing garbage
- (if (string-match (if raw "[ \t]+$" "[ \t}]+$") field)
- (setq field (replace-match "" nil t field)))
(push (cons key field) alist))))
alist))
(defun reftex-get-bib-field (fieldname entry &optional format)
- ;; Extract the field FIELDNAME from an ENTRY
+ "Extract the field FIELDNAME from ENTRY.
+If FORMAT is non-nil `format' entry accordingly."
(let ((cell (assoc fieldname entry)))
(if cell
(if format
"")))
(defun reftex-format-bib-entry (entry)
- ;; Format a BibTeX ENTRY so that it is nice to look at
+ "Format a BibTeX ENTRY so that it is nice to look at."
(let*
((auth-list (reftex-get-bib-names "author" entry))
(authors (mapconcat 'identity auth-list ", "))
(concat key "\n " authors " " year " " extra "\n " title "\n\n")))
(defun reftex-parse-bibitem (item)
- ;; Parse a \bibitem entry
+ "Parse a \bibitem entry in ITEM."
(let ((key "") (text ""))
(when (string-match "\\`{\\([^}]+\\)}\\([^\000]*\\)" item)
(setq key (match-string 1 item)
(cons "&entry" (concat key " " text)))))
(defun reftex-format-bibitem (item)
- ;; Format a \bibitem entry so that it is (relatively) nice to look at.
+ "Format a \bibitem entry in ITEM so that it is (relatively) nice to look at."
(let ((text (reftex-get-bib-field "&text" item))
(key (reftex-get-bib-field "&key" item))
(lines nil))
(put-text-property 0 (length text) 'face reftex-bib-author-face text))
(concat key "\n " text "\n\n")))
-;; Make a citation
+;;; Make a citation
+;; NB this is a global autoload - see reftex.el.
;;;###autoload
(defun reftex-citation (&optional no-insert format-key)
"Make a citation using BibTeX database files.
Thus, `aaaa&&bbb' matches entries which contain both `aaaa' and `bbb'.
While entering the regexp, completion on knows citation keys is possible.
`=' is a good regular expression to match all entries in all files."
-
(interactive)
;; check for recursive edit
(reftex-kill-temporary-buffers)))
(defun reftex-do-citation (&optional arg no-insert format-key)
- ;; This really does the work of reftex-citation.
-
+ "This really does the work of `reftex-citation'."
(let* ((format (reftex-figure-out-cite-format arg no-insert format-key))
(docstruct-symbol reftex-docstruct-symbol)
(selected-entries (reftex-offer-bib-menu))
(mapcar 'car selected-entries)))
(defun reftex-figure-out-cite-format (arg &optional no-insert format-key)
- ;; Check if there is already a cite command at point and change cite format
- ;; in order to only add another reference in the same cite command.
+ "Check if there is already a cite command at point and change cite format
+in order to only add another reference in the same cite command."
(let ((macro (car (reftex-what-macro 1)))
(cite-format-value (reftex-get-cite-format))
key format)
(error "No citation format associated with key `%c'" key)))))
format))
+;;;###autoload
(defun reftex-citep ()
"Call `reftex-citation' with a format selector `?p'."
(interactive)
(reftex-citation nil ?p))
+;;;###autoload
(defun reftex-citet ()
"Call `reftex-citation' with a format selector `?t'."
(interactive)
(defvar reftex-select-bib-map)
(defun reftex-offer-bib-menu ()
- ;; Offer bib menu and return list of selected items
-
+ "Offer bib menu and return list of selected items."
(let ((bibtype (reftex-bib-or-thebib))
found-list rtn key data selected-entries)
(while
selected-entries))
(defun reftex-restrict-bib-matches (found-list)
- ;; Limit FOUND-LIST with more regular expressions
+ "Limit FOUND-LIST with more regular expressions."
(let ((re-list (split-string (read-string
"RegExp [ && RegExp...]: "
nil 'reftex-cite-regexp-hist)
found-list)))
(defun reftex-extract-bib-file (all &optional marked complement)
- ;; Limit FOUND-LIST with more regular expressions
+ "Limit FOUND-LIST with more regular expressions."
(let ((file (read-file-name "File to create: ")))
(find-file-other-window file)
(if (> (buffer-size) 0)
(goto-char (point-min))))
(defun reftex-insert-bib-matches (list)
- ;; Insert the bib matches and number them correctly
+ "Insert the bib matches and number them correctly."
(let ((mouse-face
(if (memq reftex-highlight-selection '(mouse both))
reftex-mouse-selected-face
last)))))
(defun reftex-format-citation (entry format)
- ;; Format a citation from the info in the BibTeX ENTRY
-
+ "Format a citation from the info in the BibTeX ENTRY according to FORMAT."
(unless (stringp format) (setq format "\\cite{%l}"))
(if (and reftex-comment-citations
(setq format (replace-match "" t t format)))
format)
+;;;###autoload
(defun reftex-make-cite-echo-string (entry docstruct-symbol)
- ;; Format a bibtex entry for the echo area and cache the result.
+ "Format a bibtex ENTRY for the echo area and cache the result."
(let* ((key (reftex-get-bib-field "&key" entry))
(string
(let* ((reftex-cite-punctuation '(" " " & " " etal.")))
string))
(defun reftex-bibtex-selection-callback (data ignore no-revisit)
- ;; Callback function to be called from the BibTeX selection, in
- ;; order to display context. This function is relatively slow and not
- ;; recommended for follow mode. It works OK for individual lookups.
+ "Callback function to be called from the BibTeX selection, in
+order to display context. This function is relatively slow and not
+recommended for follow mode. It works OK for individual lookups."
(let ((win (selected-window))
(key (reftex-get-bib-field "&key" data))
bibfile-list item bibtype)
(save-restriction
(widen)
(goto-char (point-min))
- (while (re-search-forward "\\(?:^\\|\\=\\)[^%\n\r]*?\\\\\\(bibentry\\|[a-zA-Z]*cite[a-zA-Z]*\\)\\(\\[[^\\]]*\\]\\)?{\\([^}]+\\)}" nil t)
+ (while (re-search-forward "\\(?:^\\|\\=\\)[^%\n\r]*?\\\\\\(bibentry\\|[a-zA-Z]*cite[a-zA-Z]*\\)\\(\\[[^]]*\\]\\)?{\\([^}]+\\)}" nil t)
(setq kk (match-string-no-properties 3))
(while (string-match "%.*\n?" kk)
(setq kk (replace-match "" t t kk)))
(string-match "^&" (car pair)))
alist))))
+;;;###autoload
(defun reftex-create-bibtex-file (bibfile)
- "Create a new BibTeX database file with all entries referenced in document.
+ "Create a new BibTeX database BIBFILE with all entries referenced in document.
The command prompts for a filename and writes the collected
entries to that file. Only entries referenced in the current
document with any \\cite-like macros are used. The sequence in
(message "%d entries extracted and copied to new database"
(length entries))))
-
+(provide 'reftex-cite)
;;; reftex-cite.el ends here
+
+;; Local Variables:
+;; generated-autoload-file: "reftex.el"
+;; End:
HCoop / bpt / emacs.git / blobdiff