Re: show_help_echo truncates unconditionally

[Richard Stallman]

What job does show_help_echo do?  The comment says

    /* Display help echo in the echo area.

       HELP a string means display that string, HELP nil means clear the
       help echo.  If HELP is a function, call it with OBJECT and POS as
       arguments; the function should return a help string or nil for
       none.  For all other types of HELP evaluate it to obtain a string.

but that is cryptic and incomprehensible.  For instance, it says
"Display help echo"; what is this "help echo" that it is supposed
to display?

Under what sort of circumstances does this function get called?

I can't begin to think about whether this function should be changed
unless I know what job it does.  Anyway, on general purposes it is
essential for the comments to explain that clearly.

    +   DEFVAR_LISP ("show-help-echo-truncate", &Vshow_help_echo_truncate,
    +          doc: /* If non-nil, truncate messages shown with show_help_echo. 
*/);
    +   Vshow_help_echo_truncate = Qt;

The doc string is supposed to tell users what this variable does.
This text is not clear, because users don't know what show_help_echo
is.  (And if they tried to read the source to find out, they would be
as puzzled as I am.)