From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#70163: 29.3; hexl-mode incorrect docstring Date: Thu, 04 Apr 2024 15:18:27 +0300 Message-ID: <86r0fl723w.fsf@gnu.org> References: <871q7mlc9v.fsf@posteo.net> <86plv68myf.fsf@gnu.org> <878r1ucsgq.fsf@igel.home> <87a5mal6nv.fsf@posteo.net> <86le5u8g9z.fsf@gnu.org> <87r0fly8zn.fsf@posteo.net> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="5043"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 70163@debbugs.gnu.org, schwab@linux-m68k.org To: Thierry Volpiatto , monnier@iro.umontreal.ca Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Apr 04 14:19:20 2024 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 1rsM3r-00013D-On for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 04 Apr 2024 14:19:19 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rsM3W-00088p-Ln; Thu, 04 Apr 2024 08:18:58 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rsM3V-00088g-48 for bug-gnu-emacs@gnu.org; Thu, 04 Apr 2024 08:18:57 -0400 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rsM3U-00066P-Qf for bug-gnu-emacs@gnu.org; Thu, 04 Apr 2024 08:18:56 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rsM3Z-0007bS-Lt for bug-gnu-emacs@gnu.org; Thu, 04 Apr 2024 08:19:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 04 Apr 2024 12:19:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 70163 X-GNU-PR-Package: emacs Original-Received: via spool by 70163-submit@debbugs.gnu.org id=B70163.171223313729217 (code B ref 70163); Thu, 04 Apr 2024 12:19:01 +0000 Original-Received: (at 70163) by debbugs.gnu.org; 4 Apr 2024 12:18:57 +0000 Original-Received: from localhost ([127.0.0.1]:60738 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rsM3V-0007bA-5s for submit@debbugs.gnu.org; Thu, 04 Apr 2024 08:18:57 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:44816) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rsM3S-0007aM-8e for 70163@debbugs.gnu.org; Thu, 04 Apr 2024 08:18:56 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rsM3G-00060W-RL; Thu, 04 Apr 2024 08:18:42 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=9X68XRZI8knmG4O2U6H013QrFjtm9BgykmYkzuVLJAo=; b=nuZYmqwIKvOXQlw7rN/6 2DycacPDUV6De4UO2ROTv1gMerXFSZmmVeOt03aJ3vZKBmn1vGE5KDMzgGh1MRtN+6X0oUZhOUE/n pgNdlxTdBoCRiKLRv67+DAPY4jQjcFNtXmHPxXSD6WhonUNolp+f3Ox8mVvmfZoD9OOwz1ZOsaEUC r+T1nQQGWkbrbnVS25GLvRlF8DXc8+gtR8xwKD50II2QwTXG0Nmwd0Ilbt9jTJPkcGJd9vDmSpOXV NufifKWZoR6h1u9yoz5WZe7l2eW/xTdyKjp352hO8BovLIuN3IMyr0m2yg0EY1I/41lqjI+1lFe9O HyvjGZefgCvx2w==; In-Reply-To: <87r0fly8zn.fsf@posteo.net> (message from Thierry Volpiatto on Thu, 04 Apr 2024 05:47:40 +0000) 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-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:282638 Archived-At: > From: Thierry Volpiatto > Cc: schwab@linux-m68k.org, monnier@iro.umontreal.ca, 70163@debbugs.gnu.org > Date: Thu, 04 Apr 2024 05:47:40 +0000 > > >> >>> Hexl-mode docstring specify "\" in its first line, this > >> >>> to specify some keybinding related to this map at end, as a result the > >> >>> documentation command returns a three line string, the first line beeing > >> >>> a blank line until hexl.el is loaded. I think docstrings generally > >> >>> should not have this specification in their first line. > >> >>> > >> >>> (defun hexl-mode (&optional arg) > >> >>> "\\A mode for editing binary files in hex dump format. > >> >>> [...] > >> >>> Most cursor movement bindings are the same: use \\[hexl-backward-char], > >> >>> [...] > >> >> > >> >> What do you suggest to do instead? > >> > > >> > Customary is to put it directly before the (first) keymap reference. > >> > >> Exactly. > > > > So we don't want an empty line at the beginning of a doc string, but > > are okay with having it farther into the doc string? > > Yes, this would avoid loading the whole file just for having the first line of > the documentation. > > Actually, (documentation 'hexl-mode) returns: > > "\nUses keymap `hexl-mode-map', which is not currently defined.\nA mode for editing binary files in hex dump format..." > > But once it is loaded: > > "A mode for editing binary files in hex dump format..." > > I think it is a good practice to specify keymap just when needed as > specified in the manual: > > • In documentation strings for a major mode, you will want to refer > to the key bindings of that mode’s local map, rather than global > ones. Therefore, use the construct ‘\\<...>’ once in the > documentation string to specify which key map to use. Do this > before the first use of ‘\\[...]’. The text inside the ‘\\<...>’ > should be the name of the variable containing the local keymap for > the major mode. Does the patch below gives any better results? It doesn't look better to me: the "Uses keymap..." blurb gets in the way and makes the documentation text wrong. And it will happen regardless of where you stuff the \\<..> thing, just in different places of the test. It looks like this feature was not meant to be used with libraries that aren't loaded, or maybe the intent is to use the RAW argument in those cases. Stefan, why do we inject this ugly blurb into the text we return when the library is not loaded? why not simply return the same as RAW does in those cases? diff --git a/lisp/hexl.el b/lisp/hexl.el index 1288cf4..938b218 100644 --- a/lisp/hexl.el +++ b/lisp/hexl.el @@ -256,10 +256,10 @@ hexl-line-displen ;;;###autoload (defun hexl-mode (&optional arg) - "\\A mode for editing binary files in hex dump format. + "A mode for editing binary files in hex dump format. This is not an ordinary major mode; it alters some aspects of the current mode's behavior, but not all; also, you can exit -Hexl mode and return to the previous mode using `hexl-mode-exit'. +Hexl mode and return to the previous mode using \\\\[hexl-mode-exit]. This function automatically converts a buffer into the hexl format using the function `hexlify-buffer'.