1. xemacs
  2. reftex

Commits

steveb  committed c3988ad

reftex.el-3.43

  • Participants
  • Parent commits 830deae
  • Branches default

Comments (0)

Files changed (4)

File ChangeLog

View file
  • Ignore whitespace
+1999-03-01  SL Baur  <steve@xemacs.org>
+
+	* reftex.el-3.43.
+
 1998-08-11  SL Baur  <steve@altair.xemacs.org>
 
 	* reftex.el-3.34.

File Makefile

View file
  • Ignore whitespace
 # the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 # Boston, MA 02111-1307, USA.
 
-VERSION = 1.11
-AUTHOR_VERSION = 3.42
+VERSION = 1.12
+AUTHOR_VERSION = 3.43
 MAINTAINER = Carsten Dominik <dominik@strw.LeidenUniv.nl>
 PACKAGE = reftex
 PKG_TYPE = regular

File reftex.el

View file
  • Ignore whitespace
 ;;; reftex.el --- Minor mode for doing \label, \ref and \cite in LaTeX
 ;; Copyright (c) 1997, 1998 Free Software Foundation, Inc.
 
-;; Version:    3.42 
+;; Version:    3.43 
 ;; Author:     Carsten Dominik <dominik@strw.LeidenUniv.nl>
 ;; Keywords:   tex
 
 ;;
 ;; RefTeX in a Nutshell
 ;; ====================
-;;
+;; 
 ;;   1. Table of Contents
 ;;      Typing `C-c =' (`reftex-toc') will show a table of contents of the
 ;;      document.  From that buffer, you can jump quickly to every part of
 ;;      your document.  Press `?' to get help.
-;;
+;; 
 ;;   2. Labels and References
 ;;      RefTeX distinguishes labels for different environments.  It knows
 ;;      about all standard environments (and many others), and can be
 ;;      configured to recognize any additional labeled environments you
-;;      have defined yourself (variable REFTEX-LABEL-ALIST).
+;;      have defined yourself (variable `reftex-label-alist').
 ;;
-;;      * Creating Labels
+;;      Creating Labels
 ;;      Type `C-c (' (`reftex-label') to insert a label at point.  RefTeX
 ;;      will either
 ;;         - derive a label from context (default for section labels)
 ;;         - prompt for a label string (default for figures and tables) or
 ;;         - insert a simple label made of a prefix and a number (all other
 ;;           environments)
+;;      This is configurable with the variable `reftex-insert-label-flags'.
 ;;
-;;      Which labels are created how is configurable with the variable
-;;      REFTEX-INSERT-LABEL-FLAGS.
-;;
-;;      * Referencing Labels
+;;      Referencing Labels
 ;;      To make a reference, type `C-c )' (`reftex-reference').  This
 ;;      shows an outline of the document with all labels of a certain type
 ;;      (figure, equation,...) and some label context.  Selecting a label
 ;;      specified in the `\bibliography' command) and pull out a list of
 ;;      matches for you to choose from.  The list is *formatted* and
 ;;      sorted.  The selected article is referenced as `\cite{KEY}' (see
-;;      also the variable REFTEX-CITE-FORMAT).
+;;      variable `reftex-cite-format').
 ;;
-;;   4. Viewing Cross References
-;;      When point is idle on the argument of a `\ref' or `\cite' macro,
-;;      the echo area will (if it is empty) display information about the
-;;      citation/cross reference.  Press `C-c &' (`reftex-view-crossref'),
-;;      or click with `S-mouse-2' on the macro argument to display the
-;;      corresponding label definition or BibTeX database entry in another
-;;      window.
+;;   4. Viewing Cross-References
+;;      When point is on the KEY argument of a cross-referencing macro
+;;      (`\label', `\ref', `\cite', `\bibitem', `\index', and variations)
+;;      or inside a BibTeX database entry, you can press `C-c &'
+;;      (`reftex-view-crossref') to display corresponding locations in the
+;;      document and associated BibTeX database files.
+;;      When the enclosing macro is `\cite' or `\ref' and no other message
+;;      occupies the echo area, information about the citation or label
+;;      will automatically be displayed.
 ;;
 ;;   5. Multifile Documents
-;;      Multifile Documents are fully supported. RefTeX provides cross
-;;      referencing information from all files which are part of the
-;;      document, and across document borders (`xr.sty').
+;;      Multifile Documents are fully supported. RefTeX provides
+;;      cross-referencing information from all parts of the document, and
+;;      across document borders (`xr.sty').
 ;;
 ;;   6. Document Parsing
 ;;      RefTeX needs to parse the document in order to find labels and
           ,@(mapcar
              (function
               (lambda (x)
-                (list 'const ':tag (concat (symbol-name (nth 0 x))
+                (list 'const :tag (concat (symbol-name (nth 0 x))
                                            ": " (nth 1 x))
                       (nth 0 x))))
              reftex-label-alist-builtin)))
       ,@(mapcar
          (function
           (lambda (x)
-            (list 'const ':tag (concat (symbol-name (nth 0 x)))
+            (list 'const :tag (concat (symbol-name (nth 0 x)))
                   (nth 0 x))))
          reftex-label-alist-builtin)))))
 
 ;; LaTeX section commands and level numbers
 (defcustom reftex-section-levels
   '(
-    ("part"            . 0)
-    ("chapter"         . 1)
-    ("section"         . 2)
-    ("subsection"      . 3)
-    ("subsubsection"   . 4)
-    ("paragraph"       . 5)
-    ("subparagraph"    . 6)
-    ("subsubparagraph" . 7)
+    ("part"            .  0)
+    ("chapter"         .  1)
+    ("section"         .  2)
+    ("subsection"      .  3)
+    ("subsubsection"   .  4)
+    ("paragraph"       .  5)
+    ("subparagraph"    .  6)
+    ("subsubparagraph" .  7)
+    ("addchap"         . -1) ; KOMA-Script
+    ("addsec"          . -2) ; KOMA-Script
+;;; ("minisec"         . -7) ; KOMA-Script
     )
   "Commands and levels used for defining sections in the document.
 The car of each cons cell is the name of the section macro.  The cdr is a
-number indicating its level."
+number indicating its level.  A negative level means the same as the
+positive value, but the section will never get a number."
   :group 'reftex-defining-label-environments
   :set 'reftex-set-dirty
   :type '(repeat
   "*List of BibTeX database files which should be used if none are specified.
 When `reftex-citation' is called from a document which has neither a
 `\bibliography{..}' statement nor a `thebibliography' environment,
-RefTeX will scan these files instead.  Intended for using
-`reftex-citation' in non-LaTeX files."
+RefTeX will scan these files instead.  Intended for using `reftex-citation'
+in non-LaTeX files.  The files will be searched along the BIBINPUTS or TEXBIB
+path."
   :group 'reftex-citation-support
   :type '(repeat (file)))
 
            ,@(mapcar
               (function
                (lambda (x)
-                 (list 'const ':tag (concat (symbol-name (nth 0 x))
+                 (list 'const :tag (concat (symbol-name (nth 0 x))
                                             ": " (nth 1 x))
                        (nth 0 x))))
               reftex-cite-format-builtin))
   :group 'reftex-citation-support
   :type 'hook)
 
