Re: I'd like to request a change to the Emacs Info documentation

[Eli Zaretskii]

> From: Ramin Honary <ramin.honary@cross-compass.com>
> Date: Fri, 21 Jan 2022 12:38:36 +0900
> 
> Hello, everyone. I thought it would be better to ask my question here
> first, so I don't end up adding noise to the emacs-devel@gnu.org
> mailing list.

Thank you for your interest in Emacs.

> I would like to change the top-level node of the Info document for
> Emacs so that it displays in prominent lettering how to do index
> search (bound to the "i" key) and full text search (bound to the "s"
> key) at the top of the document. I would like it to read:
> 
>    SEARCH IN THIS MANUAL:
>    - Press `i` to enter an index search term
>    - Press `m` to search this "menu" (the table of contents)
>    - Press `s` to do a full text search.
>    --------------------------------------------
>    - Press `q` to quit (close this screen)
>    - Press `H` for more help with keyboard shortcuts.

I don't think it's a good idea to add this to the Emacs manual,
because it's just one manual.  We'd need to add it to every Info
manual, if we want to go that way.

The comprehensive information about using Info is displayed if you
press '?' in Info mode.  That includes the search commands.  Why isn't
that enough for people who are not yet proficient with Info?

> The justification is that search is considered essential functionality
> in documentation nowadays, if people do not find search functionality
> *immediately* they go to Google to search instead. Ideally, the
> documentation would present an interactive search at the very top, as
> most modern documentation browsers do. But failing that, the next best
> thing is to put up an easy-to-read sign about how to do search.

I think you are exaggerating.  The search commands are indeed
important, but so are the commands to move between nodes, go to a
cross-reference and come back, etc.  Info is a sophisticated mode, so
it is impossible to squeeze its main capabilities into just a couple
of commands.

> As it is now, if you follow the instructions at the top of the Emacs
> manual, it merely tells you to press "h" to learn more about how to
> use the Info documentation browser, and pressing "h" only takes you to
> section 1.2 of the Info manual.

That is inaccurate.  Here's what Info presents upon entry:

  This (the Directory node) gives a menu of major topics.
  Typing "q" exits, "?" lists all Info commands, "d" returns here,
  "h" gives a primer for first-timers,
  "mEmacs<Return>" visits the Emacs manual, etc.

  In Emacs, you can click mouse button 2 on a menu item or cross reference
  to select it.

So it does say quite a bit more in addition to 'h', and it does
mention '?', which describes all the important commands, including
search.  We could add there a couple more lines, but not too many, I
think.  (And this text is not from the Emacs manual, it's the
"greeting" displayed by the Info mode in general.)