GNU bug report logs - #75634
29.1; Clearer prompt in info-lookup-change-mode

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 75634 in the body.
You can then email your comments to 75634 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Howard Melman <hmelman <at> gmail.com>
To: GNU Emacs <bug-gnu-emacs <at> gnu.org>
Subject: 29.1; Clearer prompt in info-lookup-change-mode
Date: Fri, 17 Jan 2025 11:02:59 -0500

I was reading emacs-devel in gnus and while reading a patch
I wanted to lookup named-let in the manual.  I ran
info-lookup-symbol but instead of having info open as usual
I was confronted with the prompt "Use symbol help mode: ".
My completion system (vertico) showed me a bunch of elisp
symbols, though it didn't quite register that they all ended
in "-mode" and I was wondering why named-let wasn't the
symbol at the top of the list as would normally happen.

I now understand the reason for this. It needs to find the
right manual and normally looks that up based on the major
mode, but gnus-article-mode wasn't of help here, so it was
asking me which major mode to use; but I didn't understand
the prompt and think it could be improved.

The prompt is in info-lookup-change-mode and the "symbol" is
either "symbol" or "file" depending on how the lookup
command was invoked.  I think something like "Major-mode to
lookup %s with: " would be much clearer.  It would be even
better if the prompt could include the actual string that
would be looked up ("named-let" in my example).

Howard

In GNU Emacs 29.1 (build 1, x86_64-apple-darwin21.6.0,
Carbon Version 165 AppKit 2113.6) of 2023-08-08 built on
Mac-1691500888998.local
Repository revision: e173249a143cee72d59ae78c4e11038512f5a00f
Repository branch: 29.1-mac-10.0
Windowing system distributor 'Apple Inc.', version 13.7.2
System Description:  macOS 13.7.2

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 75634 <at> debbugs.gnu.org
Subject: Re: bug#75634: 29.1; Clearer prompt in info-lookup-change-mode
Date: Sat, 18 Jan 2025 13:22:22 +0200

> From: Howard Melman <hmelman <at> gmail.com>
> Date: Fri, 17 Jan 2025 11:02:59 -0500
> 
> I was reading emacs-devel in gnus and while reading a patch
> I wanted to lookup named-let in the manual.  I ran
> info-lookup-symbol but instead of having info open as usual
> I was confronted with the prompt "Use symbol help mode: ".
> My completion system (vertico) showed me a bunch of elisp
> symbols, though it didn't quite register that they all ended
> in "-mode" and I was wondering why named-let wasn't the
> symbol at the top of the list as would normally happen.
> 
> I now understand the reason for this. It needs to find the
> right manual and normally looks that up based on the major
> mode, but gnus-article-mode wasn't of help here, so it was
> asking me which major mode to use; but I didn't understand
> the prompt and think it could be improved.
> 
> The prompt is in info-lookup-change-mode and the "symbol" is
> either "symbol" or "file" depending on how the lookup
> command was invoked.  I think something like "Major-mode to
> lookup %s with: " would be much clearer.

How about

  Major mode to use for looking up help on this %s

instead?

> It would be even better if the prompt could include the actual
> string that would be looked up ("named-let" in my example).

That'd need redesigning how these commands prompt for stuff.
Currently, they first prompt for a mode, and after that for the
symbol/file.  Patches welcome.

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

From: Howard Melman <hmelman <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#75634: 29.1; Clearer prompt in info-lookup-change-mode
Date: Sat, 18 Jan 2025 11:11:52 -0500

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

>> The prompt is in info-lookup-change-mode and the "symbol" is
>> either "symbol" or "file" depending on how the lookup
>> command was invoked.  I think something like "Major-mode to
>> lookup %s with: " would be much clearer.
>
> How about
>
>   Major mode to use for looking up help on this %s
>
> instead?

It's better than original.

1. I don't love "help" in here, because it's not using
help-mode but is looking up documentation in info manuals.

2. Both your and my suggestions suffer that they don't
explain that the major mode is used to qualify the symbol
(it's a lisp symbol) and not the "lookup mode" (like help or
info or man).

