master 26e786af: Annotate labels during completion

[Arash Esbati]

branch: master
commit 26e786af634ee896296d65236de2691a6a989e98
Author: Arash Esbati <arash@gnu.org>
Commit: Arash Esbati <arash@gnu.org>

    Annotate labels during completion
    
    * latex.el (LaTeX-completion-label-list): New function returning a
    list of labels in the current document for completion.
    (LaTeX-completion-label-annotation-function): New function
    calculating the annotation attached to the labels.
    (LaTeX-label-annotation-max-length): New custom variable.
    (LaTeX-mode-cleanup): Use the new function
    `LaTeX-completion-label-list' in `TeX-complete-list'.
    
    * style/fancyref.el ("fancyref"):
    * style/ltugboat.el ("ltugboat"):
    * style/nameref.el ("nameref"):
    * style/varioref.el ("varioref"): Adjust additions to
    `TeX-complete-list'.
    
    * tex.el (TeX--completion-at-point): Extend the choice for the
    value of :annotation-function property based on the returned value
    `TeX--complete-find-entry'.
    
    * doc/auctex.texi (Completion): Document the new feature.
---
 doc/auctex.texi    | 11 +++++++++++
 latex.el           | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 style/fancyref.el  |  4 ++--
 style/ltugboat.el  |  5 +++--
 style/nameref.el   |  5 +++--
 style/subfigure.el |  5 +++--
 style/varioref.el  | 12 ++++--------
 tex.el             | 10 ++++++++--
 8 files changed, 85 insertions(+), 21 deletions(-)

diff --git a/doc/auctex.texi b/doc/auctex.texi
index 1e2303d6..99488bf4 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -1365,6 +1365,17 @@ candidate, multiple candidates separated by commas, or 
key-value
 candidates separated by commas and/or equal signs.
 @end defun
 
+Sometimes the list of offered candidates is enriched by annotations which
+are appended to the candidates themself.  For labels which are referenced,
+the annotations are controlled by the variable
+@code{LaTeX-label-annotation-max-length} and Ref@TeX{} being enabled in
+the buffer since the annotations are gathered from it.
+
+@defopt LaTeX-label-annotation-max-length
+Controls the length of the annotation attached to a label, default is 30.
+Setting this variable to 0 disables annotation of labels.
+@end defopt
+
 A more direct way to insert a macro is with @code{TeX-insert-macro},
 bound to @kbd{C-c C-m} which is equivalent to @kbd{C-c @key{RET}}.  It
 has the advantage over completion that it knows about the argument of
