branch: externals/auctex commit fbe07828b108eaff60434713c860c1bd582a14de Author: Arash Esbati <ar...@gnu.org> Commit: Arash Esbati <ar...@gnu.org>
Add `NO-INSERT' argument to `LaTeX-label' * doc/changes.texi: Document changes to `LaTeX-label' and `LaTeX-label-function'. * latex.el (LaTeX-label): Add second optional argument NO-INSERT. This argument is passed to function bound to `LaTeX-label-function' (usually `reftex-label' with RefTeX enabled). If `LaTeX-label-function' is nil and NO-INSERT is non-nil, label is read and returned as a string. Remove some unnecessary checks. (LaTeX-label-function): Mention in docstring that the function is expected to take an optional argument NO-INSERT. This is an incompatible change. --- doc/changes.texi | 19 +++++++++++++++++++ latex.el | 34 +++++++++++++++++++--------------- 2 files changed, 38 insertions(+), 15 deletions(-) diff --git a/doc/changes.texi b/doc/changes.texi index 3cdc886..a102bbb 100644 --- a/doc/changes.texi +++ b/doc/changes.texi @@ -8,6 +8,25 @@ @end ifset +@heading News since 11.90 + +@itemize @bullet +@item +The function @code{LaTeX-label} now takes a second optional argument +@code{NO-INSERT}. When non-@code{nil}, @code{LaTeX-label} reads a label +and returns it as a string. This argument is also passed to any +function bound to @code{LaTeX-label-function} (see next item). + +@item +@strong{Incompatible change:} The signature for the function passed with +the custom variable @code{LaTeX-label-function} has changed. The +function bound to this variable is now expected to take an optional +second argument @code{NO-INSERT}. When this argument is non-@code{nil}, +the function should read and only return a label as a string; insertion +is done by another function. + +@end itemize + @heading News in 11.90 @itemize @bullet diff --git a/latex.el b/latex.el index c2aab36..32ccbbc 100644 --- a/latex.el +++ b/latex.el @@ -888,9 +888,12 @@ optional argument is omitted.)" :group 'LaTeX) (defcustom LaTeX-label-function nil - "*A function inserting a label at point. -Sole argument of the function is the environment. The function has to return -the label inserted, or nil if no label was inserted." + "*A function inserting a label at point or returning a label string. +Sole mandatory argument of the function is the environment. The +function has to return the label inserted, or nil if no label was +inserted. If the optional argument NO-INSERT is non-nil, then +the function has to return the label as string without any +insertion or nil if no label was read in." :group 'LaTeX-label :type 'function) @@ -987,7 +990,7 @@ corresponding entry." (make-variable-buffer-local 'LaTeX-label-alist) -(defun LaTeX-label (name &optional type) +(defun LaTeX-label (name &optional type no-insert) "Insert a label for NAME at point. The optional TYPE argument can be either environment or section: in the former case this function looks up `LaTeX-label-alist' to @@ -999,7 +1002,9 @@ prefix. If `LaTeX-label-function' is a valid function, LaTeX label will transfer the job to this function. -The inserted label is returned, nil if it is empty." +If the optional NO-INSERT is non-nil, only the label is returned +and no insertion happens. Otherwise the inserted label is +returned, nil if it is empty." (let ((TeX-read-label-prefix (cond ((eq type 'environment) @@ -1019,22 +1024,21 @@ The inserted label is returned, nil if it is empty." (when (symbolp TeX-read-label-prefix) (setq TeX-read-label-prefix (symbol-value TeX-read-label-prefix))) (when TeX-read-label-prefix - (if (and (boundp 'LaTeX-label-function) - LaTeX-label-function - (fboundp LaTeX-label-function)) - (setq label (funcall LaTeX-label-function name)) + (if (and (fboundp LaTeX-label-function)) + (funcall LaTeX-label-function name no-insert) ;; Use completing-read as we do with `C-c C-m \label RET' (setq label (TeX-read-label t "What label" t)) ;; No label or empty string entered? (if (or (string= TeX-read-label-prefix label) (string= "" label)) (setq label nil) - (insert TeX-esc "label" TeX-grop label TeX-grcl)) - (if label - (progn - (LaTeX-add-labels label) - label) - nil))))) + ;; If NO-INSERT, return only the label for further + ;; utilization, otherwise insert \label{label} in the buffer + (if no-insert + label + (insert TeX-esc "label" TeX-grop label TeX-grcl)) + (LaTeX-add-labels label) + label))))) (defcustom LaTeX-short-caption-prompt-length 40 "The length that the caption of a figure should be before