diff --git a/NEWS.org b/NEWS.org
index 28248d04cdb..8bc91039c02 100644
--- a/NEWS.org
+++ b/NEWS.org

@@ -12,7 +12,13 @@

** Added

- Activate new TeX xref backend (~tex-etags~) provided by Emacs 31.

-

+- Add support for in-buffer completion of citation keys for various

+ =\cite= macros. The length of the annotations attached to the keys is

+ controlled by the new option ~LaTeX-bib-annotation-max-length~. The

+ annotations are offered only when RefTeX-mode in activated. Multicite

+ commands (Qualified Citation Lists) from the biblatex package are not

+ supported.

+- Improve in-buffer completion of referencing macros.

- Add new support files =style/handstroke.el=, =style/lineno.el=,

=style/lua-unicode-math.el=, =style/sourcesans.el= and

=style/sourceserif.el=.

@@ -53,10 +59,8 @@

- Add new command ~LaTeX-repeat-recent-math~ which looks backward for a

recent top-level display math construct and inserts a copy to the

current line.

-

- Add new support files =style/floatflt.el=, =style/fontawesome7.el= and

=style/ltx-talk.el=.

-

- Add new function ~preview-dvisvgm-command~ to generate SVG images in

preview.

@@ -64,17 +68,13 @@

- Change the format of the value stored in ~preview-dumped-alist~. Add

a new optional argument to the function ~preview-watch-preamble~.

-

- Respect the value of ~font-latex-fontify-sectioning~ when fontifying

macros as =slide-title=. This affects macros provided by

=style/beamer.el= and =style/ltx-talk.el=.

-

- Change the name of ~preview-dvipng-command~ to ~preview-dvi*-command~.

Also make it accept a function symbol returning the full command.

-

- Change the name of ~preview-dvipng-image-type~ to

~preview-dvi*-image-type~.

-

- Change the setting of ~preview-image-creators~ and

~preview-gs-image-type-alist~ to use ~dvi*~ instead of ~dvipng~.

@@ -128,19 +128,15 @@

publication years, like =[Ne21]= or =[ABC99]=. These are extracted

from any bib files referenced in the document or specified by the user

option ~TeX-fold-bib-file~.

-

- Add support for folding of =\begin{env}= and =\end{env}= macros. The

replacement specifiers are controlled by the custom option

~TeX-fold-begin-end-spec-list~.

-

- Add new custom option ~TeX-fold-alert-color~ which determines the

color used when folding the ~\alert~ macro, defaults to ~red~.

-

- Add new support files =style/glossaries-extra.el=,

=style/glossaries.el=, =style/inlinegraphicx.el=, =style/minted2.el=

(=style/minted.el= is updated to package v3.1.2) and

=style/stocksize.el=.

-

- Add preliminary support for parsing =\graphicspath= in

=style/graphicx.el=.

@@ -156,7 +152,6 @@

- Respect the value of ~TeX-output-dir~ when processing files with

latexmk. This means that the default value of ~TeX-command-list~ is

changed.

-

- Add new support files =style/authblk.el=, =style/langscibook.cls=,

=style/lstautogobble.el=, =style/lstlinebgrd.el=,

=style/ninecolors.el=, =style/supertabular.el=, =style/tabularray.el=

@@ -178,7 +173,6 @@

For users who tracked the master branch: Do =git switch main= to

switch to the main branch where development takes place nowadays.

-

- Move additions to the variable ~LaTeX-indent-environment-list~ for

various tabular environments to =latex.el= from the respective style

files.

@@ -439,5 +433,4 @@

~japanese-LaTeX-mode-map~, ~japanese-plain-TeX-mode-hook~,

~japanese-LaTeX-mode-hook~, ~japanese-plain-TeX-mode-abbrev-table~,

~japanese-LaTeX-mode-abbrev-table~.

-

- AUCTeX now requires GNU Emacs 27.1 or higher.

diff --git a/doc/auctex.texi b/doc/auctex.texi
index 756fdb9dd38..07ad346c9e8 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi

@@ -1526,14 +1526,20 @@ candidates separated by commas and/or equal signs.

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.

+@code{LaTeX-label-annotation-max-length}. For citation keys, the variable

+@code{LaTeX-bib-annotation-max-length} is consulted. Ref@TeX{} must be

+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

+@defopt LaTeX-bib-annotation-max-length

+Controls the length of the annotation attached to a citation key, default

+is 50. Setting this variable to 0 disables annotation of citation keys.

+@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 71689429381..06087c516cf 100644
--- a/latex.el
+++ b/latex.el

@@ -32,16 +32,28 @@

