branch: externals/auctex-label-numbers
commit 71e97e97b7cefbd3763a06237ee3e480ff292ac0
Author: Paul Nelson <ultr...@gmail.com>
Commit: Paul Nelson <ultr...@gmail.com>
clean up, bump version, add readme details
---
README.org | 40 +++++++++++++++++
tex-numbers.el | 133 +++++++++++++++++++++++++++++++--------------------------
2 files changed, 112 insertions(+), 61 deletions(-)
diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..fb26c94ebd
--- /dev/null
+++ b/README.org
@@ -0,0 +1,40 @@
+#+title: tex-numbers.el: Numbering for LaTeX previews and folds
+#+author: Paul D. Nelson
+
+* Overview
+The package provides a function, =tex-numbers-label-to-number=, that retrieves
label numbers in LaTeX documents. This function is used to implement a global
minor mode, =tex-numbers-mode=, that augments the preview and folding features
of
[[https://www.gnu.org/software/auctex/manual/auctex/Installation.html#Installation][AUCTeX]]:
+
+- Previews of labeled equations are numbered as in the compiled
+ document.
+
+- The macros =\ref=, =\eqref=, and =\label= are folded with the
+ corresponding numbers.
+
+- =completion-at-point= annotations for the contents of =\ref= and
+ =\eqref= include equation numbers.
+
+- Annotations for the command =reftex-goto-label=.
+
+* Configuration
+This package requires
[[https://www.gnu.org/software/auctex/manual/auctex/Installation.html#Installation][AUCTeX]],
so install that first.
+
+Download this repository, install using =M-x package-install-file= (or
package-vc-install, straight, elpaca, ...), and add something like the
following to your [[https://www.emacswiki.org/emacs/InitFile][init file]]:
+#+begin_src elisp
+ (use-package tex-numbers
+ :after latex
+ :config
+ (tex-numbers-mode 1))
+#+end_src
+With this, the package activates automatically.
+
+You could alternatively use simply =(use-package tex-numbers)= and activate
via =M-x tex-numbers-mode= or =(tex-numbers-mode 1)= whenever you'd like (e.g.,
in the middle of some other customizations of =TeX-fold-mode=). If you'd like
to enable some (but not all) of the provided functionality, then you can
extract from the definition of =tex-numbers-mode= the pieces that you'd like
and put those in your config.
+
+* Usage
+The label numbers are retrieved from the aux file of the compiled document.
To update them, one should compile the document, regenerate the previews and
refresh the folds.
+
+The previews should be numbered automated. To activate the folds, you'll want
to make sure =TeX-fold-mode= is enabled (=C-c C-o C-f= to toggle) and then fold
the buffer (=C-c C-o C-b=) -- see the
[[https://www.gnu.org/software/auctex/manual/auctex/Folding.html ][folding
section]] of AUCTeX's manual for details.
+
+I use the packages
[[https://github.com/ultronozm/tex-continuous.el][tex-continuous.el]] and
[[https://github.com/ultronozm/preview-auto.el][preview-auto.el]] (with the
variable =preview-auto-refresh-after-compilation= is set to its default value,
=t=) to compile the document and regenerate the previews automatically, and
refresh the folds as needed using =TeX-fold-section= (=C-c C-o C-s=).
+
+* Customization
+By customizing the variable =tex-numbers-label-to-number-function=, one could
specify a different way to retrieve label numbers, e.g., by querying an LSP
server.
diff --git a/tex-numbers.el b/tex-numbers.el
index 2149ab07f0..996f965e68 100644
--- a/tex-numbers.el
+++ b/tex-numbers.el
@@ -1,9 +1,9 @@
-;;; tex-numbers.el --- numbering for LaTeX previews and folds -*-
lexical-binding: t; -*-
+;;; tex-numbers.el --- Numbering for LaTeX previews and folds -*-
lexical-binding: t; -*-
;; Copyright (C) 2024 Paul D. Nelson
;; Author: Paul D. Nelson <nelson.paul.da...@gmail.com>
-;; Version: 0.0
+;; Version: 0.1
;; URL: https://github.com/ultronozm/tex-numbers.el
;; Package-Requires: ((emacs "27.1") (auctex "14.0.5"))
;; Keywords: tex
@@ -23,38 +23,11 @@
;;; Commentary:
-;; This package augments the preview and folding features of AUCTeX:
-;;
-;; - Previews of labeled equations are numbered as in the compiled
-;; document.
-;;
-;; - The the macros \\ref, \\eqref, and \\label are folded with the
-;; corresponding numbers.
-;;
-;; - completion-at-point annotations for the contents of \\ref and
-;; \\eqref include equation numbers.
-;;
-;; TEMPORARY NOTE: this package currently only works with the master
-;; branch of AUCTeX. Its release is intended to be synchronized with
-;; the next release of AUCTeX.
-;;
-;; Activate via M-x tex-numbers-mode, or by adding to your init file:
-;;
-;; (use-package tex-numbers
-;; :hook
-;; (LaTeX-mode . tex-numbers-mode))
-;;
-;; The package provides an interface for retrieving label numbers in
-;; LaTeX documents. This interface is used to implement a global
-;; minor mode, `tex-numbers-mode', which enables the noted features.
-;;
-;; The label numbers are retrieved from the aux file of the compiled
-;; document. To update them, one should compile the document,
-;; regenerate the previews and refresh the folds.
-;;
-;; By customizing the variable `tex-numbers-label-to-number-function', one
-;; can specify a different way to retrieve label numbers, e.g., by
-;; querying an LSP server.
+;; This package provides a function, `tex-numbers-label-to-number',
+;; that retrieves label numbers for LaTeX documents from the compiled
+;; aux file. That function is used to implement a global minor mode,
+;; `tex-numbers-mode', that augments many features of AUCTeX
+;; (previews, folding, ...). See README.org for details.
;;; Code:
@@ -114,6 +87,18 @@ the label number as a string, or nil if the label cannot be
found."
(when cache
(gethash label cache))))
+(defcustom tex-numbers-search-external-documents t
+ "Whether to search external documents for label numbers.
+If non-nil, `tex-numbers-label-to-number' will search external documents
+for label numbers if the label cannot be found in the current document.
+
+The search is performed by looking for \\externaldocument{FILENAME}
+commands in the current document, and then looking for the label in
+FILENAME.tex. This operation opens external TeX documents in unselected
+buffers, so that it can use AUCTeX's function `TeX-master-output-file'
+to find the corresponding aux files."
+ :type 'boolean)
+
(defun tex-numbers-label-to-number (label)
"Get number of LABEL for current tex buffer.
If the buffer does not point to a file, or if the corresponding
@@ -124,22 +109,29 @@ with \"X\"."
(if tex-numbers-label-to-number-function
(funcall tex-numbers-label-to-number-function label)
(or
- (when-let* ((aux-file (TeX-master-file "aux")))
+ (when-let* ((aux-file (TeX-master-output-file "aux")))
(tex-numbers-label-to-number-helper label aux-file))
;; If we can't retrieve the label from the main file, then we look
;; at any external documents.
- (save-excursion
- (save-restriction
- (widen)
- (goto-char (point-min))
- (let (found)
- (while (and (null found)
- (re-search-forward tex-numbers--external-document-regexp
- nil t))
- (let* ((filename (concat (match-string 1) ".aux")))
- (setq found (tex-numbers-label-to-number-helper label
filename))))
- (when found
- (concat "X" found))))))))
+ (and
+ tex-numbers-search-external-documents
+ (save-excursion
+ (save-restriction
+ (widen)
+ (goto-char (point-min))
+ (let (found)
+ (while (and (null found)
+ (re-search-forward
tex-numbers--external-document-regexp
+ nil t))
+ (let* ((tex-filename (concat (match-string 1) ".tex"))
+ (tex-buffer (find-file-noselect tex-filename))
+ (aux-filename
+ (with-current-buffer tex-buffer
+ (hack-local-variables)
+ (TeX-master-output-file "aux"))))
+ (setq found (tex-numbers-label-to-number-helper label
aux-filename))))
+ (when found
+ (concat "X" found)))))))))
(defun tex-numbers-preview-preprocessor (str)
"Preprocess STR for preview by adding tags to labels.
@@ -152,17 +144,18 @@ Uses `tex-numbers-label-to-number-function' to retrieve
label numbers."
(goto-char (point-min))
(while (re-search-forward label-re nil t)
(let ((label (match-string 1)))
- (when-let ((number
- (with-current-buffer buf
- (tex-numbers-label-to-number label))))
- (when (let ((comment-start-skip
- (concat
- "\\(\\(^\\|[^\\\n]\\)\\("
- (regexp-quote TeX-esc)
- (regexp-quote TeX-esc)
- "\\)*\\)\\(%+ *\\)")))
- (texmathp))
- (insert (format "\\tag{%s}" number))))))
+ (if-let ((number
+ (with-current-buffer buf
+ (tex-numbers-label-to-number label))))
+ (when (let ((comment-start-skip
+ (concat
+ "\\(\\(^\\|[^\\\n]\\)\\("
+ (regexp-quote TeX-esc)
+ (regexp-quote TeX-esc)
+ "\\)*\\)\\(%+ *\\)")))
+ (texmathp))
+ (insert (format "\\tag{%s}" number)))
+ (insert "\\nonumber"))))
(buffer-substring-no-properties (point-min) (point-max)))))
(defun tex-numbers-ref-helper (label default)
@@ -195,12 +188,27 @@ that returns a fold display string for that macro."
:type '(repeat string))
(defun tex-numbers-label-annotation-advice (orig-fun label)
- "Return context for LABEL, augmented by the corresponding label number."
+ "Return context for LABEL, augmented by the corresponding label number.
+Call ORIG-FUN with LABEL, and append the label number in parentheses if
+it can be retrieved."
(concat
(funcall orig-fun label)
(when-let ((number (tex-numbers-label-to-number label)))
(format " (%s)" number))))
+(defun tex-numbers--reftex-goto-label-advice (orig-fun &rest args)
+ "Advice for `reftex-goto-label'.
+Call ORIG-FUN with ARGS, and add the label number to the annotation."
+ (let* ((buf (current-buffer))
+ (fn (lambda (label)
+ (if-let ((str (with-current-buffer buf
+ (funcall #'tex-numbers-label-to-number label))))
+ (format " [%s]" str)
+ "")))
+ (completion-extra-properties
+ `(:annotation-function ,fn)))
+ (apply orig-fun args)))
+
;;;###autoload
(define-minor-mode tex-numbers-mode
"Toggle `tex-numbers' mode."
@@ -208,9 +216,10 @@ that returns a fold display string for that macro."
:lighter nil
(cond
(tex-numbers-mode
- (setq preview-preprocess-function #'tex-numbers-preview-preprocessor)
+ (add-to-list 'preview-preprocess-functions
#'tex-numbers-preview-preprocessor)
(advice-add 'LaTeX-completion-label-annotation-function
:around #'tex-numbers-label-annotation-advice)
+ (advice-add 'reftex-goto-label :around
#'tex-numbers--reftex-goto-label-advice)
(require 'tex-fold)
(dolist (macro tex-numbers-macro-list)
(let ((func (intern (format "tex-numbers-%s-display" macro))))
@@ -223,9 +232,11 @@ that returns a fold display string for that macro."
(when TeX-fold-mode
(TeX-fold-mode 1)))
(t
- (setq preview-preprocess-function nil)
+ (setq preview-preprocess-functions
+ (delete #'tex-numbers-preview-preprocessor
preview-preprocess-functions))
(advice-remove 'LaTeX-completion-label-annotation-function
#'tex-numbers-label-annotation-advice)
+ (advice-remove 'reftex-goto-label #'tex-numbers--reftex-goto-label-advice)
(dolist (macro tex-numbers-macro-list)
(let ((func (intern (format "tex-numbers-%s-display" macro))))
(setq TeX-fold-macro-spec-list
