GNU bug report logs - #70163
29.3; hexl-mode incorrect docstring

Previous Next

Full log

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

From: Thierry Volpiatto <thievol <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 70163 <at> debbugs.gnu.org, schwab <at> linux-m68k.org, monnier <at> iro.umontreal.ca
Subject: Re: bug#70163: 29.3; hexl-mode incorrect docstring
Date: Thu, 04 Apr 2024 05:47:40 +0000

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

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

>> From: Thierry Volpiatto <thievol <at> posteo.net>
>> Cc: Eli Zaretskii <eliz <at> gnu.org>,  Stefan Monnier
>>  <monnier <at> iro.umontreal.ca>,  70163 <at> debbugs.gnu.org
>> Date: Wed, 03 Apr 2024 17:04:04 +0000
>> 
>> 
>> Andreas Schwab <schwab <at> linux-m68k.org> writes:
>> 
>> > On Apr 03 2024, Eli Zaretskii wrote:
>> >
>> >>> From: Thierry Volpiatto <thievol <at> posteo.net>
>> >>> Date: Wed, 03 Apr 2024 15:02:52 +0000
>> >>> 
>> >>> 
>> >>> Hexl-mode docstring specify "\<hexl-mode-map>" 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)
>> >>>       "\\<hexl-mode-map>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.


-- 
Thierry

[signature.asc (application/pgp-signature, inline)]

Previous Next

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