diff --git a/latex.el b/latex.el
index e385934b..f86e6ebe 100644
--- a/latex.el
+++ b/latex.el
@@ -8112,6 +8112,54 @@ function `TeX--completion-at-point' which should come 
first in
             ;; Any other constructs?
             (t nil)))))
 
+;; The next defcustom and functions control the annotation of labels
+;; during in-buffer completion which is done by
+;; `TeX--completion-at-point' also inside the arguments of \ref and
+;; such and not with the code above.
+
+(defcustom LaTeX-label-annotation-max-length 30
+  "Maximum number of characters for annotation of labels.
+Setting this variable to 0 disables label annotation during
+in-buffer completion."
+  :group 'LaTeX-label
+  :type 'integer)
+
+(defun LaTeX-completion-label-annotation-function (label)
+  "Return context for LABEL in a TeX file.
+Context is a string gathered from RefTeX.  Return nil if
+`LaTeX-label-annotation-max-length' is set to 0 or RefTeX-mode is
+not activated.  Context is stripped to the number of characters
+defined in `LaTeX-label-annotation-max-length'."
+  (when (and (bound-and-true-p reftex-mode)
+             (> LaTeX-label-annotation-max-length 0)
+             (boundp 'reftex-docstruct-symbol))
+    (let ((docstruct (symbol-value reftex-docstruct-symbol))
+          s)
+      (and (setq s (nth 2 (assoc label docstruct)))
+           (concat " "
+                   (string-trim-right
+                    (substring s 0 (when (>= (length s)
+                                             LaTeX-label-annotation-max-length)
+                                     LaTeX-label-annotation-max-length))))))))
+
+(defun LaTeX-completion-label-list ()
+  "Return a list of defined labels for in-buffer completion.
+This function checks if RefTeX mode is activated and extracts the
+labels from there.  Otherwise the AUCTeX label list is returned.
+If the list of offered labels is out of sync, re-parse the
+document with `reftex-parse-all' or `TeX-normal-mode'."
+  (if (and (bound-and-true-p reftex-mode)
+           (fboundp 'reftex-access-scan-info)
+           (boundp 'reftex-docstruct-symbol))
+      (progn
+        (reftex-access-scan-info)
+        (let ((docstruct (symbol-value reftex-docstruct-symbol))
+              labels)
+          (dolist (label docstruct labels)
+            (when (stringp (car label))
+              (push (car label) labels)))))
+    (LaTeX-label-list)))
+
 ;;; Mode
 
 (defgroup LaTeX-macro nil
@@ -8254,9 +8302,9 @@ Run after mode hooks and file local variables 
application."
                   ("\\\\nocite{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-bibitem-list "}")
                   ("\\\\nocite{\\([^{}\n\r\\%]*,\\)\\([^{}\n\r\\%,]*\\)"
                    2 LaTeX-bibitem-list)
-                  ("\\\\[Rr]ef{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")
-                  ("\\\\eqref{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")
-                  ("\\\\pageref{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")
+                  ("\\\\[Rr]ef{\\([^{}\n\r\\%,]*\\)" 1 
LaTeX-completion-label-list "}")
+                  ("\\\\eqref{\\([^{}\n\r\\%,]*\\)" 1 
LaTeX-completion-label-list "}")
+                  ("\\\\pageref{\\([^{}\n\r\\%,]*\\)" 1 
LaTeX-completion-label-list "}")
                   ("\\\\\\(index\\|glossary\\){\\([^{}\n\r\\%]*\\)"
                    2 LaTeX-index-entry-list "}")
                   ("\\\\begin{\\([A-Za-z]*\\)" 1 
LaTeX-environment-list-filtered "}")
diff --git a/style/fancyref.el b/style/fancyref.el
index 22fd1c17..a94c60b3 100644
--- a/style/fancyref.el
+++ b/style/fancyref.el
@@ -1,6 +1,6 @@
 ;;; fancyref.el --- AUCTeX style file with support for fancyref.sty  -*- 
lexical-binding: t; -*-
 
-;; Copyright (C) 1999, 2014, 2015, 2018, 2020 Free Software Foundation, Inc.
+;; Copyright (C) 1999--2024 Free Software Foundation, Inc.
 
 ;; Author: Carsten Dominik <dominik@strw.leidenuniv.nl>
 ;; Maintainer: auctex-devel@gnu.org
@@ -91,7 +91,7 @@
    (setq TeX-complete-list
          (append
           '(("\\\\[fF]ref\\(\\[[^]]*\\]\\)?{\\([^{}\n\r\\%,]*\\)" 
-             2 LaTeX-label-list "}")
+             2 LaTeX-completion-label-list "}")
             ("\\\\[fF]ref\\[\\([^{}\n\r\\%,]*\\)" 
              1 LaTeX-fancyref-formats "]")
             ("\\\\[fF]refformat{\\([^{}\n\r\\%,]*\\)"
diff --git a/style/ltugboat.el b/style/ltugboat.el
index 85866df9..c6eb07d0 100644
--- a/style/ltugboat.el
+++ b/style/ltugboat.el
@@ -1,6 +1,6 @@
 ;;; ltugboat.el --- AUCTeX style for `ltugboat.cls' (v2.28)  -*- 
lexical-binding: t; -*-
 
-;; Copyright (C) 2019--2023 Free Software Foundation, Inc.
+;; Copyright (C) 2019--2024 Free Software Foundation, Inc.
 
 ;; Author: Arash Esbati <arash@gnu.org>
 ;; Maintainer: auctex-devel@gnu.org
@@ -61,7 +61,8 @@
 
    (setq TeX-complete-list
          (append
-          '(("\\\\nameref{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}"))
+          '(("\\\\nameref{\\([^{}\n\r\\%,]*\\)"
+             1 LaTeX-completion-label-list "}"))
           TeX-complete-list))
 
    ;; 6.1 Abstracts
diff --git a/style/nameref.el b/style/nameref.el
index d4c7b10e..22518610 100644
--- a/style/nameref.el
+++ b/style/nameref.el
@@ -1,6 +1,6 @@
 ;;; nameref.el --- AUCTeX style for `nameref.sty'  -*- lexical-binding: t; -*-
 
-;; Copyright (C) 2013--2023 Free Software Foundation, Inc.
+;; Copyright (C) 2013--2024 Free Software Foundation, Inc.
 
 ;; Author: Mads Jensen <mje@inducks.org>
 ;; Maintainer: auctex-devel@gnu.org
@@ -46,7 +46,8 @@
 
    (setq TeX-complete-list
          (append
-          '(("\\\\\\(?:N\\|n\\)ameref\\*?{\\([^{}\n\r\\%,]*\\)" 1 
LaTeX-label-list "}"))
+          '(("\\\\\\(?:N\\|n\\)ameref\\*?{\\([^{}\n\r\\%,]*\\)"
+             1 LaTeX-completion-label-list "}"))
           TeX-complete-list))
 
    ;; Fontification
diff --git a/style/subfigure.el b/style/subfigure.el
index 181b17c0..55c9c851 100644
--- a/style/subfigure.el
+++ b/style/subfigure.el
@@ -1,6 +1,6 @@
 ;;; subfigure.el --- AUCTeX style file for subfigure.sty  -*- lexical-binding: 
t; -*-
 
-;; Copyright (C) 2003, 2005, 2013, 2018, 2020 Free Software Foundation, Inc.
+;; Copyright (C) 2003--2024 Free Software Foundation, Inc.
 
 ;; Author: Reiner Steib  <Reiner.Steib@gmx.de>
 ;; Maintainer: auctex-devel@gnu.org
@@ -55,7 +55,8 @@
    ;; Install completion for labels:
    (setq TeX-complete-list
          (append
-          '(("\\\\[Ss]ubref{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}"))
+          '(("\\\\[Ss]ubref{\\([^{}\n\r\\%,]*\\)"
+             1 LaTeX-completion-label-list "}"))
           TeX-complete-list))
 
    ;; Fontification
diff --git a/style/varioref.el b/style/varioref.el
index 32134c1d..82bcaf31 100644
--- a/style/varioref.el
+++ b/style/varioref.el
@@ -1,6 +1,6 @@
 ;;; varioref.el --- AUCTeX style for `varioref.sty' (v1.6b)  -*- 
lexical-binding: t; -*-
 
-;; Copyright (C) 1999, 2013, 2015, 2018--2020 Free Software Foundation, Inc.
+;; Copyright (C) 1999--2024 Free Software Foundation, Inc.
 
 ;; Author: Carsten Dominik <dominik@strw.leidenuniv.nl>
 ;;         Mads Jensen <mje@inducks.org>
@@ -69,16 +69,12 @@
 
    ;; Install completion for labels.  Only offer completion for
    ;; commands that take only one reference as an argument
-   ;; FIXME: The first 3 entries can be reduced to
-   ;; ("\\\\[Vv]ref\\*?{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")  ???
    (setq TeX-complete-list
          (append
-          '(("\\\\[Vv]ref{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")
-            ("\\\\vref\\*?{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")
-            ("\\\\vref\\*{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")
-            ("\\\\fullref{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-label-list "}")
+          '(("\\\\[Vv]ref\\*?{\\([^{}\n\r\\%,]*\\)" 1 
LaTeX-completion-label-list "}")
+            ("\\\\fullref{\\([^{}\n\r\\%,]*\\)" 1 LaTeX-completion-label-list 
"}")
             ("\\\\vpageref\\*?\\(\\[[^]]*\\]\\)*{\\([^{}\n\r\\%,]*\\)"
-             2 LaTeX-label-list "}"))
+             2 LaTeX-completion-label-list "}"))
           TeX-complete-list))
 
    ;; Fontification
diff --git a/tex.el b/tex.el
index 3132472e..eeb7237c 100644
--- a/tex.el
+++ b/tex.el
@@ -56,6 +56,8 @@
                   (bus service path interface signal handler &rest args))
 (declare-function LaTeX-environment-list "latex" nil)
 (declare-function LaTeX-bibliography-list "latex" nil)
+(declare-function LaTeX-completion-label-annotation-function "latex" (label))
+(declare-function LaTeX-completion-label-list "latex" nil)
 (declare-function LaTeX-section-name "latex" (level))
 (declare-function comint-exec "ext:comint"
                   (buffer name command startfile switches))
@@ -3234,10 +3236,14 @@ See `completion-at-point-functions'."
                  (begin (match-beginning sub))
                  (end (match-end sub))
                  (symbol (buffer-substring-no-properties begin end))
-                 (list (funcall (nth 2 entry))))
+                 (func (nth 2 entry))
+                 (list (funcall func)))
             (list begin end (all-completions symbol list)
                   :annotation-function
-                  #'TeX--completion-annotation-function))
+                  (cond ((eq func #'LaTeX-completion-label-list)
+                         #'LaTeX-completion-label-annotation-function)
+                        (t
+                         #'TeX--completion-annotation-function))))
         ;; We intentionally don't call the fallback completion functions 
because
         ;; they do completion on their own and don't work too well with things
         ;; like company-mode.  And the default function `ispell-complete-word'