main 14de1605: Add folding support for \begin and \end macros

[Arash Esbati]

branch: main
commit 14de1605acdfaedda60568b0f4e06e48b4a17d41
Author: Paul Nelson <ultrono@gmail.com>
Commit: Arash Esbati <arash@gnu.org>

    Add folding support for \begin and \end macros
    
    * NEWS.org (Added): Announce the addition.
    * auctex.texi (Folding Macros and Environments): Document the
    new user option.
    * tex-fold.el (TeX-fold-macro-spec-list): Add begin and end
    entries.
    (TeX-fold-begin-display, TeX-fold-end-display): New functions,
    added above as entries.
    (TeX-fold--helper-display): New helper function.
    (TeX-fold-begin-end-spec-list): New user option, used by
    the above functions.
    (TeX-fold-format-titled-block,
    TeX-fold-format-titled-alertblock,
    TeX-fold-format-theorem-environment): New functions used in the
    default value of the new user option.  (bug#73724)
---
 NEWS.org        |   4 ++
 doc/auctex.texi |  75 ++++++++++++++++++++++++++
 tex-fold.el     | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 239 insertions(+)

diff --git a/NEWS.org b/NEWS.org
index 6eddeb2f..6960e062 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -11,6 +11,10 @@
 
 ** Added
 
+- 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~.
 
diff --git a/doc/auctex.texi b/doc/auctex.texi
index d8e92e80..0356b96d 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -2880,6 +2880,81 @@ replacement specifier given by the default value of
 @code{TeX-fold-macro-spec-list}).
 @end defopt
 
+@defopt TeX-fold-begin-end-spec-list
+List of replacement specifiers for @samp{\begin@{@var{env}@}} and
+@samp{\end@{@var{env}@}} macros.  This option is used only when the
+replacement specifiers for @samp{begin} and @samp{end} macros in
+@code{TeX-fold-macro-spec-list} are set to their default values:
+@code{TeX-fold-begin-display} and @code{TeX-fold-end-display},
+respectively.
+
+Each item in the list consists of two elements.  The first element is a
+cons cell @code{(@var{BEGIN} . @var{END})}, where @var{BEGIN} and
+@var{END} are the display specifications for @samp{\begin@{...@}} and
+@samp{\end@{...@}} macros, respectively.  Each specification can be
+either:
+
+@itemize @bullet
+@item
+A string, which will be used directly as the fold display string.
+
+@item
+A function symbol, which will be called with two arguments: the
+(unabbreviated) environment name and a list of the remaining mandatory
+macro arguments.  The function should return a string to be used as the
+fold display.
+@end itemize
+
+The second element is a list of environment types.  Each type can be:
+
+@itemize @bullet
+@item
+A string representing the environment name (e.g., @code{"remark"}).
+
+@item
+A list with the first element being the environment name and the remaining
+elements being any abbreviated forms of that name (e.g., @code{("remark"
+"rem" "rmk")}).
+@end itemize
+
+For example:
+
+@lisp
+(((">" . "<") ("itemize" "enumerate" "description" "frame"))
+ ((TeX-fold-format-theorem-environment . "*")
+  ("note" ("theorem" "thm"))))
+@end lisp
+
+In this example:
+
+@itemize @bullet
+@item
+@samp{\begin@{itemize@}}, @samp{\begin@{enumerate@}},
+@samp{\begin@{description@}} and @samp{\begin@{frame@}} will fold to
+@samp{>}, while their corresponding @samp{\end@{...@}} macros will fold to
+@samp{<}.
+
+@item
+@samp{\begin@{note@}} will fold to @samp{Note}.
+
+@item
+@samp{\begin@{theorem@}} and @samp{\begin@{thm@}} will fold to @samp{Theorem}.
+
+@item
+If an optional argument is provided, e.g., @samp{\begin@{theorem@}[Foo]},
+it will fold to @samp{Theorem (Foo)}.
+
+@item
+All corresponding @samp{\end@{...@}} macros for @samp{note},
+@samp{theorem}, and @samp{thm} will fold to @samp{*}.
+@end itemize
+
+To disable folding for @samp{\begin@{...@}} and @samp{\end@{...@}} macros,
+you can either set this variable to @code{nil}, or remove the display
+specifications for @samp{begin} and @samp{end} from
+@code{TeX-fold-macro-spec-list}.
+@end defopt
+
 @node Outline
 @section Outlining the Document
 @cindex Outlining
