;;; 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
(set-syntax-table saved-syntax))))
(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
(get 'reftex-default-bibliography :reftex-expanded))
(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 thebib 'thebib nil))))
(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.
(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]*{"
(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)))
(split-string names "\n")))
(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
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
;;;###autoload
(defun reftex-citation (&optional no-insert format-key)
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)
(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
format)
(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)
alist))))
(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
(reftex-access-scan-info '(16)))
(defun reftex-do-parse (rescan &optional file)
- "Do a document rescan. When allowed, do only a partial scan from FILE."
+ "Do a document rescan.
+When allowed, do only a partial scan from FILE."
;; Normalize the rescan argument
(setq rescan (cond ((eq rescan t) t)
(defvar index-tags)
(defun reftex-parse-from-file (file docstruct master-dir)
- ;; Scan the buffer for labels and save them in a list.
+ "Scan the buffer for labels and save them in a list."
(let ((regexp (reftex-everything-regexp))
(bound 0)
file-found tmp include-file
docstruct))
(defun reftex-locate-bibliography-files (master-dir &optional files)
- ;; Scan buffer for bibliography macro and return file list.
-
+ "Scan buffer for bibliography macro and return file list."
(unless files
(save-excursion
(goto-char (point-min))
(delq nil files)))
(defun reftex-replace-label-list-segment (old insert &optional entirely)
- ;; Replace the segment in OLD which corresponds to INSERT.
- ;; Works with side effects, directly changes old.
- ;; If entirely is t, just return INSERT.
- ;; This function also makes sure the old toc markers do not point anywhere.
+ "Replace the segment in OLD which corresponds to INSERT.
+Works with side effects, directly changes old.
+If ENTIRELY is t, just return INSERT.
+This function also makes sure the old toc markers do not point anywhere."
(cond
(entirely
new))))
(defun reftex-section-info (file)
- ;; Return a section entry for the current match.
- ;; Careful: This function expects the match-data to be still in place!
+ "Return a section entry for the current match.
+Careful: This function expects the match-data to be still in place!"
(let* ((marker (set-marker (make-marker) (1- (match-beginning 3))))
(macro (reftex-match-string 3))
(prefix (save-match-data
literal (marker-position marker))))
(defun reftex-ensure-index-support (&optional abort)
- ;; When index support is turned off, ask to turn it on and
- ;; set the current prefix argument so that `reftex-access-scan-info'
- ;; will rescan the entire document.
+ "When index support is turned off, ask to turn it on and
+set the current prefix argument so that `reftex-access-scan-info'
+will rescan the entire document."
(cond
(reftex-support-index t)
((y-or-n-p "Turn on index support and rescan entire document? ")
(defvar test-dummy)
(defun reftex-index-info (file)
- ;; Return an index entry for the current match.
- ;; Careful: This function expects the match-data to be still in place!
+ "Return an index entry for the current match.
+Careful: This function expects the match-data to be still in place!"
(catch 'exit
(let* ((macro (reftex-match-string 10))
(bom (match-beginning 10))
(list 'index index-tag context file bom arg key showkey sortkey key-end))))
(defun reftex-short-context (env parse &optional bound derive)
- ;; Get about one line of useful context for the label definition at point.
+ "Get about one line of useful context for the label definition at point."
(if (consp parse)
(setq parse (if derive (cdr parse) (car parse))))
"INVALID VALUE OF PARSE"))))
(defun reftex-where-am-I ()
- ;; Return the docstruct entry above point. Actually returns a cons
- ;; cell in which the cdr is a flag indicating if the information is
- ;; exact (t) or approximate (nil).
+ "Return the docstruct entry above point.
+Actually returns a cons cell in which the cdr is a flag indicating
+if the information is exact (t) or approximate (nil)."
(let ((docstruct (symbol-value reftex-docstruct-symbol))
(cnt 0) rtn rtn-if-no-other
)
(defsubst reftex-move-to-previous-arg (&optional bound)
- ;; Assuming that we are in front of a macro argument,
- ;; move backward to the closing parenthesis of the previous argument.
- ;; This function understands the splitting of macros over several lines
- ;; in TeX.
+ "Assuming that we are in front of a macro argument,
+move backward to the closing parenthesis of the previous argument.
+This function understands the splitting of macros over several lines
+in TeX."
(cond
;; Just to be quick:
((memq (preceding-char) '(?\] ?\})))
(t nil)))
(defun reftex-what-macro-safe (which &optional bound)
- ;; reftex-what-macro with special syntax table.
+ "Call `reftex-what-macro' with special syntax table."
(reftex-with-special-syntax
(reftex-what-macro which bound)))
(defun reftex-what-macro (which &optional bound)
- ;; Find out if point is within the arguments of any TeX-macro.
- ;; The return value is either ("\\macro" . (point)) or a list of them.
-
- ;; If WHICH is nil, immediately return nil.
- ;; If WHICH is 1, return innermost enclosing macro.
- ;; If WHICH is t, return list of all macros enclosing point.
- ;; If WHICH is a list of macros, look only for those macros and return the
- ;; name of the first macro in this list found to enclose point.
- ;; If the optional BOUND is an integer, bound backwards directed
- ;; searches to this point. If it is nil, limit to nearest \section -
- ;; like statement.
-
- ;; This function is pretty stable, but can be fooled if the text contains
- ;; things like \macro{aa}{bb} where \macro is defined to take only one
- ;; argument. As RefTeX cannot know this, the string "bb" would still be
- ;; considered an argument of macro \macro.
-
+ "Find out if point is within the arguments of any TeX-macro.
+The return value is either (\"\\macro\" . (point)) or a list of them.
+
+If WHICH is nil, immediately return nil.
+If WHICH is 1, return innermost enclosing macro.
+If WHICH is t, return list of all macros enclosing point.
+If WHICH is a list of macros, look only for those macros and return the
+ name of the first macro in this list found to enclose point.
+If the optional BOUND is an integer, bound backwards directed
+ searches to this point. If it is nil, limit to nearest \\section -
+ like statement.
+
+This function is pretty stable, but can be fooled if the text contains
+things like \\macro{aa}{bb} where \\macro is defined to take only one
+argument. As RefTeX cannot know this, the string \"bb\" would still be
+considered an argument of macro \\macro."
(unless reftex-section-regexp (reftex-compile-variables))
(catch 'exit
(if (null which) (throw 'exit nil))
(nreverse cmd-list)))))
(defun reftex-what-environment (which &optional bound)
- ;; Find out if point is inside a LaTeX environment.
- ;; The return value is (e.g.) either ("equation" . (point)) or a list of
- ;; them.
-
- ;; If WHICH is nil, immediately return nil.
- ;; If WHICH is 1, return innermost enclosing environment.
- ;; If WHICH is t, return list of all environments enclosing point.
- ;; If WHICH is a list of environments, look only for those environments and
- ;; return the name of the first environment in this list found to enclose
- ;; point.
-
- ;; If the optional BOUND is an integer, bound backwards directed searches to
- ;; this point. If it is nil, limit to nearest \section - like statement.
-
+ "Find out if point is inside a LaTeX environment.
+The return value is (e.g.) either (\"equation\" . (point)) or a list of
+them.
+
+If WHICH is nil, immediately return nil.
+If WHICH is 1, return innermost enclosing environment.
+If WHICH is t, return list of all environments enclosing point.
+If WHICH is a list of environments, look only for those environments and
+ return the name of the first environment in this list found to enclose
+ point.
+
+If the optional BOUND is an integer, bound backwards directed searches to
+this point. If it is nil, limit to nearest \\section - like statement."
(unless reftex-section-regexp (reftex-compile-variables))
(catch 'exit
(save-excursion
(nreverse env-list)))))
(defun reftex-what-special-env (which &optional bound)
- ;; Run the special environment parsers and return the matches.
- ;;
- ;; The return value is (e.g.) either ("my-parser-function" . (point))
- ;; or a list of them.
-
- ;; If WHICH is nil, immediately return nil.
- ;; If WHICH is 1, return innermost enclosing environment.
- ;; If WHICH is t, return list of all environments enclosing point.
- ;; If WHICH is a list of environments, look only for those environments and
- ;; return the name of the first environment in this list found to enclose
- ;; point.
+ "Run the special environment parsers and return the matches.
+
+The return value is (e.g.) either (\"my-parser-function\" . (point))
+or a list of them.
+If WHICH is nil, immediately return nil.
+If WHICH is 1, return innermost enclosing environment.
+If WHICH is t, return list of all environments enclosing point.
+If WHICH is a list of environments, look only for those environments and
+ return the name of the first environment in this list found to enclose
+ point."
(unless reftex-section-regexp (reftex-compile-variables))
(catch 'exit
(save-excursion
(car specials))))))
(defsubst reftex-move-to-next-arg (&optional ignore)
- ;; Assuming that we are at the end of a macro name or a macro argument,
- ;; move forward to the opening parenthesis of the next argument.
- ;; This function understands the splitting of macros over several lines
- ;; in TeX.
+ "Assuming that we are at the end of a macro name or a macro argument,
+move forward to the opening parenthesis of the next argument.
+This function understands the splitting of macros over several lines
+in TeX."
(cond
;; Just to be quick:
((memq (following-char) '(?\[ ?\{)))
(reftex-nth-arg (nth 5 entry) (nth 6 entry))))
(defun reftex-nth-arg (n &optional opt-args)
- ;; Return the nth following {} or [] parentheses content.
- ;; OPT-ARGS is a list of argument numbers which are optional.
+ "Return the Nth following {} or [] parentheses content.
+OPT-ARGS is a list of argument numbers which are optional."
;; If we are sitting at a macro start, skip to end of macro name.
(and (eq (following-char) ?\\) (skip-chars-forward "a-zA-Z*\\\\"))
(error nil)))
(defun reftex-context-substring (&optional to-end)
- ;; Return up to 150 chars from point
- ;; When point is just after a { or [, limit string to matching parenthesis
+ "Return up to 150 chars from point.
+When point is just after a { or [, limit string to matching parenthesis"
(cond
(to-end
;; Environment - find next \end
(defvar reftex-section-numbers (make-vector reftex-max-section-depth 0))
(defun reftex-init-section-numbers (&optional toc-entry appendix)
- ;; Initialize the section numbers with zeros or with what is found
- ;; in the toc entry.
+ "Initialize the section numbers with zeros or with what is found in the TOC-ENTRY."
(let* ((level (or (nth 5 toc-entry) -1))
(numbers (nreverse (split-string (or (nth 6 toc-entry) "") "\\.")))
(depth (1- (length reftex-section-numbers)))
(put 'reftex-section-numbers 'appendix appendix))
(defun reftex-section-number (&optional level star)
- ;; Return a string with the current section number.
- ;; When LEVEL is non-nil, increase section numbers on that level.
+ "Return a string with the current section number.
+When LEVEL is non-nil, increase section numbers on that level."
(let* ((depth (1- (length reftex-section-numbers))) idx n (string "")
(appendix (get 'reftex-section-numbers 'appendix))
(partspecial (and (not reftex-part-resets-chapter)
string))))
(defun reftex-roman-number (n)
- ;; Return as a string the roman number equal to N.
+ "Return as a string the roman number equal to N."
(let ((nrest n)
(string "")
(list '((1000 . "M") ( 900 . "CM") ( 500 . "D") ( 400 . "CD")
projects / emacs.git / commitdiff