bug#50599: [PATCH] Don't recommend against "\[...]" substitutions for performance

[Stefan Kangas <stefan@marxist.se>]

Eli Zaretskii <eliz@gnu.org> writes:

> We have no idea what could Lisp programmers out there want to do with
> this.  For example, I could envision some programmatically generated
> help text with many such references.  Where there are limitations due
> to the implementation, we should strive to let people know about them.

But not every such limitation belongs in `(elisp) Documentation Tips'.

Even if one can imagine that there exists specialized applications
where this limitation will become a problem, that does not mean that
we should mention it here.   This section should IMO be about general
advice for Emacs Lisp programming, and this is not a general problem.

> I disagree with the "completely irrelevant" part, the general advice
> to keep the use of \\[..] to the minimum is still valid,

I see no reason to keep use of "\\[...]" to the minimum.  In any
realistic use, my investigation has demonstrated that there is no
problem with using it for reasons of performance.

Instead of discouraging it, we should encourage its use, as it leads
to better documentation.  For example, compare the current
'ibuffer-mode' docstring to what you get if you replace the list of
commands (with its categories, explanations, etc.) with a blanket
"\\{ibuffer-mode-map}".  So I find the advice not only irrelevant but
misleading.

How about this:

We change, in my patch, 'checkdoc-max-keyref-before-warn' to a value
like 1000 or 500 instead of nil.  This would make me happy by not
impacting any real use-cases [none of which will have 500+ commands in
its docstring, or at least none of the ones that I care about will]
and it would (hopefully) make you happy by sufficiently calling
attention to any possible performance issues in some other cases.

With that, perhaps we could agree that it is okay to delete the
paragraph in `(elisp) Documentation Tips'.  Running 'checkdoc' is
after all recommended in that section as well.  WDYT?