bug#73724: [PATCH] Add folding support for begin and end macros

[Arash Esbati]

Hi Paul,

Paul Nelson <ultrono@gmail.com> writes:

> This patch supports the folding of \begin{...} and \end{...} macros.

Thanks for the proposal, I think this might be indeed interesting for
people who use folding.  I have some comments, see below.

> ---
>  doc/auctex.texi |   7 +++
>  tex-fold.el     | 155 ++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 162 insertions(+)
>
> diff --git a/doc/auctex.texi b/doc/auctex.texi
> index d8e92e80..3bd8eeb6 100644
> --- a/doc/auctex.texi
> +++ b/doc/auctex.texi
> @@ -2880,6 +2880,13 @@ 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@{...@}} and
> +@samp{\end{...@}} macros (for the replacement specifiers given by the
             ^ @ is missing before {

> +default value of @code{TeX-fold-macro-spec-list}).  See the doc string for
> +details.

Which docstring are you referring to, `TeX-fold-begin-end-spec-list'?
If so, I would expect to find the description here in the manual.  See
for example what it says about `TeX-fold-macro-spec-list':

  
https://elpa.gnu.org/packages/doc/auctex.html#index-TeX_002dfold_002dmacro_002dspec_002dlist

> +@end defopt
> +
>  @node Outline
>  @section Outlining the Document
>  @cindex Outlining
> diff --git a/tex-fold.el b/tex-fold.el
> index c9f65b59..14b2a006 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*"
> @@ -615,6 +617,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
> @@ -624,6 +628,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
> @@ -638,6 +644,155 @@ 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")
> +      ("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 `TeX-fold-*-display', * = begin or end.

This is hard to parse.  I don't understand why the docstring should talk
about `TeX-fold-begin-display' and `TeX-fold-end-display', they aren't
relevant for the users, right?

How about something like this:

  Replacement specifier list for \\begin{env} and \\end{env} macros.

> +
> +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 required 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 {} arguments supplied to the macro."
                               ^^
Does this mean "mandatory arguments in braces"?

> +  (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 {} arguments supplied to the macro."

See above.

> +  (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 {} arguments to the macro.  Returns the string or

See above.

Others LGTM.

Best, Arash