GNU bug report logs - #73724
[PATCH] Add folding support for begin and end macros

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 73724 in the body.
You can then email your comments to 73724 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Paul Nelson <ultrono <at> gmail.com>
To: bug-auctex <at> gnu.org
Subject: [PATCH] Add folding support for begin and end macros
Date: Wed, 9 Oct 2024 22:37:14 +0200

[Message part 1 (text/plain, inline)]

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

The naive way to attempt such folding in AUCTeX via string
specifications in TeX-fold-macro-spec-list has many drawbacks.  I
would be happy to elaborate upon these, but do not do so in this
message.

This patch adds function specifications to TeX-fold-macro-spec-list
and a new user-facing option TeX-fold-begin-end-spec-list that
controls how to fold begin/end arguments.  To get a flavor, see the
screenshots at https://github.com/ultronozm/czm-tex-fold.el (but let
me note that I've streamlined the code while preparing this patch).

I'll illustrate here with some examples:

- If the option TeX-fold-begin-end-spec-list is nil, then behavior is as before.

- If the option contains an item such as

    (("↴" . "↲") ("itemize" "enumerate" "description" "frame"))

  then, e.g., \begin{enumerate} and \end{enumerate} fold to ↴ and ↲,
respectively.

- If the option contains an item such as

    ((TeX-fold-format-theorem-environment . "◼")
         ("note" ("theorem" "thm")))

  then

  - \begin{note} folds to "Note",
  - \begin{theorem} and \begin{thm} fold to "Theorem",
  - \begin{theorem}[Foo] and \begin{thm}[Foo] fold to "Theorem (Foo)".
  - \end{note}, etc., fold to "◼".

I've supplied what I believe to be reasonable defaults (attempting to
err on the conservative side), but would welcome any feedback.

Thanks, best,

Paul

[0001-Add-folding-support-for-begin-and-end-macros.patch (application/octet-stream, attachment)]

Message #8 received at 73724 <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: Paul Nelson <ultrono <at> gmail.com>
Cc: 73724 <at> debbugs.gnu.org
Subject: Re: bug#73724: [PATCH] Add folding support for begin and end macros
Date: Sun, 13 Oct 2024 13:57:04 +0200

Hi Paul,

Paul Nelson <ultrono <at> 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

Message #11 received at 73724 <at> debbugs.gnu.org (full text, mbox):

From: Paul Nelson <ultrono <at> gmail.com>
To: Arash Esbati <arash <at> gnu.org>
Cc: 73724 <at> debbugs.gnu.org
Subject: Re: bug#73724: [PATCH] Add folding support for begin and end macros
Date: Sun, 13 Oct 2024 15:23:39 +0200

[Message part 1 (text/plain, inline)]

Hi Arash,

Many for your feedback.

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

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.

> > +  "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.

Agreed that this is clearer.

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.

> > +(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"?
>

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.

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.

Thanks, best,

Paul

[0001-Add-folding-support-for-begin-and-end-macros.patch (application/octet-stream, attachment)]

Message #14 received at 73724 <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: Paul Nelson <ultrono <at> gmail.com>
Cc: 73724 <at> debbugs.gnu.org
Subject: Re: bug#73724: [PATCH] Add folding support for begin and end macros
Date: Mon, 14 Oct 2024 22:19:43 +0200

[Message part 1 (text/plain, inline)]

Hi Paul,

Paul Nelson <ultrono <at> 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 <at> 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:

[texinfo-pdf-out.png (image/png, inline)]

[Message part 3 (text/plain, inline)]

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

Message #17 received at 73724 <at> debbugs.gnu.org (full text, mbox):

From: Paul Nelson <ultrono <at> gmail.com>
To: Arash Esbati <arash <at> gnu.org>
Cc: 73724 <at> debbugs.gnu.org
Subject: Re: bug#73724: [PATCH] Add folding support for begin and end macros
Date: Tue, 15 Oct 2024 08:45:42 +0200

[Message part 1 (text/plain, inline)]

Hi Arash, thanks, please find attached the updated patch.  Paul

[0001-Add-folding-support-for-begin-and-end-macros.patch (application/octet-stream, attachment)]

Message #22 received at 73724-done <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: Paul Nelson <ultrono <at> gmail.com>
Cc: 73724-done <at> debbugs.gnu.org
Subject: Re: bug#73724: [PATCH] Add folding support for begin and end macros
Date: Wed, 16 Oct 2024 18:56:33 +0200

Paul Nelson <ultrono <at> gmail.com> writes:

> Hi Arash, thanks, please find attached the updated patch.  Paul

Hi Paul,

many thanks for your contribution and your patience.  I installed that
patch under your name, and therefore closing this report.

Best, Arash

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.