help-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Ramin Honary
Subject: I'd like to request a change to the Emacs Info documentation
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.

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.

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.

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. How to search is not listed anywhere
in section 1 of the Info manual, it is listed in section 2 under the
"Advanced" functionality, so not only is search NOT the first thing an
end user sees, they would likely have a hard time finding it.

Search is not an "advanced" feature, it is *essential.* And I would
argue that any mention of the most important feature of an interactive
documentation browser has been completely buried, which is
unfortunate.

I first brought it up online on Reddit in this thread:
https://www.reddit.com/r/emacs/comments/s4za7y/comment/hsz1cqb/  and
decided to find out what I can do to go ahead and make this change, if
the developers find it to be a reasonable request.

Any advice on my next steps toward making this change is appreciated.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]