From 9b50b36efe5181f3b2b76136d8f121f098d83d72 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Wed, 15 Sep 2021 22:01:21 +0300 Subject: [PATCH] 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) --- doc/lispref/tips.texi | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index f0eb1079caf..0b20c107bba 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -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 -- 2.39.5