(require 'latex-flymake)

;; Silence the compiler for functions:

+(declare-function LaTeX-install-toolbar "tex-bar" nil)

(declare-function multi-prompt "multi-prompt")

(declare-function multi-prompt-key-value "multi-prompt")

-(declare-function LaTeX-install-toolbar "tex-bar" nil)

(declare-function outline-level "ext:outline" nil)

(declare-function outline-mark-subtree "ext:outline" nil)

+(declare-function reftex--query-search-regexps "ext:reftex-cite")

+(declare-function reftex-access-scan-info "ext:reftex")

+(declare-function reftex-all-assq "ext:reftex")

+(declare-function reftex-bib-or-thebib "ext:reftex-cite")

+(declare-function reftex-default-bibliography "ext:reftex-cite")

+(declare-function reftex-extract-bib-entries "ext:reftex-cite")

+(declare-function reftex-extract-bib-entries-from-thebibliography "ext:reftex-cite")

+(declare-function reftex-get-bib-field "ext:reftex-cite")

+(declare-function reftex-get-bibfile-list "ext:reftex-cite")

+(declare-function reftex-uniquify "ext:reftex")

(declare-function turn-off-filladapt-mode "ext:filladapt" nil)

;; Silence the compiler for variables:

-(defvar outline-heading-alist)

(defvar LaTeX-section-list-changed)

+(defvar outline-heading-alist)

+(defvar reftex-default-bibliography)

+(defvar reftex-docstruct-symbol)

;;; Syntax

@@ -8078,7 +8090,8 @@ only mapping for functions which perform key=val completions. See also

`LaTeX-completion-function-map-alist-crm'.")

(defvar LaTeX-completion-function-map-alist-crm

- '((TeX-arg-ref . LaTeX-completion-label-list))

+ '((TeX-arg-ref . LaTeX-completion-label-list)

+ (TeX-arg-cite . LaTeX-completion-bib-list))

"Alist mapping style funcs to completion-candidates counterparts.

Each element is a cons with the name of the function used in an AUCTeX

style file which queries and inserts something in the buffer as car and

@@ -8104,7 +8117,9 @@ only mapping for functions which perform completing-read. See also

(defvar LaTeX-completion-extra-props-alist

'((LaTeX-completion-label-list (:annotation-function

- LaTeX-completion-label-annotation-function)))

+ LaTeX-completion-label-annotation-function))

+ (LaTeX-completion-bib-list (:annotation-function

+ LaTeX-completion-bib-annotation-function)))

"Alist of extra properties for in-buffer completion.

The car of each element is a function which returns completion

candidates. The cdr is a list of extra properties passed to

@@ -8223,7 +8238,8 @@ function `TeX--completion-at-point' which should come later in

;; The next defcustom and functions control the annotation of labels

;; during in-buffer completion which is done by

;; `TeX--completion-at-point' inside the arguments of \ref and such as

-;; well as with `TeX-arg-ref'

+;; well as with `TeX-arg-ref'. For the bib entries, we cater for

+;; `TeX-arg-cite':

(defcustom LaTeX-label-annotation-max-length 30

"Maximum number of characters for annotation of labels.

@@ -8268,6 +8284,71 @@ document with `reftex-parse-all' or `TeX-normal-mode'."

(push (car label) labels)))))

(LaTeX-label-list)))

+(defcustom LaTeX-bib-annotation-max-length 50

+ "Maximum number of characters for annotation of bib entries.

+Setting this variable to 0 disables annotation of bib entries during

+in-buffer completion."

+ :group 'LaTeX-label

+ :type 'integer)

+

+(defvar-local LaTeX--completion-bib-list-from-reftex nil

+ "List of bib entries retrieved from RefTeX.

+The value is set in `LaTeX-completion-bib-list' and used in

+`LaTeX-completion-bib-annotation-function'.")

+

+(defun LaTeX-completion-bib-list ()

+ "Return a list of bib entries in current document.

+If RefTeX is active, use its advanced mechanism, otherwise use

+`LaTeX-bibitem-list' provided by AUCTeX."

+ (if (and (bound-and-true-p reftex-mode)

+ (require 'reftex-cite nil t))

+ ;; `reftex--query-search-regexps' calls `completing-read', so

+ ;; prevent this here:

+ (cl-letf (((symbol-function #'reftex--query-search-regexps)

+ (lambda (_) '("."))))

+ (reftex-access-scan-info)

+ (setq LaTeX--completion-bib-list-from-reftex

+ ;; This part is extracted from `reftex-offer-bib-menu':

+ (pcase (reftex-bib-or-thebib)

+ ('thebib (reftex-extract-bib-entries-from-thebibliography

+ (reftex-uniquify

+ (mapcar #'cdr

+ (reftex-all-assq

+ 'thebib (symbol-value reftex-docstruct-symbol))))))

+ ('bib (reftex-extract-bib-entries (reftex-get-bibfile-list)))

+ ((pred (lambda (x) (and (null x) reftex-default-bibliography)))

+ (reftex-extract-bib-entries (reftex-default-bibliography)))))

+ (when LaTeX--completion-bib-list-from-reftex

+ (mapcar (lambda (x) (substring-no-properties (car x)))

+ LaTeX--completion-bib-list-from-reftex)))

+ (LaTeX-bibitem-list)))

+

+(defun LaTeX-completion-bib-annotation-function (key)

+ "Return context for bib KEY in a TeX file.

+Context is a string gathered from RefTeX. Context is the `title' field

+of the key stored in the bibtex database. For the \\thebibliography

+environment, the text after the \\bibitem is used.

+

+Return nil if `LaTeX-bib-annotation-max-length' is set to 0 or

+RefTeX-mode is not activated. Context is stripped to the number of

+characters defined in `LaTeX-bib-annotation-max-length'."

+ (when (and LaTeX--completion-bib-list-from-reftex

+ (bound-and-true-p reftex-mode)

+ (> LaTeX-bib-annotation-max-length 0)

+ (require 'reftex-cite nil t))

+ (let ((annot (reftex-get-bib-field

+ (if (eq (reftex-bib-or-thebib) 'thebib)

+ "&text"

+ "title")

+ (assoc key LaTeX--completion-bib-list-from-reftex))))

+ (unless (string-empty-p annot)

+ (concat " "

+ (string-trim-right

+ (substring-no-properties annot 0

+ (when (>= (length annot)

+ LaTeX-bib-annotation-max-length)

+ LaTeX-bib-annotation-max-length))))))))

+

;;; Mode

(defgroup LaTeX-macro nil