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

[Jim Porter <jporterbugs@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1386 bytes --]

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.

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

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.

[-- Attachment #2: 0001-Put-the-list-of-built-in-Eshell-commands-in-its-own-.patch --]
[-- Type: text/plain, Size: 1924 bytes --]

From 4d74fc9d500bcc1b2ac350b5df3edb7b1671d3cc Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Wed, 7 Feb 2024 17:58:31 -0800
Subject: [PATCH] Put the list of built-in Eshell commands in its own manual
 node

* doc/misc/eshell.texi (Built-ins): Fix capitalization of node to be
more consistent with the rest of the manual.  Fix a cross reference.
List child nodes.
(List of Built-ins): New section and node.
(Defining New Built-ins): Make this a node.  Fix capitalization.
---
 doc/misc/eshell.texi | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 5d3e5c7dbd6..9e5eea6cb61 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -416,7 +416,7 @@ Arguments
 @end table
 
 @node Built-ins
-@section Built-in commands
+@section Built-in Commands
 Eshell provides a number of built-in commands, many of them
 implementing common command-line utilities, but enhanced for Eshell.
 (These built-in commands are just ordinary Lisp functions whose names
@@ -477,7 +477,16 @@ Built-ins
 @command{ln} is the current directory.
 
 A few commands are wrappers for more niche Emacs features, and can be
-loaded as part of the eshell-xtra module.  @xref{Extension modules}.
+loaded as part of the @code{eshell-xtra} module.  @xref{Extra built-in
+commands}.
+
+@menu
+* List of Built-ins::
+* Defining New Built-ins::
+@end menu
+
+@node List of Built-ins
+@subsection List of Built-in Commands
 
 @table @code
 
@@ -1195,7 +1204,8 @@ Built-ins
 associated with that connection.
 @end table
 
-@subsection Defining new built-in commands
+@node Defining New Built-ins
+@subsection Defining New Built-in Commands
 While Eshell can run Lisp functions directly as commands, it may be
 more convenient to provide a special built-in command for
 Eshell.  Built-in commands are just ordinary Lisp functions designed
-- 
2.25.1