From: Howard Melman <hmelman@gmail.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 39295@debbugs.gnu.org
Subject: bug#39295: 26.3; kbd-help property is undocumented
Date: Fri, 31 Jan 2020 12:23:45 -0500 [thread overview]
Message-ID: <FF8BE1E9-5E9D-44CB-B077-0A8CB83E587B@gmail.com> (raw)
In-Reply-To: <83wo97k0vc.fsf@gnu.org>
> 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
next prev parent reply other threads:[~2020-01-31 17:23 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-01-26 17:03 bug#39295: 26.3; kbd-help property is undocumented Howard Melman
2020-01-31 14:04 ` Eli Zaretskii
[not found] ` <AF0C03F3-ED3B-462A-B4B7-E578BB44B32E@gmail.com>
2020-01-31 17:10 ` Eli Zaretskii
2020-01-31 17:23 ` Howard Melman [this message]
2020-01-31 19:24 ` Eli Zaretskii
2020-02-03 19:31 ` Howard Melman
2020-08-21 14:34 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=FF8BE1E9-5E9D-44CB-B077-0A8CB83E587B@gmail.com \
--to=hmelman@gmail.com \
--cc=39295@debbugs.gnu.org \
--cc=eliz@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.