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

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

[Howard Melman]

The docstring for `help-at-pt-string' mentions a `kbd-help'
property, but this property is not mentioned in either the
emacs or elisp manuals.

The commentary to help-at-pt.el mentions that it is a new
property though it's not clear how new and it doesn't seem
to be used in the rest of emacs 26 lisp source. 

In GNU Emacs 26.3 (build 1, x86_64-apple-darwin18.2.0, NS appkit-1671.20 Version 10.14.3 (Build 18D109))
of 2019-09-02 built on builder10-14.porkrind.org

-- 

Howard

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

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Sun, 26 Jan 2020 12:03:12 -0500
> 
> The docstring for `help-at-pt-string' mentions a `kbd-help'
> property, but this property is not mentioned in either the
> emacs or elisp manuals.
> 
> The commentary to help-at-pt.el mentions that it is a new
> property though it's not clear how new and it doesn't seem
> to be used in the rest of emacs 26 lisp source. 

It indeed is unused, so I'm not sure it should be documented at this
time.  As for "new": the help-at-pt.el file was added to Emacs 17
years ago, and its original version already included support for this
property.

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

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Fri, 31 Jan 2020 11:10:26 -0500

[Please keep the bug address on the CC list.]

> > It indeed is unused, so I'm not sure it should be documented at this
> > time.  As for "new": the help-at-pt.el file was added to Emacs 17
> > years ago, and its original version already included support for this
> > property.
> 
> Perhaps it should be deprecated? Without documentation it's unlikely to be used.

It is documented in the doc strings, isn't it?

> It would be nice if some place described it as unused (and perhaps as unused for a very long time). 

Unused in Emacs itself doesn't mean no one out there uses it.  A
feature that is unused doesn't do any harm.

> Since the code will use it, it should remain in the docstring. If you don't want to add it to the manual then may I suggest at a least a comment in the code saying so and what its intent was, perhaps in the package commentary, would be useful.

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.

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

[Howard Melman]

> On Jan 31, 2020, at 12:10 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Howard Melman <hmelman@gmail.com>
>> Date: Fri, 31 Jan 2020 11:10:26 -0500
> 
> [Please keep the bug address on the CC list.]
> 
>>> It indeed is unused, so I'm not sure it should be documented at this
>>> time.  As for "new": the help-at-pt.el file was added to Emacs 17
>>> years ago, and its original version already included support for this
>>> property.
>> 
>> Perhaps it should be deprecated? Without documentation it's unlikely to be used.
> 
> It is documented in the doc strings, isn't it?
> 
>> It would be nice if some place described it as unused (and perhaps as unused for a very long time). 
> 
> Unused in Emacs itself doesn't mean no one out there uses it.  A
> feature that is unused doesn't do any harm.

Well, just a little complexity. I've now forgotten what I was tracking down that led me to this code but it was an additional property I had to figure out if it was relevant to what I was looking for.

>> Since the code will use it, it should remain in the docstring. If you don't want to add it to the manual then may I suggest at a least a comment in the code saying so and what its intent was, perhaps in the package commentary, would be useful.
> 
> 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. 

The elisp manual section "Properties with Special Meanings" is incomplete without it. If it doesn't deserve a description there, then I do think a comment differentiating it from help-echo (even to say it's rarely used) would help.

Howard

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

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Fri, 31 Jan 2020 12:23:45 -0500
> Cc: 39295@debbugs.gnu.org
> 
> > 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.

> 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.

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

[Howard Melman]

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

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

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

[Lars Ingebrigtsen]

Howard Melman <hmelman@gmail.com> writes:

> 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,

Makes sense to me.  I've now made the suggested adjustment in Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no