bug#68963: 30.0.50; [PATCH] Split Eshell built-in command documentation into subsections

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 6 Feb 2024 20:26:08 -0800
> Cc: 68963@debbugs.gnu.org
> From: Jim Porter <jporterbugs@gmail.com>
> 
> On 2/6/2024 7:31 PM, Eli Zaretskii wrote:
> >> Date: Tue, 6 Feb 2024 16:02:32 -0800
> >> From: Jim Porter <jporterbugs@gmail.com>
> >>
> >> Currently, the Eshell manual lists all the built-in commands in one
> >> section, which can make it hard to find the commands related to the
> >> topic you care about. Here's a patch to split this into subsections of
> >> various (loosely-defined) topics.
> > 
> > If people look for commands by using 'i' (Info-index), then finding
> > them in a single long section will be as easy as doing that in several
> > shorter ones.
> 
> The use-case I was imagining for this was a person thinking, "What 
> commands does Eshell have for working with [say] directories?"

But then subdivision into sections has other problems.  For example,
who says that 'ls' is only "for directories", ln, mv, and rm are only
"for files", and info is "for searching"?  A person can reasonably
think about these (and others) differently.  And why "basename" is not
about files?

That is why we use indexing for providing flexible and accurate search
capabilities: you can have more than one index entry for each piece of
text, so you can satisfy different use cases where people have
different phrases on their mind when thinking about something.

So the right way of handling this is to use better indexing.  You
could index each command, for example:

  @cindex deleting files and directories
  @cindex file commands, deletion
  [text about 'rm' here]

and in addition, you could have a short section with a list of
"file-related commands", where each command or group of commands is
followed by a cross-reference to the relevant place/section.

Using sectioning for these purposes is not flexible enough to satisfy
enough use cases, because it supports only a single way of looking at
a subject, and people tend to think about them differently, especially
if they need that in different contexts.