-
 ;; Viewing Cross References and Citations
 (defgroup reftex-viewing-cross-references-and-citations nil
   "Displaying cross references and citations."
   :group 'reftex)
 
+(defcustom reftex-view-crossref-extra
+  '(("index\\|idx" "\\\\[a-zA-Z]*\\(index\\|idx\\)[a-zA-Z]*\\*?\\(\\[[^]]*\\]\\|{[^}]*}\\)*{\\(%s\\)}" 3))
+  "Macros which can be used for the display of cross references.
+This is used when `reftex-view-crossref' is called with point in an
+argument of a macro.  Note that crossref viewing for citations and
+references (both ways) is hard-coded.  This variable is only to
+configure additional structures for which crossreference viewing
+can be useful.  Each entry has the structure 
+
+(MACRO-RE SEARCH-RE HIGHLIGHT).
+
+MACRO-RE is matched against the macro.  SEARCH-RE is the regexp used
+to search for cross references.  `%s' in this regexp is replaced with
+with the macro argument at point.  HIGHLIGHT is an integer indicating
+which subgroup of the match should be highlighted."
+  :group 'reftex-viewing-cross-references-and-citations
+  :type '(repeat (group (regexp  :tag "Macro  Regexp  ")
+			(string  :tag "Search Regexp  ")
+			(integer :tag "Highlight Group"))))
+
 (defcustom reftex-auto-view-crossref t
   "*Non-nil means, initially turn automatic viewing of crossref info on.
 Automatic viewing of crossref info normally uses the echo area.
 ;;; Define the formal stuff for a minor mode named RefTeX.
 ;;;
 
-(defconst reftex-version "RefTeX version 3.42"
+(defconst reftex-version "RefTeX version 3.43"
   "Version string for RefTeX.")
 
 (defvar reftex-mode nil
 (if (fboundp 'add-minor-mode)
     ;; Use it so that we get the extras
     (progn
-      (put 'reftex-mode ':included '(memq major-mode '(latex-mode tex-mode)))
-      (put 'reftex-mode ':menu-tag "RefTeX Mode")
+      (put 'reftex-mode :included '(memq major-mode '(latex-mode tex-mode)))
+      (put 'reftex-mode :menu-tag "RefTeX Mode")
       (add-minor-mode 'reftex-mode " Ref" reftex-mode-map))
   ;; The standard way
   (unless (assoc 'reftex-mode minor-mode-alist)
             symlist (cdr symlist)
             symname (symbol-name symbol))
       (set symbol (intern (concat symname "-" (int-to-string index))))
-      (put (symbol-value symbol) ':master-index index)
+      (put (symbol-value symbol) :master-index index)
       ;; Initialize if new symbols.
       (if newflag (set (symbol-value symbol) nil)))
 
 (defvar reftex-section-regexp nil)
 (defvar reftex-section-or-include-regexp nil)
 (defvar reftex-everything-regexp nil)
+(defvar reftex-find-citation-regexp-format
+  "\\\\[a-zA-Z]*cite[*a-zA-Z]*\\*?\\(\\[[^]]*\\]\\|{[^}]*}\\)*{\\([^}]*,\\)?\\(%s\\)[},]")
+(defvar reftex-find-reference-format
+  "\\\\\\(ref[a-zA-Z]*\\|[a-zA-Z]*ref\\)\\*?\\(\\[[^]]*\\]\\|{[^}]*}\\)*{\\(%s\\)}")
+(defvar reftex-macros-with-labels nil)
 (defvar reftex-find-label-regexp-format nil)
 (defvar reftex-find-label-regexp-format2 nil)
 
     ;; Return the list
     docstruct))
 
-(defun reftex-locate-bibliography-files (master-dir)
+(defun reftex-locate-bibliography-files (master-dir &optional files)
   ;; Scan buffer for bibliography macro and return file list.
-  (let (files)
+  
+  (unless files
     (save-excursion
       (goto-char (point-min))
-      (when (re-search-forward
-	     "\\(\\`\\|[\n\r]\\)[ \t]*\\\\bibliography{[ \t]*\\([^}]+\\)" nil t)
-	(setq files (split-string (reftex-match-string 2)
-				      "[ \t\n\r]*,[ \t\n\r]*"))
-	(setq files 
-	      (mapcar
-	       (lambda (x)
-		 (if (or (member x reftex-bibfile-ignore-list)
-			 (delq nil (mapcar (lambda (re) (string-match re x))
-					   reftex-bibfile-ignore-regexps)))
-		     ;; excluded file
-		     nil
-		   ;; find the file
-		   (reftex-locate-file x "bib" master-dir)))
-	       files))
-	(delq nil files)))))
+      (if (re-search-forward
+	   "\\(\\`\\|[\n\r]\\)[ \t]*\\\\bibliography{[ \t]*\\([^}]+\\)" nil t)
+	  (setq files 
+		(split-string (reftex-match-string 2)
+			      "[ \t\n\r]*,[ \t\n\r]*")))))
+  (when files
+    (setq files 
+	  (mapcar
+	   (lambda (x)
+	     (if (or (member x reftex-bibfile-ignore-list)
+		     (delq nil (mapcar (lambda (re) (string-match re x))
+				       reftex-bibfile-ignore-regexps)))
+		 ;; excluded file
+		 nil
+	       ;; find the file
+	       (reftex-locate-file x "bib" master-dir)))
+	   files))
+    (delq nil files)))
+
+(defun reftex-default-bibliography ()
+  ;; Return the expanded value of `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-locate-bibliography-files 
+	  default-directory reftex-default-bibliography))
+    (put 'reftex-default-bibliography :reftex-raw
+	 reftex-default-bibliography))
+  (get 'reftex-default-bibliography :reftex-expanded))
 
 (defun reftex-replace-label-list-segment (old insert &optional entirely)
   ;; Replace the segment in OLD which corresponds to INSERT.
       (if (file-exists-p file)
           ;; load the file and return t for success
 	  (condition-case nil
-	      (progn (load-file file) t)
-	    (error (message "Error while loading file %s" file)
+	      (progn
+		(load-file file)
+		(reftex-check-parse-consistency)
+		t)
+	    (error (message "Error while restoring file %s" file)
 		   (set reftex-docstruct-symbol nil)
 		   nil))
         ;; return nil for failure, but no exception
           (error "Cannot write to file %s" file)))
       t))))
 
+(defun reftex-check-parse-consistency ()
+  ;; Check if parse file is consistent, throw an error if not.
+
+  ;; Check if the master is the same: when moving a document, this will see it.
+  (let* ((real-master (reftex-TeX-master-file))
+	 (parsed-master 
+	  (nth 1 (assq 'bof (symbol-value reftex-docstruct-symbol)))))
+    (unless (string= (file-truename real-master) (file-truename parsed-master))
+      (message "Master file name in load file is different: %s versus %s"
+	       parsed-master real-master)
+      (error "Master file name error")))
+
+  ;; Check for the existence of all document files
+;;;  (let* ((all (symbol-value reftex-docstruct-symbol)))
+;;;    (while all
+;;;      (when (and (eq (car (car all)) 'bof)
+;;;		 (not (file-regular-p (nth 1 (car all)))))
+;;;	(message "File %s in saved parse info not avalable" (cdr (car all)))
+;;;	(error "File not found"))
+;;;      (setq all (cdr all))))
+  )
+
 (defun reftex-kill-buffer-hook ()
   "Save RefTeX's parse file for this buffer if the information has changed."
   ;; Save the parsing information if it was modified.
   ;; Carefull: 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))
+         (level (cdr (assoc macro reftex-section-levels-all)))
          (star (= ?* (char-after (match-end 3))))
-         (level (cdr (assoc macro reftex-section-levels-all)))
-         (section-number (reftex-section-number level star))
+	 (unnumbered (or star (< level 0)))
+	 (level (abs level))
+         (section-number (reftex-section-number level unnumbered))
          (text1 (save-match-data (save-excursion (reftex-context-substring))))
          (literal (buffer-substring-no-properties
                    (1- (match-beginning 3))
 (defun reftex-make-selection-buffer-name (type &optional index)
   ;; Make unique name for a selection buffer.
   (format " *RefTeX[%s][%d]*"
-	  type (or index (get reftex-docstruct-symbol ':master-index) 0)))
+	  type (or index (get reftex-docstruct-symbol :master-index) 0)))
 
 (defun reftex-get-offset (buf here-am-I &optional typekey toc file)
   ;; Find the correct offset data, like insert-docstruct would, but faster.
 	    (if mouse-face
 		(put-text-property from (1- to)
 				   'mouse-face mouse-face))
-	    (put-text-property from to ':data cell))))
+	    (put-text-property from to :data cell))))
 
        ((eq (car cell) 'toc)
         ;; a table of contents entry
 	    (if mouse-face
 		(put-text-property from (1- to)
 				   'mouse-face mouse-face))
-	    (put-text-property from to ':data cell))
+	    (put-text-property from to :data cell))
 	  (goto-char to)))
 
        ((stringp (car cell))
           (when context
             (insert context-indent text "\n")
             (setq to (point)))
-          (put-text-property from to ':data cell)
+          (put-text-property from to :data cell)
 	  (when mouse-face
 	    (put-text-property from (1- to)
 			       'mouse-face mouse-face))	  
 
 (defun reftex-find-start-point (fallback &rest locations)
   ;; Set point to the first available LOCATION.  When a LOCATION is a list,
-  ;; search for such a ':data text property.  When it is an integer,
+  ;; search for such a :data text property.  When it is an integer,
   ;; use is as line number.  FALLBACK is a buffer position used if everything
   ;; else  fails.
   (catch 'exit
 	(cond
 	 ((null loc))
 	 ((listp loc)
-	  (setq pos (text-property-any (point-min) (point-max) ':data loc))
+	  (setq pos (text-property-any (point-min) (point-max) :data loc))
 	  (when pos
 	    (goto-char pos) 
 	    (throw 'exit t)))
 
 (defun reftex-show-entry (beg-hlt end-hlt)
   ;; Show entry if point is hidden
-  (let* ((n (/ (window-height) 2))
+  (let* ((n (/ (reftex-window-height) 2))
          (beg (save-excursion
                (re-search-backward "[\n\r]" nil 1 n) (point)))
          (end (save-excursion
 	 (xr-data (assq 'xr (symbol-value reftex-docstruct-symbol)))
 	 (xr-alist (cons (cons "" (buffer-file-name)) (nth 1 xr-data)))
 	 (here-I-am (if rebuild 
-			(get 'reftex-toc ':reftex-data)
+			(get 'reftex-toc :reftex-data)
 		      (car (reftex-where-am-I))))
 	 offset)
 
 		(reftex-last-assoc-before-elt 
 		 'toc here-I-am
 		 (symbol-value reftex-docstruct-symbol))))
-      (put 'reftex-toc ':reftex-line 3)
+      (put 'reftex-toc :reftex-line 3)
       (goto-line 3)
       (beginning-of-line)))
 
     ;; Find the correct starting point
-    (reftex-find-start-point (point) offset (get 'reftex-toc ':reftex-line))
+    (reftex-find-start-point (point) offset (get 'reftex-toc :reftex-line))
     (setq reftex-last-follow-point (point))))
 
 (defun reftex-toc-pre-command-hook ()
 
 (defun reftex-toc-post-command-hook ()
   ;; used in the post-command-hook for the *toc* buffer
-  (when (get-text-property (point) ':data)
-    (put 'reftex-toc ':reftex-data (get-text-property (point) ':data))
+  (when (get-text-property (point) :data)
+    (put 'reftex-toc :reftex-data (get-text-property (point) :data))
     (and (> (point) 1)
 	 (not (get-text-property (point) 'intangible))
 	 (memq reftex-highlight-selection '(cursor both))
 	 (reftex-highlight 1
-	   (or (previous-single-property-change (1+ (point)) ':data)
+	   (or (previous-single-property-change (1+ (point)) :data)
 	       (point-min))
-	   (or (next-single-property-change (point) ':data)
+	   (or (next-single-property-change (point) :data)
 	       (point-max)))))
   (if (integerp reftex-toc-follow-mode)
       ;; remove delayed action
   (interactive "p")
   (setq reftex-callback-fwd t)
   (or (eobp) (forward-char 1))
-  (goto-char (or (next-single-property-change (point) ':data) 
+  (goto-char (or (next-single-property-change (point) :data) 
 		 (point))))
 (defun reftex-toc-previous (&optional arg)
   "Move to previous selectable item."
   (interactive "p")
   (setq reftex-callback-fwd nil)
-  (goto-char (or (previous-single-property-change (point) ':data)
+  (goto-char (or (previous-single-property-change (point) :data)
 		 (point))))
 (defun reftex-toc-toggle-follow ()
   "Toggle follow (other window follows with context)."
   "Regenerate the *toc* buffer by reparsing file of section at point."
   (interactive)
   (if reftex-enable-partial-scans
-      (let* ((data (get-text-property (point) ':data))
+      (let* ((data (get-text-property (point) :data))
 	     (what (car data))
 	     (file (cond ((eq what 'toc) (nth 3 data))
 			  ((memq what '(eof bof file-error)) (nth 1 data))
 	     (line (+ (count-lines (point-min) (point)) (if (bolp) 1 0))))
         (if (not file)
             (error "Don't know which file to rescan.  Try `R'")
-	  (put 'reftex-toc ':reftex-line line)
+	  (put 'reftex-toc :reftex-line line)
           (switch-to-buffer-other-window
            (reftex-get-file-buffer-force file))
           (setq current-prefix-arg '(4))
   ;; even if the buffer is not live, or things like outline, x-symbol etc.
   ;; have been active.
 
-  (let* ((toc (get-text-property (point) ':data))
+  (let* ((toc (get-text-property (point) :data))
          (toc-window (selected-window))
          show-window show-buffer match)
 
                            (symbol-value reftex-docstruct-symbol))))
    ;; Anywhere in the entire document
    (cdr (assq 'bib (symbol-value reftex-docstruct-symbol)))
-   (error "\\bibliography statement missing or .bib files not found.")))
+   (error "\\bibliography statement missing or .bib files not found")))
 
 ;; Find a certain reference in any of the BibTeX files.
 
 
     (setq first-re (car re-list)    ; We'll use the first re to find things,
           rest-re  (cdr re-list))   ; the others to narrow down.
-    (if (string-match "\\`[ \t]*\\'" first-re)
+    (if (string-match "\\`[ \t]*\\'" (or first-re ""))
         (error "Empty regular expression"))
 
     (save-excursion
             (setq buffer1 (reftex-get-file-buffer-force
                            buffer (not reftex-keep-temporary-buffers))))
           (if (not buffer1)
-              (error "Cannot find BibTeX file %s" buffer)
+              (message "No such BibTeX file %s (ignored)" buffer)
             (message "Scanning bibliography database %s" buffer1))
 
           (set-buffer buffer1)
 bibtex entries (taken from the \\bibliography command) and offers the
 matching entries for selection.  The selected entry is formated according
 to `reftex-cite-format' and inserted into the buffer.
+
 If NO-INSERT is non-nil, nothing is inserted, only the selected key returned.
+
+When called with one or two `C-u' prefixes, first rescans the document.
+When called with a numeric prefix, make that many citations.  When
+called with point inside the braces of a `\cite' command, it will
+add another key, ignoring the value of `reftex-cite-format'.
+
 The regular expression uses an expanded syntax: && is interpreted as `and'.
 Thus, `aaaa&&bbb' matches entries which contain both `aaaa' and `bbb'.
 While entering the regexp, completion on knows citation keys is possible.
-When this function is called with point inside the braces of a \\cite
-command, it will add another key, ignoring the value of `reftex-cite-format'.
-When called with a numeric prefix, that many citations will be made and all
-put into the same \\cite command.
-When called with just or two C-u as prefix, enforces rescan of buffer for
-bibliography statement (e.g. if it was changed)."
+`=' is a good regular expression to match all entries in all files."
 
   (interactive)
 
   ;; Offer bib menu and return list of selected items
 
   (let (found-list rtn key data selected-entries)
-
     (while 
 	(not 
 	 (catch 'done
 		 (cdr (assq 'thebib (symbol-value reftex-docstruct-symbol)))))
 	       (reftex-default-bibliography
 		(message "Using default bibliography")
-		(reftex-extract-bib-entries reftex-default-bibliography))
+		(reftex-extract-bib-entries (reftex-default-bibliography)))
 	       (t (error "No valid bibliography in this document, and no default available"))))
 	   
 	   (unless found-list
 		(reftex-insert-bib-matches found-list)))
 	    (setq buffer-read-only t)
 	    (if (= 0 (buffer-size))
-		(error "Sorry, no matches found"))
+		(error "No matches found"))
 	    (setq truncate-lines t)
 	    (goto-char 1)
 	    (while t
       (lambda (x)
 	(setq tmp (cdr (assoc "&formatted" x))
 	      len (length tmp))
-	(put-text-property 0 len ':data x tmp)
+	(put-text-property 0 len :data x tmp)
 	(put-text-property 0 (1- len) 'mouse-face mouse-face tmp)
 	(insert tmp)))
      list))
 	  (setq bibfile-list (list (cdr tmp))
 		item t))
 	 (reftex-default-bibliography
-	  (setq bibfile-list reftex-default-bibliography))
+	  (setq bibfile-list (reftex-default-bibliography)))
 	 (t (ding) (throw 'exit))))
 
       (when no-revisit
   (if (marker-position reftex-recursive-edit-marker)
       (error
        (substitute-command-keys
-        "In unfinished selection process. Finish, or abort with \\[abort-recursive-edit]."))))
+        "In unfinished selection process. Finish, or abort with \\[abort-recursive-edit]"))))
 
 (defun reftex-select-item (prompt help-string keymap
 				  &optional offset
 
 (defun reftex-select-post-command-hook ()
   (let (b e)
-    (setq data (get-text-property (point) ':data))
+    (setq data (get-text-property (point) :data))
     (setq last-data (or data last-data))
   
     (when (and data cb-flag
 	       (not reftex-revisit-to-follow)))
     (if data
 	(setq b (or (previous-single-property-change
-		     (1+ (point)) ':data)
+		     (1+ (point)) :data)
 		    (point-min))
 	      e (or (next-single-property-change
-		     (point) ':data)
+		     (point) :data)
 		    (point-max)))
       (setq b (point) e (point)))
     (and (memq reftex-highlight-selection '(cursor both))
      ((and (local-variable-p 'reftex-last-data (current-buffer))
 	   reftex-last-data
 	   (setq pos (text-property-any (point-min) (point-max)
-					':data reftex-last-data)))
+					:data reftex-last-data)))
       (goto-char pos))
      ((and (local-variable-p 'reftex-last-line (current-buffer))
 	   (integerp reftex-last-line))
   "Accept the item at the mouse click."
   (interactive "e")
   (mouse-set-point ev)
-  (setq data (get-text-property (point) ':data))
+  (setq data (get-text-property (point) :data))
   (setq last-data (or data last-data))
   (throw 'myexit 'return))
 (defun reftex-select-read-label ()
 ;;;
 ;;; View cross references
 
-(defun reftex-view-crossref (&optional arg how)
-  "View cross reference of \\ref or \\cite macro at point.
-If the macro at point is a \\ref, show the corresponding label definition.
-If it is a \\cite, show the BibTeX database entry or the \\bibitem.
-To cope with the plethora of variations in packages, this
-function assumes any macro either starting with or ending in `ref' or
-`cite' to contain cross references.
-When the LaTeX package `xr' is being used, this command will also view
-crossreferences in external documents.  However, this works correctly only
-when the \\externaldocument macros are used with the optional label prefix
-argument.
+(defun reftex-view-crossref (&optional arg auto-how)
+  "View cross reference of macro at point.  Point must be on the KEY
+argument.  When at at `\ref' macro, show corresponding `\label'
+definition, also in external documents (`xr').  When on a label, show
+a locations where KEY is referenced.  Subsequent calls find additional
+locations.  When on a `\cite', show the associated `\bibitem' macro or
+the BibTeX database entry.  When on a `\bibitem', show a `\cite' macro
+which uses this KEY. When on an `\index', show other locations marked
+by the same index entry.
+To define additional cross referencing items, use the option
+`reftex-view-crossref-extra'.  See also `reftex-view-crossref-from-bibtex'.
 With one or two C-u prefixes, enforce rescanning of the document.
 With argument 2, select the window showing the cross reference.
-When HOW is 'echo, call the corresponding echo function.
-When HOW is 'tmp-window, make the pop-up window as small as possible and
-arrange for its removal before the next command."
+AUTO-HOW is only for the automatic crossref display and is handed through
+to the functions `reftex-view-cr-cite' and `reftex-view-cr-ref'."
 
   (interactive "P")
-
   ;; See where we are.
   (let* ((macro (car (reftex-what-macro 1)))
-         (key (reftex-this-word "^{}%\n\r,")))
+         (key (reftex-this-word "^{}%\n\r,"))
+	 dw)
+
+    (if (or (null macro) (reftex-in-comment))
+	(error "Not on a crossref macro argument"))
 
     (setq reftex-call-back-to-this-buffer (current-buffer))
 
-    (if (and macro
-	     (string-match "\\`\\\\cite\\|\\`\\\\ref\\|cite\\'\\|ref\\'"
-			   macro))
-	(and (setq macro (match-string 0 macro))
-	     (string-match "\\`\\\\" macro)
-	     (setq macro (substring macro 1)))
-      (setq macro nil))
-
-    (if (or (null macro) (reftex-in-comment))
-	(error "No cross reference to display"))
-
-    (if (eq how 'tmp-window)
-	;; Remember the window configuration
-	(put 'reftex-auto-view-crossref 'last-window-conf 
-	     (current-window-configuration)))
     (cond
-     ((string= macro "cite")
-      (reftex-view-cr-cite arg key how))
-     ((string= macro "ref")
-      (reftex-view-cr-ref arg key how))
+     ((string-match "\\`\\\\cite\\|cite\\*?\\'" macro)
+      ;; A citation macro: search for bibitems or BibTeX entries
+      (setq dw (reftex-view-cr-cite arg key auto-how)))
+     ((string-match "\\`\\\\ref\\|ref\\*?\\'" macro)
+      ;; A reference macro: search for labels
+      (setq dw (reftex-view-cr-ref arg key auto-how)))
+     (auto-how nil)  ;; No further action for automatic display (speed)
+     ((or (equal macro "\\label")
+	  (member macro reftex-macros-with-labels))
+      ;; A label macro: search for reference macros
+      (reftex-access-scan-info arg)
+      (setq dw (reftex-view-regexp-match
+		(format reftex-find-reference-format (regexp-quote key))
+		3 nil nil)))
+     ((equal macro "\\bibitem")
+      ;; A bibitem macro: search for citations
+      (reftex-access-scan-info arg)
+      (setq dw (reftex-view-regexp-match
+		(format reftex-find-citation-regexp-format (regexp-quote key))
+		3 nil nil)))
      (t 
-      (error "Cannot display crossref\n")))))
+      (reftex-access-scan-info arg)
+      (catch 'exit
+	(let ((list reftex-view-crossref-extra)
+	      entry mre action group)
+	  (while (setq entry (pop list))
+	    (setq mre (car entry)
+		  action (nth 1 entry)
+		  group (nth 2 entry))
+	    (when (string-match mre macro)
+	      (setq dw (reftex-view-regexp-match 
+			(format action key) group nil nil))
+	      (throw 'exit t))))
+	(error "Not on a crossref macro argument"))))
+    (if (and (eq arg 2) (windowp dw)) (select-window dw))))
      
 (defun reftex-view-cr-cite (arg key how)
   ;; View crossreference of a ref cite.  HOW can have the values 
   ;; Ensure access to scanning info
   (reftex-access-scan-info (or arg current-prefix-arg))
 
+  (if (eq how 'tmp-window)
+      ;; Remember the window configuration
+      (put 'reftex-auto-view-crossref 'last-window-conf 
+	   (current-window-configuration)))
+
   (let (files size item (pos (point)) (win (selected-window)) pop-win)
     ;; Find the citation mode and the file list
     (cond
 				   (symbol-value reftex-docstruct-symbol))))))
      (reftex-default-bibliography
       (setq item nil
-	    files reftex-default-bibliography))
+	    files (reftex-default-bibliography)))
      (how)  ;; don't throw for special display
      (t (error "Cannot display crossref")))
 
   ;; Ensure access to scanning info
   (reftex-access-scan-info (or arg current-prefix-arg))
   
+  (if (eq how 'tmp-window)
+      ;; Remember the window configuration
+      (put 'reftex-auto-view-crossref 'last-window-conf 
+	   (current-window-configuration)))
+
   (let* ((xr-data (assoc 'xr (symbol-value reftex-docstruct-symbol)))
 	 (xr-re (nth 2 xr-data))
 	 (entry (assoc label (symbol-value reftex-docstruct-symbol)))
 	  (setq entry 
 		(assoc label (symbol-value reftex-docstruct-symbol)))))
     (if (eq how 'echo)
-	;; Dsiplay in echo area
+	;; Display in echo area
 	(reftex-echo-ref label entry (symbol-value reftex-docstruct-symbol))
       (let ((window-conf (current-window-configuration)))
 	(condition-case nil
 			    'reftex-view-crossref-when-idle 
 			    reftex-idle-time nil t))))
 
+(defun reftex-view-crossref-from-bibtex (&optional arg)
+  "View location in a LaTeX document which cites the BibTeX entry at point.
+Since BibTeX files can be used by many LaTeX documents, this function
+promps upon first use for a buffer in RefTeX mode.  To reset this
+link to a document, call the function with with a prefix arg.
+Calling this function several times find successive citation locations."
+  (interactive "P")
+  (when arg 
+    ;; Break connection to reference buffer
+    (remprop 'reftex-bibtex-view-cite-locations :ref-buffer))
+  (let ((ref-buffer (get 'reftex-bibtex-view-cite-locations :ref-buffer)))
+    ;; Establish connection to reference buffer
+    (unless ref-buffer
+      (setq ref-buffer
+	    (save-excursion
+	      (completing-read 
+	       "Reference buffer: "
+	       (delq nil
+		     (mapcar 
+		      (lambda (b)
+			(set-buffer b)
+			(if reftex-mode (list (buffer-name b)) nil))
+		      (buffer-list)))
+	       nil t)))
+      (put 'reftex-bibtex-view-cite-locations :ref-buffer ref-buffer))
+    ;; Search for citations
+    (bibtex-beginning-of-entry)
+    (if (looking-at
+	 "@[a-zA-Z]+[ \t\n\r]*[{(][ \t\n\r]*\\([^, \t\r\n}]+\\)")
+	(progn
+	  (goto-char (match-beginning 1))
+	  (reftex-view-regexp-match
+	   (format reftex-find-citation-regexp-format
+		   (regexp-quote (match-string 1)))
+	   3 arg ref-buffer))
+      (error "Cannot find citation key in BibTeX entry"))))
+
+(defun reftex-view-regexp-match (re &optional highlight-group new ref-buffer)
+  ;; Search for RE in current document or in the document of REF-BUFFER.
+  ;; Continue the search, if the same re was searched last.
+  ;; Highlight the group HIGHLIGHT-GROUP of the match.
+  ;; When NEW is non-nil, start a new search regardless.
+  ;; Match point is displayed in another window.
+  ;; Upon success, returns the window which displays the match.
+
+  ;;; Decide if new search or continued search
+  (let* ((oldprop (get 'reftex-view-regexp-match :props))
+	 (newprop (list (current-buffer) re))
+	 (cont (and (not new) (equal oldprop newprop)))
+	 (cnt (if cont (get 'reftex-view-regexp-match :cnt) 0))
+	 (current-window (selected-window))
+	 (window-conf (current-window-configuration))
+	 match pop-window)
+    (switch-to-buffer-other-window (or ref-buffer (current-buffer)))
+    ;; Search
+    (condition-case nil
+	(if cont
+	    (setq match (reftex-global-search-continue))
+	  (reftex-access-scan-info)
+	  (setq match (reftex-global-search re (reftex-all-document-files))))
+      (error nil))
+    ;; Evaluate the match.
+    (if match
+	(progn
+	  (put 'reftex-view-regexp-match :props newprop)
+	  (put 'reftex-view-regexp-match :cnt (incf cnt))
+	  (reftex-highlight 0 (match-beginning highlight-group)
+			    (match-end highlight-group))
+	  (add-hook 'pre-command-hook 'reftex-highlight-shall-die)
+	  (setq pop-window (selected-window)))
+      (remprop 'reftex-view-regexp-match :props)
+      (or cont (set-window-configuration window-conf)))
+    (select-window current-window)
+    (if match
+	(progn
+	  (message "Match Nr. %s" cnt)
+	  pop-window)
+      (if cont
+	  (error "No further matches (total number of matches: %d)" cnt)
+	(error "No matches")))))
+
+(defvar reftex-global-search-marker (make-marker))
+(defun reftex-global-search (regexp file-list)
+  ;; Start a search for REGEXP in all files of FILE-LIST
+  (put 'reftex-global-search :file-list file-list)
+  (put 'reftex-global-search :regexp regexp)
+  (move-marker reftex-global-search-marker nil)
+  (reftex-global-search-continue))
+
+(defun reftex-global-search-continue ()
+  ;; Continue a global search started with `reftex-global-search'
+  (unless (get 'reftex-global-search :file-list)
+    (error "No global search to continue"))
+  (let* ((file-list (get 'reftex-global-search :file-list))
+	 (regexp (get 'reftex-global-search :regexp))
+	 (buf (or (marker-buffer reftex-global-search-marker)
+		  (reftex-get-file-buffer-force (car file-list))))
+	 (pos (or (marker-position reftex-global-search-marker) 1))
+	 file)
+    ;; Take up starting position
+    (unless buf (error "No such buffer %s" buf))
+    (switch-to-buffer buf)
+    (widen)
+    (goto-char pos)
+    ;; Search and switch file if necessary
+    (if (catch 'exit
+	  (while t
+	    (when (re-search-forward regexp nil t)
+	      (move-marker reftex-global-search-marker (point))
+	      (throw 'exit t))
+	    ;; No match - goto next file
+	    (pop file-list)
+	    (or file-list (throw 'exit nil))
+	    (setq file (car file-list)
+		  buf (reftex-get-file-buffer-force file))
+	    (unless buf (error "Cannot access file %s" file))
+	    (put 'reftex-global-search :file-list file-list)
+	    (switch-to-buffer buf)
+	    (widen)
+	    (goto-char 1)))
+	t
+      (move-marker reftex-global-search-marker nil)
+      (error "All files processed"))))
+
 ;;; =========================================================================
 ;;;
 ;;; Functions that check out the surroundings
       (pop alist))
     (nreverse out)))
 
+(defun reftex-window-height ()
+  (if (fboundp 'window-displayed-height)
+      (window-displayed-height)
+    (window-height)))
+
 (defun reftex-enlarge-to-fit (buf2 &optional keep-current)
   ;; Enlarge other window displaying buffer to show whole buffer if possible.
   ;; If KEEP-CURRENT in non-nil, current buffer must remain visible.
   (let* ((win1 (selected-window))
 	 (buf1 (current-buffer))
-	 (win2 (get-buffer-window buf2)))
+	 (win2 (get-buffer-window buf2))) ;; Only on current frame.
     (when win2
       (select-window win2)
       (unless (and (pos-visible-in-window-p 1)
 		   (pos-visible-in-window-p (point-max)))
 	(enlarge-window (1+ (- (count-lines 1 (point-max))
-			       (window-height))))))
+			       (reftex-window-height))))))
     (cond
      ((window-live-p win1) (select-window win1))
      (keep-current
 	(message (concat prompt "   (?=Help)"))
 	(when (or (sit-for (or delay-time 0))
 		  (= ?\? (setq char (read-char-exclusive))))
-	  (with-output-to-temp-buffer " *RefTeX Help*"
-	    (princ help-string))
-	  (reftex-enlarge-to-fit " *RefTeX Help*")
-	  (select-window (get-buffer-window " *RefTeX Help*"))
+	  (reftex-kill-buffer "*RefTeX Select*")
+	  (switch-to-buffer-other-window "*RefTeX Select*")
+	  (insert help-string)
+	  (goto-char 1)
+	  (unless (and (pos-visible-in-window-p 1)
+		       (pos-visible-in-window-p (point-max)))
+	    (enlarge-window (1+ (- (count-lines 1 (point-max))
+				   (reftex-window-height)))))
 	  (setq truncate-lines t))
 	(setq prompt (concat prompt (if scroll "   (SPC/DEL=Scroll)" "")))
 	(message prompt)
 (defconst reftex-cache-variables 
   '(reftex-memory ;; This MUST ALWAYS be the first!
     reftex-env-or-mac-alist reftex-everything-regexp
+    reftex-macros-with-labels
     reftex-find-label-regexp-format reftex-find-label-regexp-format2
     reftex-label-env-list reftex-label-mac-list
     reftex-section-or-include-regexp reftex-section-levels-all
             (concat label-re "\\|" section-re "\\|" include-re
 		    "\\|" appendix-re
                     (if macros-with-labels "\\|" "") macro-re)
+	    reftex-macros-with-labels macros-with-labels
             reftex-find-label-regexp-format find-label-re-format
 	    reftex-find-label-regexp-format2 
 	    "\\([]} \t\n\r]\\)\\([[{]\\)\\(%s\\)[]}]")
   "Toggle Interface between AUCTeX and RefTeX on and off."
   (interactive)
   (unless (and (featurep 'tex-site) (featurep 'latex))
-    (error "AUCTeX's LaTeX mode does not seem to be loaded."))
+    (error "AUCTeX's LaTeX mode does not seem to be loaded"))
   (setq reftex-plug-into-AUCTeX (not reftex-plug-into-AUCTeX))
   (reftex-plug-into-AUCTeX)
   (if reftex-plug-into-AUCTeX
 	("\C-c&" . reftex-view-crossref))
       do (define-key reftex-mode-map (car x) (cdr x)))
 
+(eval-after-load 
+ "bibtex"
+ '(define-key bibtex-mode-map "\C-c&" 'reftex-view-crossref-from-bibtex))
+
 ;; Bind `reftex-mouse-view-crossref' only when the key is still free
-(if (featurep 'xemacs)
-    (unless (key-binding [(shift button2)])
-      (define-key reftex-mode-map [(shift button2)] 
-	'reftex-mouse-view-crossref))
-  (unless (key-binding [(shift mouse-2)])
-    (define-key reftex-mode-map [(shift mouse-2)] 
-      'reftex-mouse-view-crossref)))
+(let ((key (if (featurep 'xemacs) [(shift button2)] [(shift mouse-2)])))
+  (unless (key-binding key)
+    (define-key reftex-mode-map key 'reftex-mouse-view-crossref)))
 
 ;; If the user requests so, she can have a few more bindings:
 (when reftex-extra-bindings
 	do (define-key map (car x) (cdr x)))
 
   ;; The mouse-2 binding
-  (if (featurep 'xemacs)
-      (define-key map [(button2)] 'reftex-select-mouse-accept)
-    (define-key map [(mouse-2)] 'reftex-select-mouse-accept))
+  (define-key map (if (featurep 'xemacs) [(button2)] [(mouse-2)])
+    'reftex-select-mouse-accept)
 
   ;; Digit arguments
   (loop for key across "0123456789" do
       do (define-key reftex-select-bib-map (car x) (cdr x)))
   
 ;; Table of Contents map
-(if (featurep 'xemacs)
-    (define-key reftex-toc-map [(button2)] 'reftex-toc-mouse-goto-line-and-hide)
-  (define-key reftex-toc-map  [(mouse-2)] 'reftex-toc-mouse-goto-line-and-hide))
+(define-key reftex-toc-map (if (featurep 'xemacs) [(button2)] [(mouse-2)])
+  'reftex-toc-mouse-goto-line-and-hide)
 
 (substitute-key-definition
  'next-line 'reftex-toc-next reftex-toc-map global-map)
     ["Save Document"          reftex-save-all-document-buffers t])
    "---"
    ("Options"
-    ("Table of Contents"
-     ["Keep Other Windows" (setq reftex-toc-keep-other-windows 
-				 (not reftex-toc-keep-other-windows))
-      :style toggle :selected reftex-toc-keep-other-windows]
-     ["Follow Mode" (setq reftex-toc-follow-mode (not reftex-toc-follow-mode))
-      :style toggle :selected reftex-toc-follow-mode]
-     ["Follow Mode may Visit Files"
-      (setq reftex-revisit-to-follow (not reftex-revisit-to-follow))
-      :style toggle :selected reftex-revisit-to-follow])
-    ("References"
-     ["Guess Label Type" 
-      (setq reftex-guess-label-type (not reftex-guess-label-type))
-      :style toggle :selected reftex-guess-label-type]
-     ["Use `\\vref' by Default" 
-      (setq reftex-vref-is-default (not reftex-vref-is-default))
-      :style toggle :selected reftex-vref-is-default]
-     "---"
-     "Selection Buffers"
-     ["Use Multiple Buffers"
-      (setq reftex-use-multiple-selection-buffers
-	    (not reftex-use-multiple-selection-buffers))
-      :style toggle :selected reftex-use-multiple-selection-buffers]
-     ["Auto Update Buffers"
-      (setq reftex-auto-update-selection-buffers
-	    (not reftex-auto-update-selection-buffers))
-      :style toggle :selected reftex-auto-update-selection-buffers])
-    ("Citations"
-     "Citation Style"
-     ,@(mapcar
-	(function
-	 (lambda (x)
-	   (vector
-	    (capitalize (symbol-name (car x)))
-	    (list 'reftex-set-cite-format (list 'quote (car x)))
-	    ':style 'radio ':selected
-	    (list 'eq (list 'reftex-get-cite-format) (list 'quote (car x))))))
-	reftex-cite-format-builtin)
-     "---"
-     "Bibinfo in Comments"
-     ["Attach Comments"
-      (setq reftex-comment-citations (not reftex-comment-citations))
-      :style toggle :selected reftex-comment-citations]
-     "---"
-     "Sort Database Matches"
-     ["Not" (setq reftex-sort-bibtex-matches nil)
-      :style radio :selected (eq reftex-sort-bibtex-matches nil)]
-     ["by Author" (setq reftex-sort-bibtex-matches 'author)
-      :style radio :selected (eq reftex-sort-bibtex-matches 'author)]
-     ["by Year" (setq reftex-sort-bibtex-matches 'year)
-      :style radio :selected (eq reftex-sort-bibtex-matches 'year)]
-     ["by Year, reversed" (setq reftex-sort-bibtex-matches 'reverse-year)
-      :style radio :selected (eq reftex-sort-bibtex-matches 'reverse-year)])
-    ("Crossref Viewing"
-     ["Automatic Info" reftex-toggle-auto-view-crossref
-      :style toggle :selected reftex-auto-view-crossref-timer]
-     ["...in Echo Area" (setq reftex-auto-view-crossref t)
-      :style radio :selected (eq reftex-auto-view-crossref t)]
-     ["...in Other Window" (setq reftex-auto-view-crossref 'window)
-      :style radio :selected (eq reftex-auto-view-crossref 'window)]
-     "---"
-     ["Crossref Echo may Visit Files"
-      (setq reftex-revisit-to-echo (not reftex-revisit-to-echo))
-      :style toggle :selected reftex-revisit-to-echo]
-     ["Cache Echo Strings for \cite"
-      (setq reftex-cache-cite-echo (not reftex-cache-cite-echo))
-      :style toggle :selected reftex-cache-cite-echo])
-    ("Parser"
-     "Document Scans"
-     ["Partial Scans"
-      (setq reftex-enable-partial-scans (not reftex-enable-partial-scans))
-      :style toggle :selected reftex-enable-partial-scans]
-     ["Auto-Save Parse Info"
-      (setq reftex-save-parse-info (not reftex-save-parse-info))
-      :style toggle :selected reftex-save-parse-info]
-     ["Automatic Rescans"
-      (setq reftex-allow-automatic-rescan (not reftex-allow-automatic-rescan))
-      :style toggle :selected reftex-allow-automatic-rescan]
-     "---"
-     "Temporary Buffers"
-     ["Keep Buffers"
-      (setq reftex-keep-temporary-buffers (not reftex-keep-temporary-buffers))
-      :style toggle :selected reftex-keep-temporary-buffers]
-     ["Initialize when Visiting"
-      (setq reftex-initialize-temporary-buffers
-	    (not reftex-initialize-temporary-buffers))
-      :style toggle :selected reftex-initialize-temporary-buffers])
-    ("AUC TeX"
-     ["Plug into AUC TeX" reftex-toggle-plug-into-AUCTeX
-      :style toggle :selected reftex-plug-into-AUCTeX])
-    ("Fontification"
-     ["Use Fontification" (setq reftex-use-fonts (not reftex-use-fonts))
-      :style toggle :selected reftex-use-fonts]
-     ["Fontify Context Display" (setq reftex-refontify-context 
-				      (not (reftex-refontify)))
-      :style toggle :selected (reftex-refontify)]))
-   ;;"---"
+    "PARSER"
+    ["Partial Scans"
+     (setq reftex-enable-partial-scans (not reftex-enable-partial-scans))
+     :style toggle :selected reftex-enable-partial-scans]
+    ["Auto-Save Parse Info"
+     (setq reftex-save-parse-info (not reftex-save-parse-info))
+     :style toggle :selected reftex-save-parse-info]
+    "---"
+    "CROSSREF INFO"
+    ["Automatic Info" reftex-toggle-auto-view-crossref
+     :style toggle :selected reftex-auto-view-crossref-timer]
+    ["...in Echo Area" (setq reftex-auto-view-crossref t)
+     :style radio :selected (eq reftex-auto-view-crossref t)]
+    ["...in Other Window" (setq reftex-auto-view-crossref 'window)
+     :style radio :selected (eq reftex-auto-view-crossref 'window)]
+    "---"
+    "MISC"
+    ["AUC TeX Interface" reftex-toggle-plug-into-AUCTeX
+     :style toggle :selected reftex-plug-into-AUCTeX])
+   ("Reference Style"
+    ["Standard" (setq reftex-vref-is-default nil)
+     :style radio :selected (not reftex-vref-is-default)]
+    ["Varioref" (setq reftex-vref-is-default t)
+     :style radio :selected reftex-vref-is-default])
+   ("Citation Style"
+    ,@(mapcar
+       (function
+	(lambda (x)
+	  (vector
+	   (capitalize (symbol-name (car x)))
+	   (list 'reftex-set-cite-format (list 'quote (car x)))
+	   :style 'radio :selected
+	   (list 'eq (list 'reftex-get-cite-format) (list 'quote (car x))))))
+       reftex-cite-format-builtin)
+    "---"
+    "Sort Database Matches"
+    ["Not" (setq reftex-sort-bibtex-matches nil)
+     :style radio :selected (eq reftex-sort-bibtex-matches nil)]
+    ["by Author" (setq reftex-sort-bibtex-matches 'author)
+     :style radio :selected (eq reftex-sort-bibtex-matches 'author)]
+    ["by Year" (setq reftex-sort-bibtex-matches 'year)
+     :style radio :selected (eq reftex-sort-bibtex-matches 'year)]
+    ["by Year, reversed" (setq reftex-sort-bibtex-matches 'reverse-year)
+     :style radio :selected (eq reftex-sort-bibtex-matches 'reverse-year)])
+   "---"
    ("Customize"
     ["Browse RefTeX Group" reftex-customize t]
     "---"
     ["Build Full Customize Menu" reftex-create-customize-menu 
      (fboundp 'customize-menu-create)])
-   "---"
    ("Documentation"
     ["Info" reftex-info t]
     ["Commentary" reftex-show-commentary t])))
 
 ;;; reftex.el ends here
 
+	      

File reftex.texi

View file
  • Ignore whitespace
 @synindex ky cp
 @syncodeindex vr cp
 @syncodeindex fn cp
+@set VERSION 3.43
+@set EDITION 3.43
+@set DATE December 1998
+@set AUTHOR Carsten Dominik
+@set AUTHOR-EMAIL dominik@@strw.leidenuniv.nl
+@set MAINTAINER Carsten Dominik
+@set MAINTAINER-EMAIL dominik@@strw.leidenuniv.nl
 @c %**end of header
 @finalout
 
 This file documents @b{Ref@TeX{}}, a package to do labels, references and
 citations for LaTeX documents with Emacs.@refill
 
-This is edition 3.42 of the @b{Ref@TeX{}} User Manual for @b{Ref@TeX{}} 3.42
+This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for
+@b{Ref@TeX{}} @value{VERSION}@refill
 
 Copyright (c) 1997, 1998 Free Software Foundation, Inc.
 
 @titlepage
 @title Ref@TeX{} User Manual
 @subtitle Support for LaTeX labels, references, and citations with GNU Emacs
-@subtitle Edition 3.42, November 1998
+@subtitle Edition @value{EDITION}, @value{DATE}
 
 @author by Carsten Dominik
 @page
 Copyright @copyright{} 1997, 1998 Free Software Foundation, Inc.
 
 @sp 2
-This is edition 3.42 of the @cite{Ref@TeX{} User Manual} for @b{Ref@TeX{}}
-version 3.42, November 1998.@refill
+This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for
+@b{Ref@TeX{}} version @value{VERSION}, @value{DATE}.@refill
 
 @sp 2
 
 @ifinfo
 @node Top,,,(dir)
 
-@b{Ref@TeX{}} is a package for managing Labels, References and Citations
-with GNU Emacs.@refill
-
-Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}}
-in great depth.  All you need to know to use @b{Ref@TeX{}} can be
-summarized on a single page (@pxref{RefTeX in a Nutshell}).  You can go
-back later to other parts of this document when needed.@refill
+@b{Ref@TeX{}} is a package for managing Labels, References and
+Citations with GNU Emacs.@refill
+
+Don't be discouraged by the size of this manual, which covers
+@b{Ref@TeX{}} in great depth.  All you need to know to use
+@b{Ref@TeX{}} can be summarized on a single page (@pxref{RefTeX in a
+Nutshell}).  You can go back later to other parts of this document when
+needed.@refill
 
 @menu
 * Introduction::                     Quick-Start information.
 * Table of Contents::                A Tool to move around quickly.
 * Labels and References::            Creating and referencing labels.
 * Citations::                        Creating Citations.
+* Viewing Cross-References::         Who references or cites what?
 
 * RefTeXs Menu::                     The Ref menu in the menubar.
 * Keybindings::                      The default keybindings.
 
 * Index::                            The full index.
 
+@detailmenu
+
 Introduction
 
 * Installation::                     How to install and activate RefTeX.
 * RefTeX in a Nutshell::             A brief summary and quick guide.
-
+ 
 Labels and References
 
 * Creating Labels::
 * Referencing Labels::
 * Builtin Label Environments::       The environments RefTeX knows about.
 * Defining Label Environments::        ... and environments it doesn't.
-* Displaying Cross References::      View the label corresponding to a \ref.
+* Reference Info::                   View the label corresponding to a \ref.
 * xr (LaTeX package)::               References to external documents.
 * varioref (LaTeX package)::         How to create \vref instead of \ref.
 
 
 * Creating Citations::               How to create them.
 * Citation Styles::                  Natbib, Harvard, Chicago and CO.
-* Displaying Citations::             View the corresponding database entry.
+* Citation Info::                    View the corresponding database entry.
 * Chapterbib and Bibunits::          Multiple bibliographies in a Document.
 * Citations Outside LaTeX::          How to make citations in Emails etc.
 
 * Options (Creating Labels)::
 * Options (Referencing Labels)::
 * Options (Creating Citations)::
-* Options (Viewing Cross References)::
+* Options (Viewing Cross-References)::
 * Options (Finding Files)::
 * Options (Optimizations)::
 * Options (Fontification)::
 * Options (Misc)::
 
+@end detailmenu
 @end menu
 
 @end ifinfo
 @section Installation
 @cindex Installation
 
-@b{Ref@TeX{}} is bundled and preinstalled with Emacs since version 20.2.
-It was also bundled and preinstalled with XEmacs 19.16--20.x.  XEmacs
-21.x users want to install the corresponding plugin package which is
-available from the XEmacs @code{ftp} site.  See the XEmacs 21.x
-documentation on package installation for details.@refill
+@b{Ref@TeX{}} is bundled and pre--installed with Emacs since version 20.2.
+It was also bundled and pre--installed with XEmacs 19.16--20.x.  XEmacs
+21.x users want to install the corresponding plug-in package which is
+available from the
+@uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}.  See
+the XEmacs 21.x documentation on package installation for
+details.@refill
 
 Users of earlier Emacs distributions (including Emacs 19) can get a copy
-of the @b{Ref@TeX{}} distribution from the maintainers webpage.
+of the @b{Ref@TeX{}} distribution from the maintainers web-page.
 @xref{Imprint} for more information.@refill
 
 @section Environment
 
 @findex turn-on-reftex
 @findex reftex-mode
+@vindex LaTeX-mode-hook
+@vindex latex-mode-hook
 To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use
 @kbd{M-x reftex-mode}.  To turn on @b{Ref@TeX{}} Mode for all LaTeX
 files, add the following lines to your @file{.emacs} file:@refill
 @b{Ref@TeX{}} distinguishes labels for different environments.  It knows
 about all standard environments (and many others), and can be configured
 to recognize any additional labeled environments you have defined
-yourself (variable @var{reftex-label-alist}).@refill
+yourself (variable @code{reftex-label-alist}).@refill
 
 @b{Creating Labels}@* 
 Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point.
 environments)@refill
 @end itemize
 @noindent
-Which labels are created how is configurable with the variable
-@var{reftex-insert-label-flags}.@refill
+This is configurable with the variable
+@code{reftex-insert-label-flags}.@refill
 
 @b{Referencing Labels}@* 
 To make a reference, type @kbd{C-c )} (@code{reftex-reference}).  This
 shows an outline of the document with all labels of a certain type
 (figure, equation,...) and some label context.  Selecting a
-label inserts a @code{\ref@{LABEL@}} macro into the original
+label inserts a @code{\ref@{@var{label}@}} macro into the original
 buffer.@refill
 
 @item
 regular expression to search in current BibTeX database files (as
 specified in the @code{\bibliography} command) and pull out a list of
 matches for you to choose from.  The list is @emph{formatted} and
-sorted.  The selected article is referenced as @samp{\cite@{KEY@}}
-(see also the variable @var{reftex-cite-format}).@refill
-
-@item
-@b{Viewing Cross References}@*
-When point is idle on the argument of a @code{\ref} or @code{\cite}
-macro, the echo area will (if it is empty) display information about the
-citation/cross reference.  Press @kbd{C-c &}
-(@code{reftex-view-crossref}), or click with @kbd{S-mouse-2} on the
-macro argument to display the corresponding label definition or
-BibTeX database entry in another window.@refill
+sorted.  The selected article is referenced as @samp{\cite@{@var{key}@}}
+(see variable @code{reftex-cite-format}).@refill
+
+@item @b{Viewing Cross-References}@*
+When point is on the @var{key} argument of a cross--referencing macro
+(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
+@code{\index}, and variations) or inside a BibTeX database entry, you
+can press @kbd{C-c &} (@code{reftex-view-crossref}) to display
+corresponding locations in the document and associated BibTeX database
+files.@refill @*
+When the enclosing macro is @code{\cite} or
+@code{\ref} and no other message occupies the echo area, information
+about the citation or label will automatically be displayed.@refill
 
 @item
 @b{Multifile Documents}@* Multifile Documents are fully
-supported. @b{Ref@TeX{}} provides cross referencing information from
-all files which are part of the document, and across document
-borders (@file{xr.sty}).@refill
+supported. @b{Ref@TeX{}} provides cross-referencing information from all
+parts of the document, and across document borders
+(@file{xr.sty}).@refill
 
 @item
 @b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in
 
 @node Table of Contents, Labels and References, Introduction, Top
 @chapter Table of Contents
-@cindex @code{*toc*} buffer
+@cindex @file{*toc*} buffer
 @cindex Table of contents buffer
 @findex reftex-toc
 @kindex C-c =
 
 Pressing the keys @kbd{C-c =} pops up a buffer showing
-the table of contents of the document.  By default, this @code{*toc*}
+the table of contents of the document.  By default, this @file{*toc*}
 buffer shows only the sections of a document.  Using the @kbd{l} and
 @kbd{c} keys you can have all labels defined in the document and some
 context of the label definition displayed as well.@refill
 document, simple key strokes will display the corresponding part in
 another window, jump to that location, or perform other actions.@refill
 
-Here is a list of special commands in the @code{*toc*} buffer.  A
+@kindex ?
+Here is a list of special commands in the @file{*toc*} buffer.  A
 summary of this information is always available by pressing
 @kbd{?}.@refill
 
 Prefix argument.
 
 @item c
-Toggle the display of label context in the @code{*toc*} buffer.  The
+@vindex reftex-toc-include-context
+Toggle the display of label context in the @file{*toc*} buffer.  The
 default for this flag can be set with the variable
-@var{reftex-toc-include-context}.@refill
+@code{reftex-toc-include-context}.@refill
 
 @item f
+@vindex reftex-toc-follow-mode
+@vindex reftex-revisit-to-follow
 Toggle follow mode.  When follow mode is active, the other window will
-always show the location corresponding to the line in the @code{*toc*}
+always show the location corresponding to the line in the @file{*toc*}
 buffer at point.  This is similar to pressing @key{SPC} after each
 cursor motion.  The default for this flag can be set with the variable
-@var{reftex-toc-follow-mode}.  Note that only context in files already
+@code{reftex-toc-follow-mode}.  Note that only context in files already
 visited is shown.  @b{RefTeX} will not visit a file just for follow
-mode.  See, however, the variable @var{reftex-revisit-to-follow}.@refill
+mode.  See, however, the variable @code{reftex-revisit-to-follow}.@refill
 
 @item g
-Rebuild the @code{*toc*} buffer.  This does @emph{not} rescan the
+Rebuild the @file{*toc*} buffer.  This does @emph{not} rescan the
 document.@refill
 
 @item i
+@vindex reftex-toc-include-file-boundaries
 Toggle the display of the file borders of a multifile document in the
-@code{*toc*} buffer.  The default for this flag can be set with the
-variable @var{reftex-toc-include-file-boundaries}.@refill
+@file{*toc*} buffer.  The default for this flag can be set with the
+variable @code{reftex-toc-include-file-boundaries}.@refill
 
 @item l
-Toggle the display of labels @code{*toc*} buffer.  The default for this
+@vindex reftex-toc-include-labels
+Toggle the display of labels @file{*toc*} buffer.  The default for this
 flag can be set with the variable
-@var{reftex-toc-include-labels}.@refill
+@code{reftex-toc-include-labels}.@refill
 
 @item n
 Goto next entry in the table of context.
 Goto previous entry in the table of context.
 
 @item q
-Hide the @code{*toc*} buffer, return to the position where
+Hide the @file{*toc*} buffer, return to the position where
 @code{reftex-toc} was last called.@refill
 
 @item Q
-Kill the @code{*toc*} buffer, return to the position where
+Kill the @file{*toc*} buffer, return to the position where
 @code{reftex-toc} was last called.@refill
 
 @item r
-Reparse the LaTeX document and rebuild the @code{*toc*} buffer.  When
-@var{reftex-enable-partial-scans} is non-nil, rescan only the file this
+@vindex reftex-enable-partial-scans
+Reparse the LaTeX document and rebuild the @file{*toc*} buffer.  When
+@code{reftex-enable-partial-scans} is non-nil, rescan only the file this
 location is defined in, not the entire document.@refill
 
 @item R
-Reparse the @emph{entire} LaTeX document and rebuild the @code{*toc*}
+Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*}
 buffer.@refill
 
 @item x
-Switch to the @code{*toc*} buffer of an external document.  When the
+Switch to the @file{*toc*} buffer of an external document.  When the
 current document is using the @code{xr} package (@pxref{xr (LaTeX
 package)}), @b{Ref@TeX{}} will switch to one of the external
 documents.@refill
 Goto the location in another window.
 
 @item @key{RET}
-Go to the location and hide the @code{*toc*} buffer.  This will restore
+Go to the location and hide the @file{*toc*} buffer.  This will restore
 the window configuration before @code{reftex-toc} (@kbd{C-c =}) was
 called.@refill
 
 @item mouse-2
+@vindex reftex-highlight-selection
 Clicking with mouse button 2 on a line has the same effect as @key{RET}.
-See also variable @var{reftex-highlight-selection}, @ref{Options
+See also variable @code{reftex-highlight-selection}, @ref{Options
 (Fontification)}.@refill
 
 @end table
 
-In order to define additional commands for the @code{*toc*} buffer, the
-keymap @var{reftex-toc-map} may be used.@refill
+@vindex reftex-toc-map
+In order to define additional commands for the @file{*toc*} buffer, the
+keymap @code{reftex-toc-map} may be used.@refill
+
+@cindex Sectioning commands
+@cindex KOMA-Script, LaTeX classes
+@cindex LaTeX classes, KOMA-Script
+@vindex reftex-section-levels
+The section macros recognized by @b{Ref@TeX{}} are all LaTeX section
+macros (from @code{\part} to @code{\subsubparagraph}) and the commands
+@code{\addchap} and @code{\addsec} from the KOMA-Script classes.
+Additional macros can be configured with the variable
+@code{reftex-section-levels}.
 
 @node Labels and References, Citations, Table of Contents, Top
 @chapter Labels and References
 @cindex Label environment
 @cindex @code{\label}
 
-LaTeX provides a powerful mechanism to deal with cross references in a
+LaTeX provides a powerful mechanism to deal with cross--references in a
 document.  When writing a document, any part of it can be marked with a
 label, like @samp{\label@{mark@}}.  LaTeX records the current value of a
 certain counter when a label is defined.  Later references to this label
 * Referencing Labels::
 * Builtin Label Environments::       The environments RefTeX knows about.
 * Defining Label Environments::        ... and environments it doesn't.
-* Displaying Cross References::      View the label corresponding to a \ref.
+* Reference Info::                   View the label corresponding to a \ref.
 * xr (LaTeX package)::               References to external documents.
 * varioref (LaTeX package)::         How to create \vref instead of \ref.
 @end menu
 
 @enumerate
 @item
+@vindex reftex-translate-to-ascii-function
+@vindex reftex-derive-label-parameters
+@vindex reftex-label-illegal-re
+@vindex reftex-abbrev-parameters
 A label can be derived from context.  This means, @b{Ref@TeX{}} takes
 the context of the label definition and constructs a label from
 that@footnote{Note that the context may contain constructs which are
 accented Latin-1 characters and remove everything else which is not
 legal in labels.  This mechanism is safe, but may not be satisfactory
 for non-western languages.  Check the following variables if you need to
-change things: @var{reftex-translate-to-ascii-function},
-@var{reftex-derive-label-parameters}, @var{reftex-label-illegal-re},
-@var{reftex-abbrev-parameters}.}.  This works best for section labels,
+change things: @code{reftex-translate-to-ascii-function},
+@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re},
+@code{reftex-abbrev-parameters}.}.  This works best for section labels,
 where the section heading is used to construct a label.  In fact,
 @b{Ref@TeX{}}'s default settings use this method only for section
 labels.  You will be asked to confirm the derived label, or edit
 this label later.@refill
 @end enumerate
 
+@vindex reftex-insert-label-flags
 If you want to change the way certain labels are created, check out the
-variable @var{reftex-insert-label-flags} (@pxref{Options (Creating
+variable @code{reftex-insert-label-flags} (@pxref{Options (Creating
 Labels)}).@refill
 
 If you are using AUCTeX to write your LaTeX documents, you can
 
 In order to reference a label, move to cursor to the correct label and
 press @key{RET}.@*
+@kindex ?
 Here is a list of special commands in the selection buffer.  A summary
 of this information is always available from the selection process by
 pressing @kbd{?}.@refill
 selection buffer.@refill
 
 @item f
+@vindex reftex-revisit-to-follow
 Toggle follow mode.  When follow mode is active, the other window will
 always display the full context of the current label.  This is similar
 to pressing @key{SPC} after each cursor motion.  Note that only context
 in files already visited is shown.  @b{RefTeX} will not visit a file
 just for follow mode.  See, however, the variable
-@var{reftex-revisit-to-follow}.@refill
+@code{reftex-revisit-to-follow}.@refill
 
 @item g
 Update the menu.  This will rebuilt the menu from the internal label
 buffer.@refill
 
 @item r
+@vindex reftex-enable-partial-scans
 Reparse the document to update the information on all labels and rebuild
-the menu.  If the variable @var{reftex-enable-partial-scans} is
+the menu.  If the variable @code{reftex-enable-partial-scans} is
 non-@code{nil} and your document is a multifile document, this will
 reparse only a part of the document (the file in which the label at
 point was defined).@refill
 selection process was started.@refill
 
 @item mouse-2
+@vindex reftex-highlight-selection
 Clicking with mouse button 2 on a label will accept it like @key{RET}
-would. See also variable @var{reftex-highlight-selection}, @ref{Options
+would. See also variable @code{reftex-highlight-selection}, @ref{Options
 (Misc)}.@refill
 
 @item #
 
 @end table
 
+@vindex reftex-label-menu-flags
+@vindex reftex-select-label-map
 Several of these keys toggle certain settings.  The default value for
 these flags can be preset by configuring the variable
-@var{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
+@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}).
 In order to define additional commands for the selection process, the
-keymap @var{reftex-select-label-map} may be used.@refill
+keymap @code{reftex-select-label-map} may be used.@refill
 
 @node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References
 @section Builtin Label Environments
 @code{wrapfigure} (@file{wrapfig.sty})
 @end itemize
 
-If you want to use other labeled environments, for example some defined
-with @code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize them
-(@pxref{Defining Label Environments}).@refill
-
-@node Defining Label Environments, Displaying Cross References, Builtin Label Environments, Labels and References
+If you want to use other labeled environments, defined with
+@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize
+them (@pxref{Defining Label Environments}).@refill
+
+@node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References
 @section Defining Label Environments
 @cindex Label environments, defining
+
 @vindex reftex-label-alist
-
 @b{Ref@TeX{}} can be configured to recognize additional labeled
 environments and macros.  This is done with the variable
-@var{reftex-label-alist} (@pxref{Options (Defining Label
+@code{reftex-label-alist} (@pxref{Options (Defining Label
 Environments)}).  If you are not familiar with Lisp, you should use the
 @code{custom} library to configure this rather complex variable.  To do
 this, use
 @kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}}
 @end example
 
+@vindex reftex-label-alist-builtin
 Here we will discuss a few examples, in order to make things clearer.
 It can also be instructive to look at the constant
-@var{reftex-label-alist-builtin} which contains the entries for
+@code{reftex-label-alist-builtin} which contains the entries for
 all the builtin environments and macros (@pxref{Builtin Label
 Environments}).@refill
 
 @code{nil} means to use the text right after the label definition.@refill
 @item
 For more complex ways of getting context, see the variable
-@var{reftex-label-alist} (@pxref{Options (Defining Label
+@code{reftex-label-alist} (@pxref{Options (Defining Label
 Environments)}).@refill
 @end itemize
 
               [INS]
 @end example
 
+@vindex reftex-insert-label-flags
+@vindex reftex-label-menu-flags
 Depending on how you would like the label insertion and selection for
 the new environments to work, you might want to add the letters @samp{a}
 and @samp{h} to some of the flags in the variables
-@var{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
-and @var{reftex-label-menu-flags} (@pxref{Options (Referencing
+@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)})
+and @code{reftex-label-menu-flags} (@pxref{Options (Referencing
 Labels)}).@refill
 
 
 @node Putting it Together, , Using \eqref, Defining Label Environments
 @subsection Putting it all together
 
-When you have to put several entries into @var{reftex-label-alist}, just
+When you have to put several entries into @code{reftex-label-alist}, just
 put them after each other in a list, or create that many templates in
 the customization buffer.  Here is a lisp example which uses several of
 the entries described above:
     ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3)))
 @end lisp
 
-@node Displaying Cross References, xr (LaTeX package), Defining Label Environments, Labels and References
-@section Displaying Cross References
+@node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References
+@section Reference Info
 @findex reftex-view-crossref
 @findex reftex-mouse-view-crossref
-@cindex Cross references, displaying
-@cindex Displaying cross references
-@cindex Viewing cross references
+@cindex Cross-references, displaying
+@cindex Reference info
+@cindex Displaying cross-references
+@cindex Viewing cross-references
 @kindex C-c &
-
-@b{Ref@TeX{}} can display the definition site of a label which is
-referenced in the text.  With the cursor on the argument of a
-@code{\ref} macro, type @kbd{C-c &}.  Or click with @kbd{S-mouse-2} on
-the argument of the macro.  @b{Ref@TeX{}} will then display the
-definition of the label in another window.  This works also with
-references to external labels (@pxref{xr (LaTeX package)}).@refill
-
-@b{Ref@TeX{}} also uses the echo area to display short information about
-the cross reference whenever the cursor is inside the argument of a
-@code{\ref} macro.  Note that the information is only displayed if the
-echo area is not occupied by a different message.  You can toggle this
-feature from the menu @w{(@code{Ref->Options->Crossref Viewing})}.  To
-turn it off or change its behavior, see the variable
-@var{reftex-auto-view-crossref}.@refill
-
-See also @ref{Displaying Citations}.
-
-@node xr (LaTeX package), varioref (LaTeX package), Displaying Cross References, Labels and References
+@kindex S-mouse-2
+
+When point is idle on the argument of a @code{\ref} macro, the echo area
+will display some information about the label referenced there.  Note
+that the information is only displayed if the echo area is not occupied
+by a different message.  
+
+@b{Ref@TeX{}} can also display the label definition corresponding to a
+@code{\ref} macro, or all reference locations corresponding to a
+@code{\label} macro.  @xref{Viewing Cross-References} for more
+information.@refill
+
+@node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References
 @section @code{xr}: Cross-Document References
 @cindex @code{xr}, LaTeX package
 @cindex LaTeX packages, @code{xr}
 documents.  You may then select a label as before and @b{Ref@TeX{}} will
 insert it along with the required prefix.@refill
 
-For this kind of inter-document cross references, saving of parsing
+For this kind of inter-document cross--references, saving of parsing
 information and the use of multiple selection buffers can mean a large
 speed-up (@pxref{Optimizations}).@refill
 
 @cindex @code{\vref}
 @cindex LaTeX packages, @code{varioref}
 
-@code{varioref} is a frequently used LaTeX package to create cross
-references with page information.  When you want to make a reference
-with the @code{\vref} macro, just press the @kbd{v} key in the selection
-buffer to toggle between the @code{\ref} and @code{\vref}
+@vindex reftex-vref-is-default
+@code{varioref} is a frequently used LaTeX package to create
+cross--references with page information.  When you want to make a
+reference with the @code{\vref} macro, just press the @kbd{v} key in the
+selection buffer to toggle between the @code{\ref} and @code{\vref}
 (@pxref{Referencing Labels}).  The mode line of the selection buffer
 shows the current status of this switch.  If you find that you almost
 always use @code{\vref}, you may want to make it the default by
-customizing the variable @var{reftex-vref-is-default}@refill
-
-@node Citations, RefTeXs Menu, Labels and References, Top
+customizing the variable @code{reftex-vref-is-default}.@refill
+
+@node Citations, Viewing Cross-References, Labels and References, Top
 @chapter Citations
 @cindex Citations
 @cindex @code{\cite}
 @menu
 * Creating Citations::               How to create them.
 * Citation Styles::                  Natbib, Harvard, Chicago and CO.
-* Displaying Citations::             View the corresponding database entry.
+* Citation Info::                    View the corresponding database entry.
 * Chapterbib and Bibunits::          Multiple bibliographies in a Document.
 * Citations Outside LaTeX::          How to make citations in Emails etc.
 @end menu
 @code{thebibliography} environment, @b{Ref@TeX{}} will collect its
 information from there.  Note that in this case the information
 presented in the selection buffer will just be a copy of relevant
-@code{\bibitems}, not the structured listing available with BibTeX
-database files.@refill
-
+@code{\bibitem} entries, not the structured listing available with
+BibTeX database files.@refill
+
+@kindex ?
 In the selection buffer, the following keys provide special commands.  A
 summary of this information is always available from the selection
 process by pressing @kbd{?}.@refill
 which the selection process was started.@refill
 
 @item mouse-2
+@vindex reftex-highlight-selection
 Clicking with mouse button 2 on a citation will accept it like @key{RET}
-would.  See also variable @var{reftex-highlight-selection}, @ref{Options
+would.  See also variable @code{reftex-highlight-selection}, @ref{Options
 (Misc)}.@refill
 
 @item ?
 Show a summary of the available keys.
 @end table
 
+@vindex reftex-select-bib-map
 In order to define additional commands for this selection process, the
-keymap @var{reftex-select-bib-map} may be used.@refill
-
-@node Citation Styles, Displaying Citations, Creating Citations, Citations
+keymap @code{reftex-select-bib-map} may be used.@refill
+
+@node Citation Styles, Citation Info, Creating Citations, Citations
 @section Citation Styles
 @cindex Citation styles
 @cindex Citation styles, @code{natbib}
 @cindex @code{harvard}, citation style
 @cindex @code{chicago}, citation style
 
+@vindex reftex-cite-format
 The standard LaTeX macro @code{\cite} works well with numeric or simple
 key citations.  To deal with the more complex task of author-year
 citations as used in many natural sciences, a variety of packages has
 been developed which define derived forms of the @code{\cite} macro.
 @b{Ref@TeX{}} can be configured to produce these citation macros as well by
-setting the variable @var{reftex-cite-format}.  For the most commonly
+setting the variable @code{reftex-cite-format}.  For the most commonly
 used packages (@code{natbib}, @code{harvard}, @code{chicago}) this may
-be done from the menu, under @code{Ref->Options->Citations}.  Since there
+be done from the menu, under @code{Ref->Citation Styles}.  Since there
 are usually several macros to create the citations, executing
 @code{reftex-citation} (@kbd{C-c [}) starts by prompting for the correct
-macro.  For the Harvard style, this looks like this:
+macro.  For the Natbib style, this looks like this:
 
 @example
 SELECT A CITATION FORMAT
 
 [^M]   \cite@{%l@}
-[p]    \cite@{%l@}
-[t]    \citeasnoun@{%l@}
-[n]    \citeasnoun@{%l@}
-[s]    \possessivecite@{%l@}
-[e]    \citeaffixed@{%l@}@{?@}
+[t]    \citet@{%l@}
+[T]    \citet*@{%l@}
+[p]    \citep@{%l@}
+[P]    \citep*@{%l@}
+[e]    \citep[e.g.][]@{%l@}
+[s]    \citep[see][]@{%l@}
+[a]    \citeauthor@{%l@}
+[A]    \citeauthor*@{%l@}
 [y]    \citeyear@{%l@}
-[a]    \citename@{%l@}
 @end example
 
 Following the most generic of these packages, @code{natbib}, the builtin
 earlier (Jones et al, 1997)}).@refill
 
 To make one of these styles the default, customize the variable
-@var{reftex-cite-format} or put into @file{.emacs}:
+@code{reftex-cite-format} or put into @file{.emacs}:
 
 @lisp
 (setq reftex-cite-format 'natbib)
 document.  @xref{Style Files} for information on how to set up the style
 files correctly.@refill
 
-@node Displaying Citations, Chapterbib and Bibunits, Citation Styles, Citations, Top
-@section Displaying Citations
+@node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top
+@section Citation Info
 @cindex Displaying citations
 @cindex Citations, displaying
+@cindex Citation info
 @cindex Viewing citations
 @kindex C-c &
+@kindex S-mouse-2
 @findex reftex-view-crossref
 @findex reftex-mouse-view-crossref
 
-@b{Ref@TeX{}} can display the full database entry for any citation key
-used in the document.  With the cursor on the argument of a @code{\cite}
-macro, type @kbd{C-c &}.  Or click with @kbd{S-mouse-2} on the argument
-of the macro.  @b{Ref@TeX{}} will show the full database entry in
-another window.@refill
-
-@b{Ref@TeX{}} also uses the echo area to display short information about
-the citation whenever the cursor is inside the argument of a
-@code{\cite} macro.  Note that the information is only displayed if the
-echo area is not occupied by a different message.  You can toggle this
-feature from the menu @w{(@code{Ref->Options->Crossref Viewing})}.  To
-turn it off or change its behavior, see the variable
-@var{reftex-auto-view-crossref}.@refill
-
-See also @ref{Displaying Cross References}.
-
-@node Chapterbib and Bibunits, Citations Outside LaTeX, Displaying Citations, Citations
+When point is idle on the argument of a @code{\cite} macro, the echo area
+will display some information about the article cited there.  Note
+that the information is only displayed if the echo area is not occupied
+by a different message.  
+
+@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database
+entry corresponding to a @code{\cite} macro, or all citation locations
+corresponding to a @code{\bibitem} or BibTeX database entry.
+@xref{Viewing Cross-References} for more information.@refill
+
+@node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations
 @section Chapterbib and Bibunits
 @cindex @code{chapterbib}, LaTeX package
 @cindex @code{bibunits}, LaTeX package
 @node Citations Outside LaTeX, , Chapterbib and Bibunits, Citations
 @section Citations outside LaTeX
 @cindex Citations outside LaTeX
+@vindex reftex-default-bibliography
 
 The command @code{reftex-citation} can also be executed outside a LaTeX
 buffer.  This can be useful to reference articles in the mail buffer and
 other documents.  You should @emph{not} enter @code{reftex-mode} for
 this, just execute the command.  The list of BibTeX files will in this
-case be taken from the variable @var{reftex-default-bibliography}.
-Setting the variable @var{reftex-cite-format} to the symbol
+case be taken from the variable @code{reftex-default-bibliography}.
+Setting the variable @code{reftex-cite-format} to the symbol
 @code{locally} does a decent job of putting all relevant information
 about a citation directly into the buffer.  Here is the lisp code to add
 the @kbd{C-c [} binding to the mail buffer.  It also provides a local
-binding for @var{reftex-cite-format}.@refill
+binding for @code{reftex-cite-format}.@refill
 
 @lisp
 (add-hook
        (let ((reftex-cite-format 'locally))
          (reftex-citation))))))
 @end lisp
+
+@node Viewing Cross-References, RefTeXs Menu, Citations, Top
+@chapter Viewing Cross--References
+@findex reftex-view-crossref
+@findex reftex-mouse-view-crossref
+@kindex C-c &
+@kindex S-mouse-2
+
+@b{Ref@TeX{}} can display cross--referencing information.  This means,
+if two document locations are linked, @b{Ref@TeX{}} can display the
+matching location(s) in another window.  The @code{\label} and @code{\ref}
+macros are one way of estabishing such a link.  Also, a @code{\cite}
+macro is linked to the corresponding @code{\bibitem} macro or a BibTeX
+database entry.
+
+The feature is invoked by pressing @kbd{C-c &}
+(@code{reftex-view-crossref}) while point is on the @var{key} argument
+of a macro involved in cross--referencing.  You can also click with
+@kbd{S-mouse-2} on the macro argument.  Here is what will happen for
+individual classes of macros:
+
+@table @asis
+
+@item @code{\ref}
+@cindex @code{\ref}
+Display the corresponding label definition.  All usual
+variants@footnote{all macros that either start or end with @samp{ref}}
+of the @code{\ref} macro are active for cross--reference display.  This
+works also for labels defined in an external document when the current
+document refers to them through the @code{xr} interface (@pxref{xr (LaTeX
+package)}).
+
+@item @code{\label}
+@cindex @code{\label}
+@vindex reftex-label-alist
+Display a document location which references this label.  Pressing
+@kbd{C-c &} several times moves through the entire document and finds
+all locations.  Not only the @code{\label} macro but also other macros
+with label arguments (as configured with @code{reftex-label-alist}) are
+active for cross--reference display.
+
+@item @code{\cite}
+@cindex @code{\cite}
+Display the corresponding BibTeX database entry or @code{\bibitem}.
+All usual variants@footnote{all macros that either start or end with
+@samp{cite}} of the @code{\cite} macro are active for cross--reference
+display.
+
+@item @code{\bibitem}
+@cindex @code{\bibitem}
+Display a document location which cites this article. Pressing
+@kbd{C-c &} several times moves through the entire document and finds
+all locations.
+
+@item BibTeX
+@cindex BibTeX buffer, viewing cite locations from
+@cindex Viewing cite locations from BibTeX buffer
+@kbd{C-c &} is also active in BibTeX buffers.  All locations in a
+document where the database entry at point is cited will be displayed.
+On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to
+the document you want to search.  Subsequent calls will use the same
+document, unless you break this link with a prefix argument to @kbd{C-c
+&}.
+
+@item @code{\index}
+@cindex @code{\index}
+Display other locations in the document which are marked by the same
+index entry.  The standard @code{\index} macro as well as many
+variants@footnote{all macros which contain either @samp{index} or
+@samp{idx} in their name} will be recognized.
+@end table
+
+@vindex reftex-view-crossref-macros
+While the display of cross reference information for citations and
+labels is hard--coded within @b{Ref@TeX{}}, the @samp{\index} stuff is
+configured in the variable @code{reftex-view-crossref-macros}.  You can
+customize this variable to add other sets of macros for which the
+display of cross--referencing information can be useful.
     
 @iftex
 @chapter All the Rest
 @end iftex
 
-@node RefTeXs Menu, Keybindings, Citations, Top
+@node RefTeXs Menu, Keybindings, Viewing Cross-References, Top
 @section @b{Ref@TeX{}}'s Menu
 @cindex RefTeXs Menu
 @cindex Menu, in the menu bar
 
-@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems which
-support this.  From this menu you can access all of @b{Ref@TeX{}}'s
-commands and some of its options.  Note, however, that setting options
-in the menu is not permanent but applies only to the current editing
-session.  To make permanent changes, use Emacs Lisp in @file{.emacs}, or
-use @code{Customize}.
+@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems
+which support this.  From this menu you can access all of
+@b{Ref@TeX{}}'s commands and a few of its options.  There is also a
+@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s
+entire set of options.@refill
 
 @node Keybindings, Faces, RefTeXs Menu, Top
 @section Default Keybindings
 
 Here is a summary of the available keybindings.
 
+@kindex C-c =
+@kindex C-c (
+@kindex C-c )
+@kindex C-c [
+@kindex C-c &
+@kindex S-mouse-2
 @example
 @kbd{C-c =}      @code{reftex-toc}
 @kbd{C-c (}      @code{reftex-label}
 (setq reftex-extra-bindings t)
 @end lisp
 
+@vindex reftex-load-hook
 Changing and adding to @b{Ref@TeX{}}'s keybindings is best done in the hook
-@var{reftex-load-hook}.  For information on the keymaps
+@code{reftex-load-hook}.  For information on the keymaps
 which should be used to add keys, see @ref{Keymaps and Hooks}.
 
 @node Faces, AUCTeX, Keybindings, Top
 @vindex tex-main-file
 @vindex TeX-master
 All files belonging to a multifile document should have a File Variable
-(@var{TeX-master} for AUCTeX or @var{tex-main-file} for the
+(@code{TeX-master} for AUCTeX or @code{tex-main-file} for the
 standard Emacs LaTeX mode) set to the name of the master file.  See the
 documentation of your (La)TeX mode and @ref{File Variables,,,emacs, The
 GNU Emacs Manual}.@refill
 
 @itemize @bullet
 @item
+@vindex reftex-derive-label-parameters
+@vindex reftex-abbrev-parameters
 The mechanism to derive a label from context includes the abbreviation
 of words and omission of unimportant words.  These mechanisms may have
 to be changed for other languages.  See the variables
-@var{reftex-derive-label-parameters} and @var{reftex-abbrev-parameters}.
+@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}.
 
 @item
+@vindex reftex-translate-to-ascii-function
+@vindex reftex-label-illegal-re
 Also, when a label is derived from context, @b{Ref@TeX{}} clears the
 context string from non-ASCII characters in order to make a legal
 label.  If you are using a special version of @TeX{} which allows
 extended characters @emph{in labels}, then you should look at the
-variables @var{reftex-translate-to-ascii-function} and
-@var{reftex-label-illegal-re}.
+variables @code{reftex-translate-to-ascii-function} and
+@code{reftex-label-illegal-re}.
 
 @item
 When a label is referenced, @b{Ref@TeX{}} looks at the word before point
 @b{Multiple Selection Buffers}@*
 @cindex Multiple selection buffers
 @cindex Selection buffers, multiple
-Normally, the selection buffer @code{*RefTeX Select*} is re-created for
+Normally, the selection buffer @file{*RefTeX Select*} is re-created for
 every selection process.  In documents with very many labels this can
 take several seconds.  @b{Ref@TeX{}} provides an option to create a
 separate selection buffer for each label type and to keep this buffer
 @cindex @code{AUCTeX}, Emacs package
 @cindex Emacs packages, @code{AUCTeX}
 
-AUCTeX is without doubt the best major mode for editing TeX and
-LaTeX files with Emacs.  AUCTeX is part of the XEmacs
-distribution.  It is also available from
-
-@example
-http://www.sunsite.auc.dk/auctex/
-@end example
-
+AUCTeX is without doubt the best major mode for editing TeX and LaTeX
+files with Emacs.  AUCTeX is part of the XEmacs distribution.  It is
+also available from the @uref{http://www.sunsite.auc.dk/auctex/,AUCTeX
+distribution site}.
 
 @menu
 * AUCTeX-RefTeX Interface::          How both packages work together