From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Thierry Volpiatto Newsgroups: gmane.emacs.bugs Subject: bug#70163: 29.3; hexl-mode incorrect docstring Date: Thu, 04 Apr 2024 05:47:40 +0000 Message-ID: <87r0fly8zn.fsf@posteo.net> References: <871q7mlc9v.fsf@posteo.net> <86plv68myf.fsf@gnu.org> <878r1ucsgq.fsf@igel.home> <87a5mal6nv.fsf@posteo.net> <86le5u8g9z.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="1413"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 70163@debbugs.gnu.org, schwab@linux-m68k.org, monnier@iro.umontreal.ca To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Apr 04 07:47:31 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 1rsFwh-0000C5-CY for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 04 Apr 2024 07:47:31 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rsFwD-0001Sj-76; Thu, 04 Apr 2024 01:47:01 -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 1rsFwB-0001S8-1d for bug-gnu-emacs@gnu.org; Thu, 04 Apr 2024 01:46:59 -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 1rsFwA-0007jp-PD for bug-gnu-emacs@gnu.org; Thu, 04 Apr 2024 01:46:58 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rsFwF-0007Gj-Gd for bug-gnu-emacs@gnu.org; Thu, 04 Apr 2024 01:47:03 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Thierry Volpiatto Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 04 Apr 2024 05:47:03 +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.171220959827731 (code B ref 70163); Thu, 04 Apr 2024 05:47:03 +0000 Original-Received: (at 70163) by debbugs.gnu.org; 4 Apr 2024 05:46:38 +0000 Original-Received: from localhost ([127.0.0.1]:60196 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rsFvp-0007DD-Ok for submit@debbugs.gnu.org; Thu, 04 Apr 2024 01:46:38 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]:57897) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rsFvl-0007CG-8e for 70163@debbugs.gnu.org; Thu, 04 Apr 2024 01:46:36 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 4F45C24002A for <70163@debbugs.gnu.org>; Thu, 4 Apr 2024 07:46:22 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1712209582; bh=/c/q2CSTjeAZoLYHpx46+a+cZ8R/bMJVEng9hxKxOmc=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:Content-Type: Autocrypt:OpenPGP:From; b=Hea+zIIMqgCyFev4OqBizJmytUemqPkFNC/zrWRVnyayh/eCCbQJKtLv5Pr5/PwGp ZkmxjQ2HNweFi9T0SvyF9ZjdofTz301kwoGI4sh1VM3oOGxsAWPvKd1PyvMMntANJS +7bw65cV/BfkkjBpgZ6Chyj4AzBiDfZWXJEtVUFGTUKzw61A4UICzKsLs4rGUgE2yb PxhHdcDzdcRDgZQrypOQpZR4QdQtgoU7JL0KcZ8sHqo5GYGQTZIbjq0W1E2VLAq/Bj MGTAtevOlZHebiXB9GgYyDB6cDZL5K7PDgQk6B//ilmqvEfWM7dRbpvXlKLYzUamCr 2PIFB5tvL27kw== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4V99bH4CTqz6tvn; Thu, 4 Apr 2024 07:46:19 +0200 (CEST) In-Reply-To: <86le5u8g9z.fsf@gnu.org> (Eli Zaretskii's message of "Wed, 03 Apr 2024 21:14:48 +0300") Autocrypt: addr=thievol@posteo.net; prefer-encrypt=mutual; keydata=xsDNBF8ylcIBDADG+hy+zR6L4/vbdDDZuSaMmSrU3A5QZJpeBCvxTr7MpzzruZbhLPW1K3R6N2MA edi8Y+C8o27FVRIjpdbaKMGu9je7JV/TbUQYo3SOwCK1vM4LUn4V6ZLzSYkuiEt4eyMoiDdyvN0p kcK6P9x9DCetcEVszXzQg+yzCVrQ2hXWDXWT4M18EC3wtO7RHPouMqGiwBFhBAYErCqFWFxQHkfb tG/4yGyJ58rglb65O3qijjMWvYwcWZun9/7qm8Z4/4mHopmo2zgU+OrptnLSZfkZGz3Y7Uf452xQ GVq0Fv75NPvQru7y+DYVhuVXXyAmGxt+vf4rIiixMBbhKEPjcxEPAa2LTzex2IsTZR+QVG9uDnqC WcgaOEQ58fzXNvNhtwwF/Rgio2XWAJVdmFWS59/k9W58CIUSNKBMZh2XeGdEmtHvDtCxW3z6FJha 36RzOM3fMNNiAGdFZJA84gcdloJR+sHCDTTPT3784fjr+V8An7sI581NGFzkRQqPvEQCZbUAEQEA Ac0SdGhpZXZvbEBwb3N0ZW8ubmV0wsEOBBMBCgA4AhsDBQsJCAcCBhUKCQgLAgQWAgMBAh4BAheA FiEEI9twfRN7r3nig/xwDsVtFB0W75MFAmL3HCoACgkQDsVtFB0W75OVEAv/f6XxmtIFz08fUb8h Bp/zJP6IC4/rhhh+0GMRIRzLN8DK0jV8JCzYdFHiRJOy2lNIOpmrrCmjRRxferc2G42+ePFIsslx hU46VSz1Z83NwIG3mpdYNV5WUTUdgzxExHTNTFCd7NKv0nlHKQaA OpenPGP: url=https://posteo.de/keys/thievol@posteo.net.asc; preference=encrypt 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:282619 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Eli Zaretskii writes: >> From: Thierry Volpiatto >> Cc: Eli Zaretskii , Stefan Monnier >> , 70163@debbugs.gnu.org >> Date: Wed, 03 Apr 2024 17:04:04 +0000 >>=20 >>=20 >> Andreas Schwab writes: >>=20 >> > On Apr 03 2024, Eli Zaretskii wrote: >> > >> >>> From: Thierry Volpiatto >> >>> Date: Wed, 03 Apr 2024 15:02:52 +0000 >> >>>=20 >> >>>=20 >> >>> Hexl-mode docstring specify "\" in its first line, th= is >> >>> to specify some keybinding related to this map at end, as a result t= he >> >>> documentation command returns a three line string, the first line be= eing >> >>> a blank line until hexl.el is loaded. I think docstrings generally >> >>> should not have this specification in their first line. >> >>>=20 >> >>> (defun hexl-mode (&optional arg) >> >>> "\\A mode for editing binary files in hex dump = format. >> >>> [...]=20 >> >>> Most cursor movement bindings are the same: use \\[hexl-backwa= rd-char], >> >>> [...] >> >> >> >> What do you suggest to do instead? >> > >> > Customary is to put it directly before the (first) keymap reference. >>=20 >> 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: =E2=80=A2 In documentation strings for a major mode, you will want to re= fer to the key bindings of that mode=E2=80=99s local map, rather than glob= al ones. Therefore, use the construct =E2=80=98\\<...>=E2=80=99 once in = the documentation string to specify which key map to use. Do this before the first use of =E2=80=98\\[...]=E2=80=99. The text inside th= e =E2=80=98\\<...>=E2=80=99 should be the name of the variable containing the local keymap for the major mode. =2D-=20 Thierry --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQHHBAEBCgAxFiEEI9twfRN7r3nig/xwDsVtFB0W75MFAmYOPv0THHRoaWV2b2xA cG9zdGVvLm5ldAAKCRAOxW0UHRbvk6LcDACdvYeB8FvYgG66M/7DCIsyT26uOBLE yWmvyItFC2hQjX00xBwYv14SgyDA5jmDXX6LiLNPp09klCWPaxU+AbFxaYknErjK Cb8eGj5HiuSPDZ5u+O19yAU7UwHd84H1mRksBJtNLdw1q4DQrrYdwv+2Yek9z9d2 OfQ7gVkZTeYQeA3ENlEoF0LHeFZEN9cntNXqgEOZ+ske0RZ1gbB8zduFX+NCl8O6 jeVBDEjKyog5oaSXPQJtwIbWMEbVDVocUY2FSu4Mp1a0LUIASkR1xIUxsaQtQAy3 ddQg9I+feer7Em8zi4btl2uodjHsftuFhFkqoqoMU1k+UYlhyFJA7C5TciHp04mH Q8Jszq2RjPP6jxs2qmYbSg7v2wuwwG+iOJmivq03YtuVKFTL8P+Nl5l4b/uQXYCU gBe7lvJTmBjCkKFU/VYyjU9b2xrtmGVwwg10cImrs5K6rn+Qywr1mRH9P9FGrLYi jEPSPovLu9ptM9dT6MEC+fL/H/mWko6FRxA= =j+GJ -----END PGP SIGNATURE----- --=-=-=--