bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#39295: 26.3; kbd-help property is undocumented


From: Howard Melman
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 <address@hidden> wrote:

> From: Howard Melman <address@hidden>
>> 
>>> 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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]