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

Previous Next

Full log

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

Previous Next

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