diff --git a/tex-fold.el b/tex-fold.el
index c83b970d..dc7ac340 100644
--- a/tex-fold.el
+++ b/tex-fold.el
@@ -83,6 +83,8 @@ macros, `math' for math macros and `comment' for comments."
     ("TM"  ("texttrademark"))
     (TeX-fold-alert-display ("alert"))
     (TeX-fold-textcolor-display ("textcolor"))
+    (TeX-fold-begin-display ("begin"))
+    (TeX-fold-end-display ("end"))
     (1 ("part" "chapter" "section" "subsection" "subsubsection"
         "paragraph" "subparagraph"
         "part*" "chapter*" "section*" "subsection*" "subsubsection*"
@@ -616,6 +618,8 @@ Return non-nil if a comment was found and folded, nil 
otherwise."
 
 ;;; Display functions
 
+;;;; textcolor
+
 (defun TeX-fold-textcolor-display (color text &rest _args)
   "Fold display for a \\textcolor{COLOR}{TEXT} macro."
   (with-temp-buffer
@@ -625,6 +629,8 @@ Return non-nil if a comment was found and folded, nil 
otherwise."
                        (current-buffer))
     (buffer-string)))
 
+;;;; alert
+
 (defcustom TeX-fold-alert-color "red"
   "Color for alert text."
   :type 'color
@@ -639,6 +645,160 @@ Return non-nil if a comment was found and folded, nil 
otherwise."
                        (current-buffer))
     (buffer-string)))
 
