Function: reftex-reference

reftex-reference is an autoloaded, interactive and byte-compiled function defined in reftex-ref.el.gz.

Signature

(reftex-reference &optional TYPE NO-INSERT CUT)

Documentation

Make a LaTeX reference. Look only for labels of a certain TYPE.

With prefix arg, force to rescan buffer for labels. This should only be necessary if you have recently entered labels yourself without using reftex-label. Rescanning of the buffer can also be requested from the label selection menu. The function returns the selected label or nil. If NO-INSERT is non-nil, do not insert \ref command, just return label. When called with 2 C-u (universal-argument) prefix args, disable magic word recognition.

Probably introduced at or before Emacs version 20.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/textmodes/reftex-ref.el.gz
;;;###autoload
(defun reftex-reference (&optional type no-insert cut)
  "Make a LaTeX reference.  Look only for labels of a certain TYPE.
With prefix arg, force to rescan buffer for labels.  This should only be
necessary if you have recently entered labels yourself without using
reftex-label.  Rescanning of the buffer can also be requested from the
label selection menu.
The function returns the selected label or nil.
If NO-INSERT is non-nil, do not insert \\ref command, just return label.
When called with 2 \\[universal-argument] prefix args, disable magic word recognition."

  (interactive)

  ;; Check for active recursive edits
  (reftex-check-recursive-edit)

  ;; Ensure access to scanning info and rescan buffer if prefix is '(4)
  (reftex-access-scan-info current-prefix-arg)

  (let ((reftex-refstyle (when (and (boundp 'reftex-refstyle) reftex-refstyle)
		    reftex-refstyle))
	(reftex-format-ref-function reftex-format-ref-function)
	(form "\\ref{%s}")
	label labels sep sep1 style-alist)

    (unless reftex-refstyle
      (if reftex-ref-macro-prompt
	  (progn
	    ;; Build a temporary list which handles more easily.
	    (dolist (elt reftex-ref-style-alist)
	      (when (member (car elt) (reftex-ref-style-list))
		(mapc (lambda (x)
			(add-to-list 'style-alist (cons (cadr x) (car x)) t))
		      (nth 2 elt))))
	    ;; Prompt the user for the macro.
	    (let ((key (reftex-select-with-char
			"" (concat "SELECT A REFERENCE FORMAT\n\n"
				   (mapconcat
				    (lambda (x)
				      (format "[%c] %s  %s" (car x)
					      (if (> (car x) 31) " " "")
					      (cdr x)))
				    style-alist "\n")))))
	      (setq reftex-refstyle (cdr (assoc key style-alist)))
	      (unless reftex-refstyle
		(error "No reference macro associated with key `%c'" key))))
	;; Get the first macro from `reftex-ref-style-alist' which
	;; matches the first entry in the list of active styles.
	(setq reftex-refstyle
	      (or (caar (nth 2 (assoc (car (reftex-ref-style-list))
				      reftex-ref-style-alist)))
		  ;; Use the first entry in r-r-s-a as a last resort.
		  (caar (nth 2 (car reftex-ref-style-alist)))))))

    (unless type
      ;; Guess type from context
      (if (and reftex-guess-label-type
	       (setq type (reftex-guess-label-type)))
	  (setq cut (cdr type)
		type (car type))
	(setq type (reftex-query-label-type))))

    ;; Have the user select a label
    (set-marker reftex-select-return-marker (point))
    (setq labels (save-excursion
                   (reftex-offer-label-menu type)))
    (reftex-ensure-compiled-variables)
    (set-marker reftex-select-return-marker nil)
    ;; If the first entry is the symbol 'concat, concat all labels.
    ;; We keep the cdr of the first label for typekey etc information.
    (if (eq (car labels) 'concat)
        (setq labels (list (list (mapconcat #'car (cdr labels) ",")
                                 (cdr (nth 1 labels))))))
    (setq type (nth 1 (car labels))
          form (or (cdr (assoc type reftex-typekey-to-format-alist))
                   form))

    (cond
     (no-insert
      ;; Just return the first label
      (car (car labels)))
     ((null labels)
      (message "Quit")
      nil)
     (t
      (while labels
        (setq label (car (car labels))
              sep (nth 2 (car labels))
              sep1 (cdr (assoc sep reftex-multiref-punctuation))
              labels (cdr labels))
        (when cut
          (delete-char (- cut))
          (setq cut nil))

        ;; remove ~ if we do already have a space
        (when (and (= ?~ (string-to-char form))
                   (member (preceding-char) '(?\ ?\t ?\n ?~)))
          (setq form (substring form 1)))
        ;; do we have a special format?
	(unless (string= reftex-refstyle "\\ref")
	  (setq reftex-format-ref-function #'reftex-format-special))
        ;; ok, insert the reference
        (if sep1 (insert sep1))
        (insert
         (if reftex-format-ref-function
             (funcall reftex-format-ref-function label form reftex-refstyle)
           (format form label label)))
        ;; take out the initial ~ for good
        (and (= ?~ (string-to-char form))
             (setq form (substring form 1))))
      (message "")
      label))))