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

From: Paul Nelson <[email-masked]>
Date: Sun, 13 Oct 2024 15:23:39 +0200

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