unofficial mirror of help-gnu-emacs@gnu.org
 help / color / mirror / Atom feed
From: Ramin Honary <ramin.honary@cross-compass.com>
To: help-gnu-emacs@gnu.org
Subject: I'd like to request a change to the Emacs Info documentation
Date: Fri, 21 Jan 2022 12:38:36 +0900	[thread overview]
Message-ID: <CAEcHWvoKUqwq_bj8MK_KMWC-MtcdHXMMif5Rbs9Lr4d8BOkYvg@mail.gmail.com> (raw)

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	other threads:[~2022-01-21  3:38 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-01-21  3:38 Ramin Honary [this message]
2022-01-21  3:53 ` I'd like to request a change to the Emacs Info documentation Po Lu
2022-01-21  7:35 ` Eli Zaretskii
2022-01-21 11:57   ` Emanuel Berg via Users list for the GNU Emacs text editor
2022-01-21 10:40 ` Jean Louis
2022-01-21 11:57   ` Emanuel Berg via Users list for the GNU Emacs text editor
2022-01-21 14:03 ` Samuel Banya
2022-01-21 15:40   ` Emanuel Berg via Users list for the GNU Emacs text editor

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CAEcHWvoKUqwq_bj8MK_KMWC-MtcdHXMMif5Rbs9Lr4d8BOkYvg@mail.gmail.com \
    --to=ramin.honary@cross-compass.com \
    --cc=help-gnu-emacs@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).