[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: I'd like to request a change to the Emacs Info documentation
From: |
Samuel Banya |
Subject: |
Re: I'd like to request a change to the Emacs Info documentation |
Date: |
Fri, 21 Jan 2022 09:03:58 -0500 |
User-agent: |
Cyrus-JMAP/3.5.0-alpha0-4585-ga9d9773056-fm-20220113.001-ga9d97730 |
Hey Ramin,
I think its a good idea to just ask the 'emacs-devel@gnu.org' mailing list to
see if they can incorporate it into the manual.
I think its a good idea in general, so go for it!
~ Sam
On Thu, Jan 20, 2022, at 10:38 PM, Ramin Honary wrote:
> 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.
>
>