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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 7 Feb 2024 18:05:07 -0800
> Cc: 68963@debbugs.gnu.org
> From: Jim Porter <jporterbugs@gmail.com>
> 
> On 2/7/2024 12:22 PM, Stefan Kangas wrote:
> > Eli Zaretskii <eliz@gnu.org> writes:
> > 
> >> 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?
> > 
> > FWIW, I tend to agree with Eli: having all built-in commands on one page
> > also provides some benefit, especially to power users (the likely
> > audience for eshell) that are already familiar with a standard Unix
> > shell and just wants to know "what's different about Eshell" or "what
> > does Eshell provide".
> 
> Ok, no problem. It just seemed a bit hard to navigate to me, but I don't 
> have any issues with keeping all the commands together.

I'm not against subdividing that section.  My point was that if you
want these commands to be easier to find, the subdivision itself is
not enough; you need additional measures.

> How about the attached patch instead? It just moves the list of commands 
> to a sub-node, and also makes the "defining new built-ins" a proper 
> sub-node too. That should keep things a bit easier to navigate, and then 
> we can add more indexing as needed later.

No objections here.  But once again: your points about being able to
find the commands by categories are well-taken, and adding indexing to
make that easier would also be a good change.

Thanks.