How about this?

  Use which major mode's manuals to lookup this %s

Other's I considered if you don't like the above:

  Which major mode's manuals to use to lookup this %s
  Major mode's manuals to use to lookup this %s
  Lookup this %s using the manuals of which major mode
  Lookup this %s using which major mode's manuals

-- 

Howard

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 75634 <at> debbugs.gnu.org
Subject: Re: bug#75634: 29.1; Clearer prompt in info-lookup-change-mode
Date: Sat, 18 Jan 2025 20:39:45 +0200

> From: Howard Melman <hmelman <at> gmail.com>
> Date: Sat, 18 Jan 2025 11:11:52 -0500
> 
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> The prompt is in info-lookup-change-mode and the "symbol" is
> >> either "symbol" or "file" depending on how the lookup
> >> command was invoked.  I think something like "Major-mode to
> >> lookup %s with: " would be much clearer.
> >
> > How about
> >
> >   Major mode to use for looking up help on this %s
> >
> > instead?
> 
> It's better than original.
> 
> 1. I don't love "help" in here, because it's not using
> help-mode but is looking up documentation in info manuals.

Then I can suggest

  Major mode whose documentation to look up about this %s

> 2. Both your and my suggestions suffer that they don't
> explain that the major mode is used to qualify the symbol
> (it's a lisp symbol) and not the "lookup mode" (like help or
> info or man).
> 
> How about this?
> 
>   Use which major mode's manuals to lookup this %s

This is confusing English-wise, IMO.  Please see if my suggestion
above solves your problem #2 as well.

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

From: Howard Melman <hmelman <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#75634: 29.1; Clearer prompt in info-lookup-change-mode
Date: Sat, 18 Jan 2025 16:09:25 -0500

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

>> 1. I don't love "help" in here, because it's not using
>> help-mode but is looking up documentation in info manuals.
>
> Then I can suggest
>
>   Major mode whose documentation to look up about this %s
>
>> 2. Both your and my suggestions suffer that they don't
>> explain that the major mode is used to qualify the symbol
>> (it's a lisp symbol) and not the "lookup mode" (like help or
>> info or man).
>>
>> How about this?
>>
>>   Use which major mode's manuals to lookup this %s
>
> This is confusing English-wise, IMO.  Please see if my suggestion
> above solves your problem #2 as well.

Can you explain what you find confusing about this? (native
US english speaker here).  I see that "lookup" should properly
be "look up" but I don't think that's confusing.

I find the possessive "major mode's manuals" clearer than
"Major mode whose documentation".  Also the mapping is
really major mode to manuals to find the symbol's
documentation, as confirmed in info-lookup-symbol's
docstring "MODE is the major mode whose Info manuals to
search for the documentation of SYMBOL."

Also I find "to look up about this %s" a bit awkward.

I had copied the original's prompt beginning with "Use" but
I see you're not.  It's also perhaps too generic a
verb. Maybe this works for both of us?

   Search which major mode's manuals for documentation of %s

-- 

Howard

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 75634 <at> debbugs.gnu.org
Subject: Re: bug#75634: 29.1; Clearer prompt in info-lookup-change-mode
Date: Sun, 19 Jan 2025 07:48:03 +0200

> From: Howard Melman <hmelman <at> gmail.com>
> Date: Sat, 18 Jan 2025 16:09:25 -0500
> 
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> 1. I don't love "help" in here, because it's not using
> >> help-mode but is looking up documentation in info manuals.
> >
> > Then I can suggest
> >
> >   Major mode whose documentation to look up about this %s
> >
> >> 2. Both your and my suggestions suffer that they don't
> >> explain that the major mode is used to qualify the symbol
> >> (it's a lisp symbol) and not the "lookup mode" (like help or
> >> info or man).
> >>
> >> How about this?
> >>
> >>   Use which major mode's manuals to lookup this %s
> >
> > This is confusing English-wise, IMO.  Please see if my suggestion
> > above solves your problem #2 as well.
> 
> Can you explain what you find confusing about this? (native
> US english speaker here).