+;;;; begin/end
+
+(defcustom TeX-fold-begin-end-spec-list
+  '((("↴" . "↲")
+     ("itemize" "enumerate" "description" "frame"))
+    ((TeX-fold-format-titled-block . "◼")
+     ("block"))
+    ((TeX-fold-format-titled-alertblock . "◼")
+     ("alertblock"))
+    ((TeX-fold-format-theorem-environment . "□")
+     ("proof"))
+    ((TeX-fold-format-theorem-environment . "◼")
+     ("abstract"
+      "acknowledgment"
+      "algorithm"
+      "assumptions"
+      "claim"
+      "commentary"
+      "fact"
+      "note"
+      "questions"
+      ("answer" "ans")
+      ("conclusion" "conc")
+      ("condition" "cond")
+      ("conjecture" "conj")
+      ("corollary" "cor")
+      ("criterion" "crit")
+      ("definition" "def" "defn")
+      ("example" "ex")
+      ("exercise" "exer")
+      ("lemma" "lem")
+      ("notation" "not")
+      ("problem" "prob")
+      ("proposition" "prop")
+      ("question" "ques")
+      ("remark" "rem" "rmk")
+      ("summary" "sum")
+      ("terminology" "term")
+      ("theorem" "thm"))))
+  "Replacement specifier list for \\begin{env} and \\end{env} macros.
+
+This option is relevant only if the replacement specifiers in
+`TeX-fold-macro-spec-list' for \"begin\" and \"end\" macros are the
+defaults, namely `TeX-fold-begin-display' and `TeX-fold-end-display'.
+
+Each item is a list consisting of two elements:
+
+The first element is a cons cell, with car and cdr the display
+specifications for \\begin{...} and \\end{...}  macros, respectively.
+Each specification is either
+
+  - a string, used as the fold display string, or
+
+  - a function, called with the (unabbreviated) environment name and a
+    list consisting of the remaining mandatory macro arguments, that
+    returns a string.
+
+The second element is a list of environment types, which are either
+
+- the environment name, e.g., \"remark\", or
+
+- a list with first element an environment name and remaining elements
+  any abbreviated environment names, e.g., (\"remark\" \"rem\" \"rmk\")."
+  :type '(repeat
+          (group
+           (cons (choice (string :tag "Display String for \\begin{...}")
+                         (function :tag "Function to execute for 
\\begin{...}"))
+                 (choice (string :tag "Display String for \\end{...}")
+                         (function :tag "Function to execute for \\end{...}")))
+           (repeat :tag "Environment Types"
+                   (choice (string :tag "Environment")
+                           (cons :tag "Environment and Abbreviations"
+                                 (string :tag "Environment")
+                                 (repeat :tag "Abbreviations"
+                                         (string :tag "Abbreviation")))))))
+  :package-version '(auctex . "14.0.8"))
+
+
+(defun TeX-fold-begin-display (env &rest args)
+  "Fold display for a \\begin{ENV}.
+Intended for use in `TeX-fold-begin-end-spec-list'.  ARGS is a list
+consisting of the remaining mandatory macro arguments."
+  (TeX-fold--helper-display env args #'car))
+
+(defun TeX-fold-end-display (env &rest args)
+  "Fold display for a \\end{ENV} macro.
+Intended for use in `TeX-fold-begin-end-spec-list'.  ARGS is a list
+consisting of the remaining mandatory macro arguments."
+  (TeX-fold--helper-display env args #'cdr))
+
+(defun TeX-fold--helper-display (env args spec-retriever)
+  "Generate fold display string for \\begin{ENV} or \\end{ENV} macro.
+ARGS are the remaining mandatory macro arguments.  Returns the string or
+function determined by `TeX-fold-begin-end-spec-list' if ENV is found
+there, otherwise `abort'.  SPEC-RETRIEVER, which should be either `car'
+or `cdr', retrieves the appropriate part of the display specification."
+  (catch 'result
+    (dolist (item TeX-fold-begin-end-spec-list)
+      (let* ((spec (funcall spec-retriever (car item)))
+             (types (cadr item)))
+        (dolist (type types)
+          (when-let ((name (cond ((stringp type)
+                                  (when (string= env type)
+                                    env))
+                                 ((consp type)
+                                  (when (member env type)
+                                    (car type))))))
+            (throw 'result
+                   (if (functionp spec)
+                       (funcall spec name args)
+                     spec))))))
+    'abort))
+
+;;;;; block environments
+
+(defun TeX-fold-format-titled-block (_env args)
+  "Format fold display for beamer block environments.
+Intended for use in `TeX-fold-begin-end-spec-list'.  ENV is ignored.
+ARGS is a list whose car will be the block title.
+
+Example: \"\\begin{block}{Theorem 1}\" folds to \"Theorem 1\"."
+  (car args))
+
+(defun TeX-fold-format-titled-alertblock (_env args)
+  "Format fold display for beamer alertblock environments.
+Intended for use in `TeX-fold-begin-end-spec-list'.  The arguments
+ENV/ARGS and the behavior are as in `TeX-fold-format-titled-block', but
+the folded text is colored using `TeX-fold-alert-color'."
+  (let ((caption (car args)))
+    (add-face-text-property 0 (length caption)
+                            `(:foreground ,TeX-fold-alert-color) nil caption)
+    (format "%s" caption)))
+
+;;;;; theorem-like environments
+
+(defun TeX-fold-format-theorem-environment (env _args)
+  "Format fold display for theorem-like LaTeX environments.
+Intended for use in `TeX-fold-begin-end-spec-list'.  ENV is the
+environment name, ARGS are ignored.  Returns a string of the form
+\"Environment \" or \"Environment (Description) \""
+  (let* ((env (with-temp-buffer
+                (insert env)
+                (goto-char (point-min))
+                (capitalize-word 1)
+                (buffer-string)))
+         (description
+          (car (TeX-fold-macro-nth-arg 1 (point)
+                                       (TeX-fold-item-end (point) 'macro)
+                                       '(?\[ . ?\])))))
+    (concat
+     (format "%s " env)
+     (when description
+       (format "(%s) " description)))))
+
 ;;; Utilities
 
 (defun TeX-fold-make-overlay (ov-start ov-end type display-string-spec)