Function: reftex-label
reftex-label is an autoloaded, interactive and byte-compiled function
defined in reftex-ref.el.gz.
Signature
(reftex-label &optional ENVIRONMENT NO-INSERT)
Documentation
Insert a unique label. Return the label.
If ENVIRONMENT is given, don't bother to find out yourself. If NO-INSERT is non-nil, do not insert label into buffer. With prefix arg, force to rescan document first. When you are prompted to enter or confirm a label, and you reply with just the prefix or an empty string, no label at all will be inserted. A new label is also recorded into the label list. This function is controlled by the settings of reftex-insert-label-flags.
Probably introduced at or before Emacs version 20.1.
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/textmodes/reftex-ref.el.gz
;;; Creating labels ---------------------------------------------------------
;;;###autoload
(defun reftex-label (&optional environment no-insert)
"Insert a unique label. Return the label.
If ENVIRONMENT is given, don't bother to find out yourself.
If NO-INSERT is non-nil, do not insert label into buffer.
With prefix arg, force to rescan document first.
When you are prompted to enter or confirm a label, and you reply with
just the prefix or an empty string, no label at all will be inserted.
A new label is also recorded into the label list.
This function is controlled by the settings of reftex-insert-label-flags."
(interactive)
;; Ensure access to scanning info and rescan buffer if prefix arg is '(4).
(reftex-access-scan-info current-prefix-arg)
;; Find out what kind of environment this is and abort if necessary.
(if (or (not environment)
(not (assoc environment reftex-env-or-mac-alist)))
(setq environment (reftex-label-location)))
(unless environment
(error "Can't figure out what kind of label should be inserted"))
;; Ok, go ahead.
(catch 'exit
(let* ((entry (assoc environment reftex-env-or-mac-alist))
(typekey (nth 1 entry))
(format (nth 3 entry))
(macro-cell (reftex-what-macro 1))
(entry1 (assoc (car macro-cell) reftex-env-or-mac-alist))
label naked prefix valid default force-prompt rescan-is-useful)
(when (and (or (nth 5 entry) (nth 5 entry1))
(memq (preceding-char) '(?\[ ?\{)))
;; This is an argument of a label macro. Insert naked label.
(setq naked t format "%s"))
(setq prefix (or (cdr (assoc typekey reftex-typekey-to-prefix-alist))
(concat typekey "-")))
;; Replace any escapes in the prefix
(setq prefix (reftex-replace-prefix-escapes prefix))
;; Make a default label.
(cond
((reftex-typekey-check typekey (nth 0 reftex-insert-label-flags))
;; Derive a label from context.
(setq reftex-active-toc (reftex-last-assoc-before-elt
'toc (car (reftex-where-am-I))
(symbol-value reftex-docstruct-symbol)))
(setq default (reftex-no-props
(nth 2 (reftex-label-info " " nil nil t))))
;; Catch the cases where the is actually no context available.
(if (or (string-match "NO MATCH FOR CONTEXT REGEXP" default)
(string-match "INVALID VALUE OF PARSE" default)
(string-match "SECTION HEADING NOT FOUND" default)
(string-match "HOOK ERROR" default)
(string-match "^[ \t]*$" default))
(setq default prefix
force-prompt t) ; need to prompt
(setq default
(concat prefix
(funcall reftex-string-to-label-function default)))
;; Make it unique.
(setq default (reftex-uniquify-label default nil "-"))))
((reftex-typekey-check typekey (nth 1 reftex-insert-label-flags))
;; Minimal default: the user will be prompted.
(setq default prefix))
(t
;; Make an automatic label.
(setq default (reftex-uniquify-label prefix t))))
;; Should we ask the user?
(if (or (reftex-typekey-check typekey
(nth 1 reftex-insert-label-flags)) ; prompt
force-prompt)
(while (not valid)
;; iterate until we get a valid label
(setq label (read-string
(if naked "Naked Label: " "Label: ")
default))
;; Let's make sure that this is a valid label
(cond
((string-match (concat "\\`\\(" (regexp-quote prefix)
"\\)?[ \t]*\\'")
label)
;; No label at all, please
(message "No label inserted.")
(throw 'exit nil))
;; Test if label contains strange characters
((string-match reftex-label-illegal-re label)
(message "Label \"%s\" contains invalid characters" label)
(ding)
(sit-for 2))
;; Look it up in the label list
((setq entry (assoc label
(symbol-value reftex-docstruct-symbol)))
(ding)
(if (y-or-n-p
(format-message "Label `%s' exists. Use anyway?" label))
(setq valid t)))
;; Label is ok
(t
(setq valid t))))
(setq label default))
;; Insert the label into the label list
(let* ((here-I-am-info
(save-excursion
(if (and (or naked no-insert)
(integerp (cdr macro-cell)))
(goto-char (cdr macro-cell)))
(reftex-where-am-I)))
(here-I-am (car here-I-am-info))
(note (if (cdr here-I-am-info)
""
"POSITION UNCERTAIN. RESCAN TO FIX."))
(file (buffer-file-name))
;; (text nil)
(tail (memq here-I-am (symbol-value reftex-docstruct-symbol))))
(or (cdr here-I-am-info) (setq rescan-is-useful t))
(when tail
(push (list label typekey nil file nil note) (cdr tail))
(put reftex-docstruct-symbol 'modified t)))
;; Insert the label into the buffer
(unless no-insert
(insert
(if reftex-format-label-function
(funcall reftex-format-label-function label format)
(format format label)))
(if (and reftex-plug-into-AUCTeX
(fboundp 'LaTeX-add-labels))
;; Tell AUCTeX about this
(LaTeX-add-labels label)))
;; Delete the corresponding selection buffers to force update on next use.
(when reftex-auto-update-selection-buffers
(reftex-erase-buffer (reftex-make-selection-buffer-name typekey))
(reftex-erase-buffer (reftex-make-selection-buffer-name " ")))
(when (and rescan-is-useful reftex-allow-automatic-rescan)
(reftex-parse-one))
;; return value of the function is the label
label)))