The "Use which mode" part.  It's more natural to say "Which mode to
use" instead, but in any case, both wordings are phrased as a
question, whereas our prompts in Emacs are usually not questions.  For
example, "C-x C-f" prompts with "Find file:", not with "Find which
file" or "Which file to find".

> I find the possessive "major mode's manuals" clearer than
> "Major mode whose documentation".

We could use "manuals", but that would reveal some of the command's
implementation.  What if tomorrow the command will be extended to
search the doc strings as well?  "Documentation" sounds less specific
and still accurate.

> Also the mapping is really major mode to manuals to find the
> symbol's documentation, as confirmed in info-lookup-symbol's
> docstring "MODE is the major mode whose Info manuals to search for
> the documentation of SYMBOL."

I know what the command does and how it works, but do we really need
to describe all that in the prompt?

> I had copied the original's prompt beginning with "Use" but
> I see you're not.  It's also perhaps too generic a
> verb. Maybe this works for both of us?
> 
>    Search which major mode's manuals for documentation of %s

This is again phrased as a question.  Also, "documentation of symbol"
sounds vague and somewhat confusing (did you think %s stands for the
name of the symbol, perhaps?)  But if you prefer this choice of words,
then how about

  Major mode whose documentation to search for this %s

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

From: Howard Melman <hmelman <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#75634: 29.1; Clearer prompt in info-lookup-change-mode
Date: Sun, 19 Jan 2025 09:19:44 -0500

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

> The "Use which mode" part.  It's more natural to say "Which mode to
> use" instead, but in any case, both wordings are phrased as a
> question, whereas our prompts in Emacs are usually not questions.  For
> example, "C-x C-f" prompts with "Find file:", not with "Find which
> file" or "Which file to find".

I looked for documentation about conventions for prompts and
couldn't find any.  Is this written someplace?

>> I find the possessive "major mode's manuals" clearer than
>> "Major mode whose documentation".
>
> We could use "manuals", but that would reveal some of the command's
> implementation.  What if tomorrow the command will be extended to
> search the doc strings as well?  "Documentation" sounds less specific
> and still accurate.

That seems unlikely given the command is in the info package
and there are other commands to search docstrings.  If the
command is changed, its prompt could be changed (and in fact
this prompt probably wouldn't be needed).

>> Also the mapping is really major mode to manuals to find the
>> symbol's documentation, as confirmed in info-lookup-symbol's
>> docstring "MODE is the major mode whose Info manuals to search for
>> the documentation of SYMBOL."

> I know what the command does and how it works, but do we really need
> to describe all that in the prompt?

I know you know what it does.  My point was the prompt needs
to say what it's asking the user for, and that this mapping
is exposed to the user in the docstring.  It's an uncommon
prompt (first time I saw it in years if not decades of use)
so being clear helps, and what it's asking for is indirect,
so it's complicated.

> This is again phrased as a question.  Also, "documentation of symbol"
> sounds vague and somewhat confusing (did you think %s stands for the
> name of the symbol, perhaps?)

No, but I find the inclusion of symbol or file in this
prompt kind of vague and I thought my proposal sounded
similar in that respect to all the others.

> But if you prefer this choice of words, then how about
>
>   Major mode whose documentation to search for this %s

I prefer "manuals" to "documentation" but otherwise this is
fine.

Thanks.

-- 

Howard

Message #30 received at 75634-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 75634-done <at> debbugs.gnu.org
Subject: Re: bug#75634: 29.1; Clearer prompt in info-lookup-change-mode
Date: Sat, 25 Jan 2025 12:12:23 +0200

> From: Howard Melman <hmelman <at> gmail.com>
> Date: Sun, 19 Jan 2025 09:19:44 -0500
> 
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > But if you prefer this choice of words, then how about
> >
> >   Major mode whose documentation to search for this %s
> 
> I prefer "manuals" to "documentation" but otherwise this is
> fine.

Thanks, installed on the emacs-30 branch, and closing the bug.

Previous Next

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