GNU bug report logs - #39295
26.3; kbd-help property is undocumented

Previous Next

Full log

View this message in rfc822 format

From: Howard Melman <hmelman <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 39295 <at> debbugs.gnu.org
Subject: bug#39295: 26.3; kbd-help property is undocumented
Date: Mon, 3 Feb 2020 14:31:43 -0500

On Jan 31, 2020, at 2:24 PM, Eli Zaretskii <eliz <at> gnu.org> wrote:

> From: Howard Melman <hmelman <at> gmail.com>
>> 
>>> Not every feature is documented in the manual, only the important ones
>>> are.  And I'm not sure I see the utility of stating in comments that
>>> we don't document this in the manual: we don't say that about all the
>>> other features not mentioned in the manual.
>> 
>> I think some place should describe when code should use kbd-help as opposed to help-echo. 
> 
> I see it explained in the doc string of help-at-pt-display-when-idle,
> and also in some other doc strings in help-at-pt.el.

I now see it in the :doc strings of that option. Specifically the lines: "The text printed from the `help-echo' property is often only relevant when using the mouse." and "The presence of a `kbd-help' property guarantees that non mouse specific help is available." That's all the information I wanted.

I still think if those were in the defcustom's docstring or a comment it would have been easier to find, but you're correct, it is in the code and if I had been more careful in reading all 13 occurrences I would have seen it.

>> The elisp manual section "Properties with Special Meanings" is incomplete without it.
> 
> It doesn't try to be complete.  Eventually, one needs to read the doc
> strings of the features one wants to use.

That's a fine stance to take, though I interpret the first paragraph of the "Properties with Special Meanings" section as saying it is attempting to be complete.

    Here is a table of text property names that have special built-in
    meanings.  The following sections list a few additional special property
    names that control filling and property inheritance.  All other names
    have no standard meaning, and you can use them as you like.

Howard

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.