From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Mark Harig via "Bug reports for GNU Emacs, the Swiss army knife of text editors" Newsgroups: gmane.emacs.bugs Subject: 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-ID: <856796400.8608681.1578505816990@mail.yahoo.com> References: <856796400.8608681.1578505816990.ref@mail.yahoo.com> Reply-To: Mark Harig Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="----=_Part_8608680_999115868.1578505816988" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="235123"; mail-complaints-to="usenet@blaine.gmane.org" To: 38996@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Jan 08 19:03:28 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1ipFfn-000ijr-7J for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 08 Jan 2020 19:03:16 +0100 Original-Received: from localhost ([::1]:47598 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ipFfl-0007Bg-GV for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 08 Jan 2020 13:03:13 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57068) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ipFfb-0007BV-6O for bug-gnu-emacs@gnu.org; Wed, 08 Jan 2020 13:03:04 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ipFfa-0007Eb-04 for bug-gnu-emacs@gnu.org; Wed, 08 Jan 2020 13:03:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:45298) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ipFfZ-0007EL-Pg for bug-gnu-emacs@gnu.org; Wed, 08 Jan 2020 13:03:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ipFfZ-0005Ad-Ku for bug-gnu-emacs@gnu.org; Wed, 08 Jan 2020 13:03:01 -0500 X-Loop: help-debbugs@gnu.org In-Reply-To: <258277221.7485058.1578342795150@mail.yahoo.com> Resent-From: Mark Harig Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 08 Jan 2020 18:03:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 38996 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: wontfix notabug Original-Received: via spool by 38996-submit@debbugs.gnu.org id=B38996.157850656119848 (code B ref 38996); Wed, 08 Jan 2020 18:03:01 +0000 Original-Received: (at 38996) by debbugs.gnu.org; 8 Jan 2020 18:02:41 +0000 Original-Received: from localhost ([127.0.0.1]:51271 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ipFfD-0005A1-A6 for submit@debbugs.gnu.org; Wed, 08 Jan 2020 13:02:41 -0500 Original-Received: from sonic313-9.consmr.mail.ne1.yahoo.com ([66.163.185.32]:42825) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ipFTQ-0004os-VR for 38996@debbugs.gnu.org; Wed, 08 Jan 2020 12:50:30 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=aim.com; s=a2048; t=1578505822; bh=ZK2AXhM5ih0K6IsdEhBLIqPNvuD0IGbCqynp7TGCMhQ=; h=Date:From:To:Subject:References:From:Subject; b=ZBhGE8nyZ+MpYuyDqM8pbMt9BQbsijj6uLqxNA5Nk0EF2I/NWgLqKT/jdhAJarmjbZ0FCjZBSVN/SmgTZre+tbzgL5Zx5I/T/SWNF0+Ok35MGx0wueTmKKCaIjqxXJpWaAmX/UYPZ6qr/H33p8LoUmIFGgQXVaIXKnCiYFW2m398SUeOocdPMr4PT/SqEzQxEq2f/Ig0Q61X9iGd4QOTGEfQ0dCGxLzoZ0fxnCcM41FGeL7H1crbhY+Rnf9Gh4T4UC2Rzs6rUl/HpQjqGg78yL72RsYQdfuDASwwFCqLXkj2fZ5+ijY/2c78iyWynRh5WOQZ2+AqBugUZYj6at7QTQ== X-YMail-OSG: EGpIVXoVM1nawSTfHImCbD.tc14N58r0mWffqBwt4ZqE.Q5dnGoGHqF3IB7K_hw GRobf2XLBvtQQ_8ElHzRon4rAi19QtD3y5pdyrwWajLu5sM_f.RfodlBbsnEeFpVHeBOCAvbTRhL XmbfUmQclIjxDsMbzEjfSSDB2z_TXGed8nIGO8t3TM5bDhLdpYiTHz7RkawSpy.VIX5mkQsngm3b mf22jNNx_y71HVpfRtYBvwKNDDrQnFcF1Lt93.yJiWgAaTd3U9r85ETlRCbDRqlDzo5e1z4ynP_W tNDR54d0d1vFGxiWAh0w_3XyrB_xPDjtyX5fPsyFG53jAWfPzJVaoC6jkkSDbiNdBM_z3Z5bkmC1 oIT97Nn6XfE0uvcLOeedbnpr2ii7Xy6MBvguK7Mq.8LE528NQrUkGXJx0uIY1nA9UVEYRQtW2Oo9 YLoLZ3geZiylIIi4nEh2fk.6cbOCubBmJwOPx4Zns6Xpc5j61ljIXunGm7K3yYXOdJQpPGyu7F6t i4BCZflY2Px3M_oWn6NyTZ3J8Gy_5uF8639CFhHbRnmrz_RrXQNUB3lhiT1x7b5rjl4wtEcs7t9Z E7TOj3i9apSrArfVhpf1fRcj7.qlhzZMzI7ZuqqUZ4H5Av1Kg0M9YHHRr23vONdQZbXPe8NpUV4d R0DAEK5iEbCgxw6jyxfXLZi76iMbIdGoDNNg1QbRupVArtRYkpPcuj_P1vm_je0FNTPBO8J3RNAu q71pcDBikL5kchjbfJZJXqCjUAP0u4.C9yjuzePoSpryqZFFeu8qSpobaspV5xgTOARiI3_9x_P8 fIZZH7eSKaKJOHPElLDVTT9pUs0ziWaosl6S_2gN38 Original-Received: from sonic.gate.mail.ne1.yahoo.com by sonic313.consmr.mail.ne1.yahoo.com with HTTP; Wed, 8 Jan 2020 17:50:22 +0000 X-Mailer: WebService/1.1.14873 aolwebmail Mozilla/5.0 (X11; Fedora; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.117 Safari/537.36 X-Mailman-Approved-At: Wed, 08 Jan 2020 13:02:38 -0500 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:174372 Archived-At: ------=_Part_8608680_999115868.1578505816988 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable > We don't document every function in the manual: that would make the> manu= al too large (it already prints as 2 very thick volumes).=C2=A0 This> funct= ion is new, and has no callers inside Emacs, so whether it is> important en= ough to warrant a place in the manual remains to be seen.>=C2=A0> For disco= verability, we rely on built-in Help features such as> 'apropos', and yes, = on people reading NEWS when they start using a new> version, because readin= g 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 d= ocumented on purpose and which have not been documented due tooversight?=C2= =A0 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."=C2=A0 Without that, it= is impossible for a user to know whetherthe lack of documentation is inten= tional or an error to be reported here. --- ------=_Part_8608680_999115868.1578505816988 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: 7bit
> 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 not
been documented on purpose and which have not been documented due to
oversight?  It might be worth considering adding to future NEWS, when
a new function or variable is added, a some brief note saying that
"this function/variable will not (yet) be documented in one of the
manuals."  Without that, it is impossible for a user to know whether
the lack of documentation is intentional or an error to be reported here.

---

------=_Part_8608680_999115868.1578505816988--