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

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

[Ramin Honary]

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.

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

[Po Lu]

Ramin Honary <ramin.honary@cross-compass.com> writes:

> 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.

This isn't much of a question, so I think it should be sent to
bug-gnu-emacs or emacs-devel instead.

> 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)

Does `m' really search the menu?  I thought it just asks for a menu item
to jump to.

>    - Press `s` to do a full text search.

This should probably mention that regexps are accepted.

>    - Press `q` to quit (close this screen)

I don't understand what kind of screen you refer to here.

> 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-search works in Info, so most Emacs users would probably try that
first.  Secondly, I think the best place to place this information (if
the advanced search functionality is indeed as important as you say it
is, of that I have no opinion) would be somewhere in section 1 of the
Info manual, instead of some extra text at the top level of the
directory node, since that text is not generated by Emacs.

Also, doesn't this kind of change have to be coordinated with the
stand-alone Info developers?  IIRC, the same documentation is used by
both Info readers.

Thanks.

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.)

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

[Emanuel Berg via Users list for the GNU Emacs text editor]

Eli Zaretskii wrote:

> 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.

Actually it is very simple.

The question is, Is it a good idea?

If yes, we should implement it everywhere it makes sense.

If not, we shouldn't, and nowhere at that.

-- 
underground experts united
https://dataswamp.org/~incal

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

[Jean Louis]

* Ramin Honary <ramin.honary@cross-compass.com> [2022-01-21 06:39]:
> 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.

It is better to tell that on development mailing list.

Even better is to M-x report-bug and send your suggestions.


-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

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

[Emanuel Berg via Users list for the GNU Emacs text editor]

Jean Louis 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.
>
> It is better to tell that on development mailing list.

I hope so!

-- 
underground experts united
https://dataswamp.org/~incal

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

[Samuel Banya]

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.
> 
> 

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

[Emanuel Berg via Users list for the GNU Emacs text editor]

Samuel Banya wrote:

> 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.

Isn't what the OP asks for in effect a search algorithm and
interface that can be displayed/brought up and used, the same
one for all and every Texinfo manuals?

If some info cowboy think its disruptive I should be
configurable to not show unless called for, of course.
And everything else about it should be configurable as well.
Just add options for everything while you go along, it is
actually natural for your own programming/devel purposes as
well so there is no conflict of interests or anything ...

Do it today - in a different way!

-- 
underground experts united
https://dataswamp.org/~incal