From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description Date: Sat, 11 Jul 2020 13:28:34 -0700 (PDT) Message-ID: <14cf9f7a-0c6b-4c26-b4b9-ee95a470ce15@default> References: <87h7udzwuq.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="2695"; mail-complaints-to="usenet@ciao.gmane.io" To: Matthias Meulien , 42325@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Jul 11 22:29:10 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1juM7S-0000br-2y for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 11 Jul 2020 22:29:10 +0200 Original-Received: from localhost ([::1]:34920 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1juM7Q-0007HD-O5 for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 11 Jul 2020 16:29:08 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38018) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1juM7K-0007H6-5V for bug-gnu-emacs@gnu.org; Sat, 11 Jul 2020 16:29:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:33424) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1juM7J-0003su-RP for bug-gnu-emacs@gnu.org; Sat, 11 Jul 2020 16:29:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1juM7J-0001pb-Nd for bug-gnu-emacs@gnu.org; Sat, 11 Jul 2020 16:29:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 11 Jul 2020 20:29:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 42325 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 42325-submit@debbugs.gnu.org id=B42325.15944993337026 (code B ref 42325); Sat, 11 Jul 2020 20:29:01 +0000 Original-Received: (at 42325) by debbugs.gnu.org; 11 Jul 2020 20:28:53 +0000 Original-Received: from localhost ([127.0.0.1]:44970 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1juM7A-0001pF-RG for submit@debbugs.gnu.org; Sat, 11 Jul 2020 16:28:53 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:40054) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1juM78-0001p3-0Y for 42325@debbugs.gnu.org; Sat, 11 Jul 2020 16:28:50 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 06BKOqHP107112; Sat, 11 Jul 2020 20:28:44 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=ZAC3eU6P9dC6Nofjfnuag6Vx64lNKnUrUuoEotf8vKM=; b=hxKEfFPBIfhhsyGYW2s/q0YWGV42FXgFkdS7Qp0KKRPqSYVE0/f5YQ3Cv1tuKxaus2u4 Ao0XVNJ4vloerKiiJR8OFoAenF4GV2tfLwyc4VQgzh/FffQ7E6v9FcCh+ThWBW7vkNTL ENR1wNq+s4RmljM8JHejEgJiF27SPjFGhfvqbeKyVe04nd+bnQL0vcRG9TSfmU8RQh1N wcquHym8lTLRgHYobOqjs77Phk04pDuKP3zcng+xI9qDypKarcHrTLhWpE2kKupUrGmK BorgnpCyT8Y2YAmNVqmpH/ztVpPR4mTUE11vkHyd7fDqK2HR6F016UugL+h8XLLbJcQL wQ== Original-Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2120.oracle.com with ESMTP id 32762n1x42-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Sat, 11 Jul 2020 20:28:44 +0000 Original-Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 06BKNQ1g124328; Sat, 11 Jul 2020 20:28:43 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserp3030.oracle.com with ESMTP id 3273fbqqxa-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 11 Jul 2020 20:28:43 +0000 Original-Received: from abhmp0012.oracle.com (abhmp0012.oracle.com [141.146.116.18]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id 06BKSbUQ019615; Sat, 11 Jul 2020 20:28:42 GMT In-Reply-To: <87h7udzwuq.fsf@gmail.com> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.5017.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9679 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 mlxlogscore=999 phishscore=0 spamscore=0 adultscore=0 mlxscore=0 bulkscore=0 malwarescore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2007110161 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9679 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 mlxscore=0 malwarescore=0 spamscore=0 clxscore=1011 priorityscore=1501 mlxlogscore=999 lowpriorityscore=0 bulkscore=0 suspectscore=0 phishscore=0 adultscore=0 impostorscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2006250000 definitions=main-2007110161 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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.io gmane.emacs.bugs:182928 Archived-At: > When one call describe-mode from *Bookmark List* buffer, the > displayed documentation for the Bookmark Menu major mode displays > an incomplete hard-coded keymap: The useful key / > (bookmark-bmenu-search) isn't listed. I propose to rely on > derived-mode-make-docstring to put the mode's keymap in mode > docstring and to remove the currently hardcoded keymap > description. That's definitely a step backward, IMHO. Just add `/' to the list. A mode's `C-h m' documentation can, but need not, list all of its key bindings. (It can also tell users that they can use `C-h b'.) But more importantly, it should describe the mode, not just punt to say that it inherits from its parent. The doc of `derived-mode-make-docstring' should, and I think does, make clear that it provides only rudimentary, fallback help in the (hopefully rare) case where there is no other such help. "Construct a docstring for a new mode if none is provided." ^^^^^^^^^^^^^^^^^^^ It doesn't say that it's a good idea to not provide a doc string for a derived mode, and to instead use this to construct one. Thank goodness. Providing a doc string is normal. Not providing one is to be avoided, and IMO, is a bug from a user point of view. There's little excuse for copping out and not providing a doc string. There's even less excuse for doing that for a mode's doc. And there's still less excuse for _replacing_ hand-written help with such a poor, generic, robotic fallback. Please just do the right thing, adding the help you think is missing. And provide whatever other manual updates you think might help. [To be clear, this doesn't affect me or my code. Bookmark+ doesn't use the mode help provided by vanilla bookmark.el. I'm just expressing my concern for vanilla Emacs here.]