Documentation followup to a recent commit

* doc/lispref/tips.texi (Documentation Tips): Make the wording of
recommendation not to over-use \\[..] more future-proof.
(Bug#50599)
This commit is contained in:
Eli Zaretskii
2021-09-15 22:01:21 +03:00
parent ca6ae0d905
commit 9b50b36efe

View File

@@ -789,10 +789,12 @@ the first use of @samp{\\[@dots{}]}. The text inside the
@samp{\\<@dots{}>} should be the name of the variable containing the
local keymap for the major mode.
It is not practical to use @samp{\\[@dots{}]} very many times, because
display of the documentation string will become slow. So use this to
describe the most important commands in your major mode, and then use
@samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
Each use of @samp{\\[@dots{}]} slows the display of the documentation
string by a tiny amount. If you use a lot of them, these tiny
slowdowns will add up, and might become tangible, especially on slow
systems. So our recommendation is not to over-use them; e.g., try to
avoid using more than one reference to the same command in the same
doc string.
@item
For consistency, phrase the verb in the first sentence of a function's