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

[Arash Esbati]

Hi Paul,

Paul Nelson <ultrono@gmail.com> writes:

> Indeed, I had in mind (but forgot to write) that I left the manual doc
> as a stub until the general behavior was approved.  I've now attempted
> a proper manual entry.

Thanks, see below for some comments.

> The relevance of TeX-fold-begin-display and TeX-fold-end-display is
> that it is only through these functions that
> TeX-fold-begin-end-spec-list "plugs in" to the user option
> TeX-macro-spec-fold-alist.  If the user modifies that option to have
> different display specifiers for begin and end, then
> TeX-fold-begin-end-spec-list becomes irrelevant.  I've tried to make
> this point clearer in the updated doc, but any further feedback is
> welcome.

Thanks, I think I get it now.

> I had internalized that "mandatory arguments" and "arguments in
> braces" were the same thing in LaTeX, but could be mistaken on this.
> I've adjusted this docstring (and related ones) to say simply
> "mandatory macro arguments", which seems consistent with what is
> written elsewhere in tex-fold.el, but would welcome other suggestions.

"mandatory macro arguments" sounds good, my question reg. braces was
just to clarify what we're talking about.

> QUESTION: should these features be considered LaTeX-specific, hence
> added to LaTeX-fold-macro-spec-list and perhaps moved from tex-fold.el
> into either latex.el or some new file latex-fold.el?  I personally
> find the current organization reasonable, but am open to suggestions
> here.

tex-fold.el is LaTeX-centric in general, so I also think we can keep the
current organization.

> From bb03a3a8da307b65de8457b6ce0a99176469fe8b Mon Sep 17 00:00:00 2001
> From: Paul Nelson <ultrono@gmail.com>
> Date: Sat, 5 Oct 2024 14:51:32 +0100
> Subject: [PATCH] Add folding support for begin and end macros
>
> diff --git a/doc/auctex.texi b/doc/auctex.texi
> index d8e92e80..e5f08749 100644
> --- a/doc/auctex.texi
> +++ b/doc/auctex.texi
> @@ -2880,6 +2880,82 @@ 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:

I'd rewrite this part as:

+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:

> +For example:
> +
> +@lisp
> +((("↴" . "↲") ("itemize" "enumerate" "description" "frame"))
> + ((TeX-fold-format-theorem-environment . "◼")
> +  ("note" ("theorem" "thm"))))
> +@end lisp

Have you tried to typeset auctex.texi after this change?  The .pdf file
looks like this for me:

It seems that the UTF-8 chars don't work well in the .pdf output.  I
suggest we change that example to use ASCII chars.

Best, Arash