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

From: Stefan Kangas <[email-masked]>
Date: Wed, 7 Feb 2024 12:22:55 -0800

Eli Zaretskii <[email-masked]> writes:

>> Date: Tue, 6 Feb 2024 20:26:08 -0800
>> Cc: [email-masked]
>> From: Jim Porter <[email-masked]>
>>
>> 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?

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

However, I agree that the section is a bit long and unwieldy.  To make
it shorter, how about moving the section "Defining new built-in
commands" to some other part of the manual instead?  For example some
chapter that talks about "Extending Eshell" or similar.

Just my two cents.