GNU bug report logs - #38996
26.3; Missing documentation for `list-at-point' function in elisp manual.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 38996 in the body.
You can then email your comments to 38996 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Mark Harig <idirectscm <at> aim.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.3; Missing documentation for `list-at-point' function in elisp
 manual.
Date: Mon, 6 Jan 2020 20:33:15 +0000 (UTC)

[Message part 1 (text/plain, inline)]

Emacs Maintainers,
Several searches at debbugs.gnu.org did not turn up any reports for this minor documentation omission.
The NEWS file for Emacs 26.2/.3 documents changes to `thing-at-point', including mention of the function `list-at-point'.  C-h f (describe-function) provides documentation of `list-at-point', but C-h S (info-lookup-symbol) for `list-at-point' responds with "Not documented as a symbol: list-at-point'.  A check of the node in the elisp manual that documents `thing-at-point' does not show any mention of `list-at-point', nor does the previous node ("Near Point").  If `list-at-point' is documented elsewhere in the elisp manual, then an index manual entry is needed for this function.  Without this documentation, it is still possible to use `list-at-point', but when it is not documented in the manual, users might not know that it exists.
(End of report.)

[Message part 2 (text/html, inline)]

Message #8 received at 38996 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mark Harig <idirectscm <at> aim.com>
Cc: 38996 <at> debbugs.gnu.org
Subject: Re: bug#38996: 26.3;
 Missing documentation for `list-at-point' function in elisp manual.
Date: Tue, 07 Jan 2020 18:18:02 +0200

> Date: Mon, 6 Jan 2020 20:33:15 +0000 (UTC)
> From: Mark Harig via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> The NEWS file for Emacs 26.2/.3 documents changes to `thing-at-point', including mention of the function
> `list-at-point'.  C-h f (describe-function) provides documentation of `list-at-point', but C-h S
> (info-lookup-symbol) for `list-at-point' responds with "Not documented as a symbol: list-at-point'.  A check of
> the node in the elisp manual that documents `thing-at-point' does not show any mention of `list-at-point', nor
> does the previous node ("Near Point").  If `list-at-point' is documented elsewhere in the elisp manual, then an
> index manual entry is needed for this function.  Without this documentation, it is still possible to use
> `list-at-point', but when it is not documented in the manual, users might not know that it exists.

Thank you for your report.

We don't document every function in the manual: that would make the
manual too large (it already prints as 2 very thick volumes).  This
function is new, and has no callers inside Emacs, so whether it is
important enough to warrant a place in the manual remains to be seen.

For discoverability, we rely on built-in Help features such as
'apropos', and yes, on people reading NEWS when they start using a new
version, because reading that will tell them about changes in a much
more efficient way than the same information buried among many
hundreds of pages of the manual.

So I think we should wait and see if this function needs to be added
to the manual.

Message #11 received at 38996 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 38996 <at> debbugs.gnu.org, Mark Harig <idirectscm <at> aim.com>
Subject: Re: bug#38996: 26.3; Missing documentation for `list-at-point'
 function in elisp manual.
Date: Wed, 8 Jan 2020 11:11:02 +0100

tags 38996 + notabug wontfix
close 38996
thanks

Eli Zaretskii <eliz <at> gnu.org>:

> So I think we should wait and see if this function needs to be added
> to the manual.

I agree, and I'm therefore closing this bug report.

Best regards,
Stefan Kangas

Message #18 received at 38996 <at> debbugs.gnu.org (full text, mbox):

From: Mark Harig <idirectscm <at> aim.com>
To: 38996 <at> debbugs.gnu.org
Subject: Re: bug#38996: 26.3; Missing documentation for `list-at-point'
 function in elisp manual.
Date: Wed, 8 Jan 2020 17:50:16 +0000 (UTC)

[Message part 1 (text/plain, inline)]

> We don't document every function in the manual: that would make the> manual too large (it already prints as 2 very thick volumes).  This> function is new, and has no callers inside Emacs, so whether it is> important enough to warrant a place in the manual remains to be seen.> > For discoverability, we rely on built-in Help features such as> 'apropos', and yes, on people reading NEWS when they start using a new> version, because reading that will tell them about changes in a much> more efficient way than the same information buried among many> hundreds of pages of the manual.
OK. Going forward, how are end users to know which functions have notbeen documented on purpose and which have not been documented due tooversight?  It might be worth considering adding to future NEWS, whena new function or variable is added, a some brief note saying that"this function/variable will not (yet) be documented in one of themanuals."  Without that, it is impossible for a user to know whetherthe lack of documentation is intentional or an error to be reported here.
---

[Message part 2 (text/html, inline)]

Message #21 received at 38996 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Mark Harig <idirectscm <at> aim.com>
Cc: 38996 <at> debbugs.gnu.org
Subject: Re: bug#38996: 26.3;
 Missing documentation for `list-at-point' function in elisp manual.
Date: Wed, 08 Jan 2020 20:17:03 +0200

> Date: Wed, 8 Jan 2020 17:50:16 +0000 (UTC)
> From: Mark Harig via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> OK. Going forward, how are end users to know which functions have not
> been documented on purpose and which have not been documented due to
> oversight?

I don't think there should be a way.  If you think something should be
there, and you have a good reason, feel free to report it as a bug.
At worst, you will hear an explanation why it's not an omission; no
harm done.

Previous Next

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