bug#63444: folding mode for Texinfo doesn't work reliably

[Arash Esbati]

Werner LEMBERG <wl@gnu.org> writes:

> I was confused.  Having never tried folding mode for Texinfo before, I
> interpreted `[r]` as the contents of a macro.  However, this is the
> visual indicator for a reference.

Ok, got it, thanks.

> Aaah, completely undocumented :-)

We expect users to be fluent in elisp and read the code instead of
wasting their time and read the manual ;-)  I agree, the part in the
manual is sparse, but if you look here[1], you'll see:

  The variables TeX-fold-macro-spec-list, TeX-fold-env-spec-list, and
  TeX-fold-math-spec-list apply to any AUCTeX mode.  If you want to make
  settings which are only applied to LaTeX mode, you can use the
  mode-specific variables LaTeX-fold-macro-spec-list,
  LaTeX-fold-env-spec-list, and LaTeX-fold-math-spec-list

So users should deduce from this that there is also
`Texinfo-fold-env-spec-list', which is, optimistic.  But before fixing
the manual, I wonder what the idea behind the implementation is: The
variables are not custom variables, so in order to make
`Texinfo-fold-env-spec-list' for example to work, one has to setq it.
I'm CC'ing Ralf who wrote the code, maybe he can remember the idea
behind it.

@Ralf: The code was introduced with commit ae2fcc1685.  Do you still
remember the idea behind the part:

+                      (let ((symbol (intern (format "%s-fold-%s-spec-list"
+                                                    (TeX-mode-prefix) elt))))
+                        (when (boundp symbol)
+                          (symbol-value symbol)))))))

If I get it right, things like `Texinfo-fold-env-spec-list' should be
custom variables; otherwise I'd use `intern-soft' above and slightly
adjust the test.

> This helps, thanks.  However, there are some issues.
>
> * I tried to set 
>
>   ```
>   (setq Texinfo-fold-env-spec-list
>         '(("[macro]"  ("macro"))
>           ...
>   ```
>
>   This converts
>
>   ```
>   @macro foo {bar, baz}
>     ...
>   @end macro
>   ```
>
>   into
>
>   ```
>   [macro]
>   ```
>
>   which is not very helpful.  Is there a way to get
>
>   ```
>   [macro foo]
>   ```
>
>   instead?

Does something like

   (setq Texinfo-fold-env-spec-list
         '((1  ("macro"))
           ...

helps (which I didn't test)?

> * There is no example for
>
>     If the first element is a function symbol, the function will be
>     called with all mandatory arguments of the macro and the result of
>     the function call will be used as a replacement for the macro.
>
>   Additionally, this documentation paragraph confuses me: Are the
>   'mandatory arguments' passed as plain strings arguments?  Or a list
>   of strings?  Or something else?

I'd like to pass this question to Ralf as well; otherwise I have to read
and understand the code (which I've never used for any mode in my life).

> * `Texinfo-fold-type-list` is missing – or not documented.
>
> * In combination with the last item, it seems that there are no
>   folding defaults for Texinfo mode.  Maybe it makes sense to have the
>   same default as with other TeX modes, i.e., folding macros and
>   environments.

See above.  I think we can change/expand this once we have a course of
action, i.e., introduce a custom variable `Texinfo-fold-type-list' and
preset it with whatever you think is appropriate.

Best, Arash