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

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

[Jim Porter]

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

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.

I welcome any suggestions about the division or the name of the 
subsections. For example, I split them into "Commands for Directories" 
and "Commands for Files", but an alternate scheme could be "Commands for 
Files and Directories" and "Commands for Changing the Current Directory".

Here's how I split the commands up in the patch, so you don't have to 
read through a huge diff:

# Commands for Directories
cd, dirs, du, ls, mkdir, popd, pushd, pwd, rmdir

# Commands for Files
cat, cp, diff, ln, mv, rm

# Commands for Searching
grep, agrep, egrep, fgrep, rgrep, glimpse, info, locate, man, occur

# Commands for Variables
env, export, set, setq, unset

# Commands for Using Other Commands
., addpath, alias, compile, jobs, kill, source, time, wait, which

# Miscellaneous Commands
basename, clear, clear-scrollback, date, dirname, echo, eshell-debug, 
exit, history, listify, make, printnl, umask, whoami

[-- Attachment #2: 0001-Split-Eshell-built-in-commands-documentation-into-su.patch --]
[-- Type: text/plain, Size: 37120 bytes --]

From dff38b933051b9a9a496814093b5984662cc2255 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Tue, 6 Feb 2024 15:53:17 -0800
Subject: [PATCH] Split Eshell built-in commands documentation into subsections

* doc/misc/eshell.texi (Built-ins): Move built-in commands to...
(Commands for Directories, Commands for Files, Commands for Searching)
(Commands for Variables, Commands for Using Other Commands)
(Miscellaneous Commands): ... these.
---
 doc/misc/eshell.texi | 925 ++++++++++++++++++++++---------------------
 1 file changed, 484 insertions(+), 441 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 5d3e5c7dbd6..c3d9eeae503 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -479,45 +479,19 @@ Built-ins
 A few commands are wrappers for more niche Emacs features, and can be
 loaded as part of the eshell-xtra module.  @xref{Extension modules}.
 
-@table @code
-
-@item . @var{file} [@var{argument}]@dots{}
-@cmindex .
-Source an Eshell script named @var{file} in the current environment,
-passing any @var{arguments} to the script (@pxref{Scripts}).  This is
-not to be confused with the command @command{source}, which sources a
-file in a subshell environment.
-
-@item addpath
-@itemx addpath [-b] @var{directory}@dots{}
-@cmindex addpath
-Adds each specified @var{directory} to the @code{$PATH} environment
-variable.  By default, this adds the directories to the end of
-@code{$PATH}, in the order they were passed on the command line; by
-passing @code{-b} or @code{--begin}, Eshell will instead add the
-directories to the beginning.
-
-With no directories, print the list of directories currently stored in
-@code{$PATH}.
-
-@item alias
-@itemx alias @var{name} [@var{command}]
-@cmindex alias
-Define an alias named @var{name} and expanding to @var{command},
-adding it to the aliases file (@pxref{Aliases}).  If @var{command} is
-omitted, delete the alias named @var{name}.  With no arguments at all,
-list all the currently-defined aliases.
-
-@item basename @var{filename}
-@cmindex basename
-Return @var{filename} without its directory.
+@menu
+* Commands for Directories::
+* Commands for Files::
+* Commands for Searching::
+* Commands for Variables::
+* Commands for Using Other Commands::
+* Miscellaneous Commands::
+* Defining New Built-in Commands::
+@end menu
 
-@item cat @var{file}@dots{}
-@cmindex cat
-Concatenate the contents of @var{file}s to standard output.  If in a
-pipeline, or if any of the files is not a regular file, directory, or
-symlink, then this command reverts to the system's definition of
-@command{cat}.
+@node Commands for Directories
+@subsection Commands for Directories
+@table @code
 
 @item cd
 @itemx cd @var{directory}
@@ -558,104 +532,6 @@ Built-ins
 @code{eshell-list-files-after-cd} is non-@code{nil}, then @command{ls}
 is called with any remaining arguments after changing directories.
 
-@item clear [@var{scrollback}]
-@cmindex clear
-Scrolls the contents of the Eshell window out of sight, leaving a
-blank window.  If @var{scrollback} is non-@code{nil}, the scrollback
-contents are cleared instead, as with @command{clear-scrollback}.
-
-@item clear-scrollback
-@cmindex clear-scrollback
-Clear the scrollback contents of the Eshell window.  Unlike the
-command @command{clear}, this command deletes content in the Eshell
-buffer.
-
-@item compile [-p | -i] [-m @var{mode-name}] @var{command}@dots{}
-@cmindex compile
-Run an external command, sending its output to a compilation buffer if
-the command would output to the screen and is not part of a pipeline
-or subcommand.
-
-With the @code{-p} or @code{--plain} options, always send the output
-to the Eshell buffer; similarly, with @code{-i} or
-@code{--interactive}, always send the output to a compilation buffer.
-You can also set the mode of the compilation buffer with @code{-m
-@var{mode-name}} or @code{--mode @var{mode-name}}.
-
-@command{compile} is particularly useful when defining aliases, so
-that interactively, the output shows up in a compilation buffer, but
-you can still pipe the output elsewhere if desired.  For example, if
-you have a grep-like command on your system, you might define an alias
-for it like so: @samp{alias mygrep 'compile --mode=grep-mode -- mygrep
-$*'}.
-
-@item cp [@var{option}@dots{}] @var{source} @var{dest}
-@item cp [@var{option}@dots{}] @var{source}@dots{} @var{directory}
-@cmindex cp
-Copy the file @var{source} to @var{dest} or @var{source} into
-@var{directory}.
-
-@vindex eshell-cp-overwrite-files
-@vindex eshell-cp-interactive-query
-If @code{eshell-cp-overwrite-files} is non-@code{nil}, then
-@command{cp} will overwrite files without warning.  If
-@code{eshell-cp-interactive-query} is non-@code{nil}, then
-@command{cp} will ask before overwriting anything.
-
-@command{cp} accepts the following options:
-
-@table @asis
-
-@item @code{-a}, @code{--archive}
-Equivalent to @code{--no-dereference --preserve --recursive}.
-
-@item @code{-d}, @code{--no-dereference}
-Don't dereference symbolic links when copying; instead, copy the link
-itself.
-
-@item @code{-f}, @code{--force}
-Never prompt for confirmation before copying a file.
-
-@item @code{-i}, @code{--interactive}
-Prompt for confirmation before copying a file if the target already
-exists.
-
-@item @code{-n}, @code{--preview}
-Run the command, but don't copy anything.  This is useful if you
-want to preview what would be removed when calling @command{cp}.
-
-@item @code{-p}, @code{--preserve}
-Attempt to preserve file attributes when copying.
-
-@item @code{-r}, @code{-R}, @code{--recursive}
-Copy any specified directories and their contents recursively.
-
-@item @code{-v}, @code{--verbose}
-Print the name of each file before copying it.
-
-@end table
-
-@item date [@var{specified-time} [@var{zone}]]
-@cmindex date
-Print the current local time as a human-readable string.  This command
-is an alias to the Emacs Lisp function @code{current-time-string}
-(@pxref{Time of Day,,, elisp, GNU Emacs Lisp Reference Manual}).
-
-@item diff [@var{option}]@dots{} @var{old} @var{new}
-@cmindex diff
-Compare the files @var{old} and @var{new} using Emacs's internal
-@code{diff} (not to be confused with @code{ediff}).  @xref{Comparing
-Files, , , emacs, The GNU Emacs Manual}.
-
-@vindex eshell-plain-diff-behavior
-If @code{eshell-plain-diff-behavior} is non-@code{nil}, then this
-command does not use Emacs's internal @code{diff}.  This is the same
-as using @samp{alias diff '*diff $@@*'}.
-
-@item dirname @var{filename}
-@cmindex dirname
-Return the directory component of @var{filename}.
-
 @item dirs
 @cmindex dirs
 Prints the directory stack.  Directories can be added or removed from
@@ -711,235 +587,58 @@ Built-ins
 
 @end table
 
-@item echo [-n | -N] [@var{arg}]@dots{}
-@cmindex echo
-Prints the value of each @var{arg}.  By default, this prints in a
-Lisp-friendly fashion (so that the value is useful to a Lisp command
-using the result of @command{echo} as an argument).  If a single
-argument is passed, @command{echo} prints that; if multiple arguments
-are passed, it prints a list of all the arguments; otherwise, it
-prints the empty string.
-
-@vindex eshell-plain-echo-behavior
-If @code{eshell-plain-echo-behavior} is non-@code{nil}, @command{echo}
-will try to behave more like a plain shell's @command{echo}, printing
-each argument as a string, separated by a space.
-
-You can control whether @command{echo} outputs a trailing newline
-using @code{-n} to disable the trailing newline (the default behavior)
-or @code{-N} to enable it (the default when
-@code{eshell-plain-echo-behavior} is non-@code{nil}).
+@item ls [@var{option}]@dots{} [@var{file}]@dots{}
+@cmindex ls
+List information about each @var{file}, including the contents of any
+specified directories.  If @var{file} is unspecified, list the
+contents of the current directory.
 
-@item env [@var{var}=@var{value}]@dots{} [@var{command}]@dots{}
-@cmindex env
-With no arguments, print the current environment variables.  If you
-pass arguments to this command, then @command{env} will execute the
-arguments as a command.  If you pass any initial arguments of the form
-@samp{@var{var}=@var{value}}, @command{env} will first set @var{var}
-to @var{value} before running the command.
+@vindex eshell-ls-initial-args
+The user option @code{eshell-ls-initial-args} contains a list of
+arguments to include with any call to @command{ls}.  For example, you
+can include the option @option{-h} to always use a more human-readable
+format.
 
-@item eshell-debug [error | form | process]@dots{}
-@cmindex eshell-debug
-Toggle debugging information for Eshell itself.  You can pass this
-command one or more of the following arguments:
+@vindex eshell-ls-use-colors
+If @code{eshell-ls-use-colors} is non-@code{nil}, the contents of a
+directory is color-coded according to file type and status.  These
+colors and the regexps used to identify their corresponding files can
+be customized via @w{@kbd{M-x customize-group @key{RET} eshell-ls
+@key{RET}}}.
 
-@itemize @bullet
+@command{ls} supports the following options:
 
-@item
-@code{error}, to enable/disable Eshell trapping errors when
-evaluating commands;
+@table @asis
 
-@item
-@code{form}, to show/hide Eshell command form manipulation in the
-buffer @code{*eshell last cmd*}; or
+@item @code{-a}, @code{--all}
+List all files, including ones starting with @samp{.}.
 
-@item
-@code{process}, to show/hide external process events in the buffer
-@code{*eshell last cmd*}.
+@item @code{-A}, @code{--almost-all}
+Like @code{--all}, but don't list the current directory (@file{.}) or
+the parent directory (@file{..}).
 
-@end itemize
+@item @code{-c}, @code{--by-ctime}
+Sort files by last status change time, with newest files first.
 
-@item exit
-@cmindex exit
-@vindex eshell-kill-on-exit
-Exit Eshell and save the history.  By default, this command kills the
-Eshell buffer, but if @code{eshell-kill-on-exit} is @code{nil}, then
-the buffer is merely buried instead.
+@item @code{-C}
+List entries by columns.
 
-@item export [@var{name}=@var{value}]@dots{}
-@cmindex export
-Set environment variables using input like Bash's @command{export}, as
-in @samp{export @var{var1}=@var{val1} @var{var2}=@var{val2} @dots{}}.
+@item @code{-d}, @code{--directory}
+List directory entries instead of their contents.
 
-@item grep [@var{arg}]@dots{}
-@cmindex grep
-@itemx agrep [@var{arg}]@dots{}
-@cmindex agrep
-@itemx egrep [@var{arg}]@dots{}
-@cmindex egrep
-@itemx fgrep [@var{arg}]@dots{}
-@cmindex fgrep
-@itemx rgrep [@var{arg}]@dots{}
-@cmindex rgrep
-@itemx glimpse [@var{arg}]@dots{}
-@cmindex glimpse
-The @command{grep} commands are compatible with GNU @command{grep},
-but open a compilation buffer in @code{grep-mode} instead.
-@xref{Grep Searching, , , emacs, The GNU Emacs Manual}.
+@item @code{-h}, @code{--human-readable}
+Print sizes in human-readable format, with binary prefixes (so 1 KB is
+1024 bytes).
 
-@vindex eshell-plain-grep-behavior
-If @code{eshell-plain-grep-behavior} is non-@code{nil}, then these
-commands do not use open a compilation buffer, instead printing output
-to Eshell's buffer.  This is the same as using @samp{alias grep '*grep
-$@@*'}, though this setting applies to all of the built-in commands
-for which you would need to create a separate alias.
+@item @code{-H}, @code{--si}
+Print sizes in human-readable format, with decimal prefixes (so 1 KB
+is 1000 bytes).
 
-@item history [@var{n}]
-@itemx history [-arw] [@var{filename}]
-@cmindex history
-Prints Eshell's input history.  With a numeric argument @var{n}, this
-command prints the @var{n} most recent items in the history.
-Alternately, you can specify the following options:
+@item @code{-I@var{pattern}}, @code{--ignore=@var{pattern}}
+Don't list directory entries matching @var{pattern}.
 
-@table @asis
-
-@item @code{-a}, @code{--append}
-Append new history items to the history file.
-
-@item @code{-r}, @code{--read}
-Read history items from the history file and append them to the
-current shell's history.
-
-@item @code{-w}, @code{--write}
-Write the current history list to the history file.
-
-@end table
-
-@item info [@var{manual} [@var{item}]@dots{}]
-@cmindex info
-Browse the available Info documentation.  With no arguments, browse
-the top-level menu.  Otherwise, show the manual for @var{manual},
-selecting the menu entry for @var{item}.
-
-This command is the same as the external @command{info} command, but
-uses Emacs's internal Info reader.  @xref{Misc Help, , , emacs, The
-GNU Emacs Manual}.
-
-@item jobs
-@cmindex jobs
-List subprocesses of the Emacs process, if any, using the function
-@code{list-processes}.
-
-@item kill [-@var{signal}] [@var{pid} | @var{process}]
-@cmindex kill
-Kill processes.  Takes a PID or a process object and an optional
-@var{signal} specifier which can either be a number or a signal name.
-
-@item listify [@var{arg}]@dots{}
-@cmindex listify
-Return the arguments as a single list.  With a single argument, return
-it as-is if it's already a list, or otherwise wrap it in a list.  With
-multiple arguments, return a list of all of them.
-
-@item ln [@var{option}]@dots{} @var{target} [@var{link-name}]
-@itemx ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
-@cmindex ln
-Create a link to the specified @var{target} named @var{link-name} or
-create links to multiple @var{targets} in @var{directory}.
-
-@vindex eshell-ln-overwrite-files
-@vindex eshell-ln-interactive-query
-If @code{eshell-ln-overwrite-files} is non-@code{nil}, @command{ln}
-will overwrite files without warning.  If
-@code{eshell-ln-interactive-query} is non-@code{nil}, then
-@command{ln} will ask before overwriting files.
-
-@command{ln} accepts the following options:
-
-@table @asis
-
-@item @code{-f}, @code{--force}
-Never prompt for confirmation before linking a target.
-
-@item @code{-i}, @code{--interactive}
-Prompt for confirmation before linking to an item if the source
-already exists.
-
-@item @code{-n}, @code{--preview}
-Run the command, but don't move anything.  This is useful if you
-want to preview what would be linked when calling @command{ln}.
-
-@item @code{-s}, @code{--symbolic}
-Make symbolic links instead of hard links.
-
-@item @code{-v}, @code{--verbose}
-Print the name of each file before linking it.
-
-@end table
-
-@item locate @var{arg}@dots{}
-@cmindex locate
-Alias to Emacs's @code{locate} function, which simply runs the external
-@command{locate} command and parses the results.
-@xref{Dired and Find, , , emacs, The GNU Emacs Manual}.
-
-@vindex eshell-plain-locate-behavior
-If @code{eshell-plain-locate-behavior} is non-@code{nil}, then Emacs's
-internal @code{locate} is not used.  This is the same as using
-@samp{alias locate '*locate $@@*'}.
-
-@item ls [@var{option}]@dots{} [@var{file}]@dots{}
-@cmindex ls
-List information about each @var{file}, including the contents of any
-specified directories.  If @var{file} is unspecified, list the
-contents of the current directory.
-
-@vindex eshell-ls-initial-args
-The user option @code{eshell-ls-initial-args} contains a list of
-arguments to include with any call to @command{ls}.  For example, you
-can include the option @option{-h} to always use a more human-readable
-format.
-
-@vindex eshell-ls-use-colors
-If @code{eshell-ls-use-colors} is non-@code{nil}, the contents of a
-directory is color-coded according to file type and status.  These
-colors and the regexps used to identify their corresponding files can
-be customized via @w{@kbd{M-x customize-group @key{RET} eshell-ls
-@key{RET}}}.
-
-@command{ls} supports the following options:
-
-@table @asis
-
-@item @code{-a}, @code{--all}
-List all files, including ones starting with @samp{.}.
-
-@item @code{-A}, @code{--almost-all}
-Like @code{--all}, but don't list the current directory (@file{.}) or
-the parent directory (@file{..}).
-
-@item @code{-c}, @code{--by-ctime}
-Sort files by last status change time, with newest files first.
-
-@item @code{-C}
-List entries by columns.
-
-@item @code{-d}, @code{--directory}
-List directory entries instead of their contents.
-
-@item @code{-h}, @code{--human-readable}
-Print sizes in human-readable format, with binary prefixes (so 1 KB is
-1024 bytes).
-
-@item @code{-H}, @code{--si}
-Print sizes in human-readable format, with decimal prefixes (so 1 KB
-is 1000 bytes).
-
-@item @code{-I@var{pattern}}, @code{--ignore=@var{pattern}}
-Don't list directory entries matching @var{pattern}.
-
-@item @code{-k}, @code{--kilobytes}
-Print sizes as 1024-byte kilobytes.
+@item @code{-k}, @code{--kilobytes}
+Print sizes as 1024-byte kilobytes.
 
 @vindex eshell-ls-date-format
 @item @code{-l}
@@ -990,60 +689,11 @@ Built-ins
 
 @end table
 
-@item make [@var{arg}]@dots{}
-@cmindex make
-Run @command{make} through @code{compile} when run asynchronously
-(e.g., @samp{make &}).  @xref{Compilation, , , emacs, The GNU Emacs
-Manual}.  Otherwise call the external @command{make} command.
-
-@item man [@var{arg}]@dots{}
-@cmindex man
-Display Man pages using the Emacs @code{man} command.
-@xref{Man Page, , , emacs, The GNU Emacs Manual}.
-
 @item mkdir [-p] @var{directory}@dots{}
 @cmindex mkdir
 Make new directories.  With @code{-p} or @code{--parents},
 automatically make any necessary parent directories as well.
 
-@item mv [@var{option}]@dots{} @var{source} @var{dest}
-@itemx mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
-@cmindex mv
-Rename the file @var{source} to @var{dest} or move @var{source} into
-@var{directory}.
-
-@vindex eshell-mv-overwrite-files
-@vindex eshell-mv-interactive-query
-If @code{eshell-mv-overwrite-files} is non-@code{nil}, @command{mv}
-will overwrite files without warning.  If
-@code{eshell-mv-interactive-query} is non-@code{nil}, @command{mv}
-will prompt before overwriting anything.
-
-@command{mv} accepts the following options:
-
-@table @asis
-
-@item @code{-f}, @code{--force}
-Never prompt for confirmation before moving an item.
-
-@item @code{-i}, @code{--interactive}
-Prompt for confirmation before moving an item if the target already
-exists.
-
-@item @code{-n}, @code{--preview}
-Run the command, but don't move anything.  This is useful if you
-want to preview what would be moved when calling @command{mv}.
-
-@item @code{-v}, @code{--verbose}
-Print the name of each item before moving it.
-
-@end table
-
-@item occur @var{regexp} [@var{nlines}]
-@cmindex occur
-Alias to Emacs's @code{occur}.
-@xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
-
 @item popd
 @item popd +@var{n}
 @cmindex popd
@@ -1062,10 +712,6 @@ Built-ins
 
 @end table
 
-@item printnl [@var{arg}]@dots{}
-@cmindex printnl
-Print all the @var{arg}s separated by newlines.
-
 @item pushd
 @itemx pushd @var{directory}
 @itemx pushd +@var{n}
@@ -1102,44 +748,262 @@ Built-ins
 @cmindex pwd
 Prints the current working directory.
 
-@item rm [@var{option}]@dots{} @var{item}@dots{}
-@cmindex rm
-Removes files, buffers, processes, or Emacs Lisp symbols, depending on
-the type of each @var{item}.
+@item rmdir @var{directory}@dots{}
+@cmindex rmdir
+Removes directories if they are empty.
 
-@vindex eshell-rm-interactive-query
-@vindex eshell-rm-removes-directories
-If @code{eshell-rm-interactive-query} is non-@code{nil}, @command{rm}
-will prompt before removing anything.  If
-@code{eshell-rm-removes-directories} is non-@code{nil}, then
-@command{rm} can also remove directories.  Otherwise, @command{rmdir}
-is required.
+@end table
 
-@command{rm} accepts the following options:
+@node Commands for Files
+@subsection Commands for Files
+@table @code
+
+@item cat @var{file}@dots{}
+@cmindex cat
+Concatenate the contents of @var{file}s to standard output.  If in a
+pipeline, or if any of the files is not a regular file, directory, or
+symlink, then this command reverts to the system's definition of
+@command{cat}.
+
+@item cp [@var{option}@dots{}] @var{source} @var{dest}
+@item cp [@var{option}@dots{}] @var{source}@dots{} @var{directory}
+@cmindex cp
+Copy the file @var{source} to @var{dest} or @var{source} into
+@var{directory}.
+
+@vindex eshell-cp-overwrite-files
+@vindex eshell-cp-interactive-query
+If @code{eshell-cp-overwrite-files} is non-@code{nil}, then
+@command{cp} will overwrite files without warning.  If
+@code{eshell-cp-interactive-query} is non-@code{nil}, then
+@command{cp} will ask before overwriting anything.
+
+@command{cp} accepts the following options:
 
 @table @asis
 
+@item @code{-a}, @code{--archive}
+Equivalent to @code{--no-dereference --preserve --recursive}.
+
+@item @code{-d}, @code{--no-dereference}
+Don't dereference symbolic links when copying; instead, copy the link
+itself.
+
 @item @code{-f}, @code{--force}
-Never prompt for confirmation before removing an item.
+Never prompt for confirmation before copying a file.
 
 @item @code{-i}, @code{--interactive}
-Prompt for confirmation before removing each item.
+Prompt for confirmation before copying a file if the target already
+exists.
 
 @item @code{-n}, @code{--preview}
-Run the command, but don't remove anything.  This is useful if you
-want to preview what would be removed when calling @command{rm}.
+Run the command, but don't copy anything.  This is useful if you
+want to preview what would be removed when calling @command{cp}.
+
+@item @code{-p}, @code{--preserve}
+Attempt to preserve file attributes when copying.
 
 @item @code{-r}, @code{-R}, @code{--recursive}
-Remove any specified directories and their contents recursively.
+Copy any specified directories and their contents recursively.
 
 @item @code{-v}, @code{--verbose}
-Print the name of each item before removing it.
+Print the name of each file before copying it.
 
 @end table
 
-@item rmdir @var{directory}@dots{}
-@cmindex rmdir
-Removes directories if they are empty.
+@item diff [@var{option}]@dots{} @var{old} @var{new}
+@cmindex diff
+Compare the files @var{old} and @var{new} using Emacs's internal
+@code{diff} (not to be confused with @code{ediff}).  @xref{Comparing
+Files, , , emacs, The GNU Emacs Manual}.
+
+@vindex eshell-plain-diff-behavior
+If @code{eshell-plain-diff-behavior} is non-@code{nil}, then this
+command does not use Emacs's internal @code{diff}.  This is the same
+as using @samp{alias diff '*diff $@@*'}.
+
+@item ln [@var{option}]@dots{} @var{target} [@var{link-name}]
+@itemx ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
+@cmindex ln
+Create a link to the specified @var{target} named @var{link-name} or
+create links to multiple @var{targets} in @var{directory}.
+
+@vindex eshell-ln-overwrite-files
+@vindex eshell-ln-interactive-query
+If @code{eshell-ln-overwrite-files} is non-@code{nil}, @command{ln}
+will overwrite files without warning.  If
+@code{eshell-ln-interactive-query} is non-@code{nil}, then
+@command{ln} will ask before overwriting files.
+
+@command{ln} accepts the following options:
+
+@table @asis
+
+@item @code{-f}, @code{--force}
+Never prompt for confirmation before linking a target.
+
+@item @code{-i}, @code{--interactive}
+Prompt for confirmation before linking to an item if the source
+already exists.
+
+@item @code{-n}, @code{--preview}
+Run the command, but don't move anything.  This is useful if you
+want to preview what would be linked when calling @command{ln}.
+
+@item @code{-s}, @code{--symbolic}
+Make symbolic links instead of hard links.
+
+@item @code{-v}, @code{--verbose}
+Print the name of each file before linking it.
+
+@end table
+
+@item mv [@var{option}]@dots{} @var{source} @var{dest}
+@itemx mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
+@cmindex mv
+Rename the file @var{source} to @var{dest} or move @var{source} into
+@var{directory}.
+
+@vindex eshell-mv-overwrite-files
+@vindex eshell-mv-interactive-query
+If @code{eshell-mv-overwrite-files} is non-@code{nil}, @command{mv}
+will overwrite files without warning.  If
+@code{eshell-mv-interactive-query} is non-@code{nil}, @command{mv}
+will prompt before overwriting anything.
+
+@command{mv} accepts the following options:
+
+@table @asis
+
+@item @code{-f}, @code{--force}
+Never prompt for confirmation before moving an item.
+
+@item @code{-i}, @code{--interactive}
+Prompt for confirmation before moving an item if the target already
+exists.
+
+@item @code{-n}, @code{--preview}
+Run the command, but don't move anything.  This is useful if you
+want to preview what would be moved when calling @command{mv}.
+
+@item @code{-v}, @code{--verbose}
+Print the name of each item before moving it.
+
+@end table
+
+@item rm [@var{option}]@dots{} @var{item}@dots{}
+@cmindex rm
+Removes files, buffers, processes, or Emacs Lisp symbols, depending on
+the type of each @var{item}.
+
+@vindex eshell-rm-interactive-query
+@vindex eshell-rm-removes-directories
+If @code{eshell-rm-interactive-query} is non-@code{nil}, @command{rm}
+will prompt before removing anything.  If
+@code{eshell-rm-removes-directories} is non-@code{nil}, then
+@command{rm} can also remove directories.  Otherwise, @command{rmdir}
+is required.
+
+@command{rm} accepts the following options:
+
+@table @asis
+
+@item @code{-f}, @code{--force}
+Never prompt for confirmation before removing an item.
+
+@item @code{-i}, @code{--interactive}
+Prompt for confirmation before removing each item.
+
+@item @code{-n}, @code{--preview}
+Run the command, but don't remove anything.  This is useful if you
+want to preview what would be removed when calling @command{rm}.
+
+@item @code{-r}, @code{-R}, @code{--recursive}
+Remove any specified directories and their contents recursively.
+
+@item @code{-v}, @code{--verbose}
+Print the name of each item before removing it.
+
+@end table
+
+@end table
+
+@node Commands for Searching
+@subsection Commands for Searching
+@table @code
+
+@item grep [@var{arg}]@dots{}
+@cmindex grep
+@itemx agrep [@var{arg}]@dots{}
+@cmindex agrep
+@itemx egrep [@var{arg}]@dots{}
+@cmindex egrep
+@itemx fgrep [@var{arg}]@dots{}
+@cmindex fgrep
+@itemx rgrep [@var{arg}]@dots{}
+@cmindex rgrep
+@itemx glimpse [@var{arg}]@dots{}
+@cmindex glimpse
+The @command{grep} commands are compatible with GNU @command{grep},
+but open a compilation buffer in @code{grep-mode} instead.
+@xref{Grep Searching, , , emacs, The GNU Emacs Manual}.
+
+@vindex eshell-plain-grep-behavior
+If @code{eshell-plain-grep-behavior} is non-@code{nil}, then these
+commands do not use open a compilation buffer, instead printing output
+to Eshell's buffer.  This is the same as using @samp{alias grep '*grep
+$@@*'}, though this setting applies to all of the built-in commands
+for which you would need to create a separate alias.
+
+@item info [@var{manual} [@var{item}]@dots{}]
+@cmindex info
+Browse the available Info documentation.  With no arguments, browse
+the top-level menu.  Otherwise, show the manual for @var{manual},
+selecting the menu entry for @var{item}.
+
+This command is the same as the external @command{info} command, but
+uses Emacs's internal Info reader.  @xref{Misc Help, , , emacs, The
+GNU Emacs Manual}.
+
+@item locate @var{arg}@dots{}
+@cmindex locate
+Alias to Emacs's @code{locate} function, which simply runs the external
+@command{locate} command and parses the results.
+@xref{Dired and Find, , , emacs, The GNU Emacs Manual}.
+
+@vindex eshell-plain-locate-behavior
+If @code{eshell-plain-locate-behavior} is non-@code{nil}, then Emacs's
+internal @code{locate} is not used.  This is the same as using
+@samp{alias locate '*locate $@@*'}.
+
+@item man [@var{arg}]@dots{}
+@cmindex man
+Display Man pages using the Emacs @code{man} command.
+@xref{Man Page, , , emacs, The GNU Emacs Manual}.
+
+@item occur @var{regexp} [@var{nlines}]
+@cmindex occur
+Alias to Emacs's @code{occur}.
+@xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
+
+@end table
+
+@node Commands for Variables
+@subsection Commands for Variables
+@table @code
+
+@item env [@var{var}=@var{value}]@dots{} [@var{command}]@dots{}
+@cmindex env
+With no arguments, print the current environment variables.  If you
+pass arguments to this command, then @command{env} will execute the
+arguments as a command.  If you pass any initial arguments of the form
+@samp{@var{var}=@var{value}}, @command{env} will first set @var{var}
+to @var{value} before running the command.
+
+@item export [@var{name}=@var{value}]@dots{}
+@cmindex export
+Set environment variables using input like Bash's @command{export}, as
+in @samp{export @var{var1}=@var{val1} @var{var2}=@var{val2} @dots{}}.
 
 @item set [@var{var} @var{value}]@dots{}
 @cmindex set
@@ -1154,6 +1018,74 @@ Built-ins
 Set variable values, using the function @code{setq} like a command
 (@pxref{Setting Variables,,, elisp, GNU Emacs Lisp Reference Manual}).
 
+@item unset [@var{var}]@dots{}
+@cmindex unset
+Unset one or more variables.  As with @command{set}, the value of
+@var{var} can be a symbol, in which case it refers to a Lisp variable,
+or a string, referring to an environment variable.
+
+@end table
+
+@node Commands for Using Other Commands
+@subsection Commands for Using Other Commands
+@table @code
+
+@item . @var{file} [@var{argument}]@dots{}
+@cmindex .
+Source an Eshell script named @var{file} in the current environment,
+passing any @var{arguments} to the script (@pxref{Scripts}).  This is
+not to be confused with the command @command{source}, which sources a
+file in a subshell environment.
+
+@item addpath
+@itemx addpath [-b] @var{directory}@dots{}
+@cmindex addpath
+Adds each specified @var{directory} to the @code{$PATH} environment
+variable.  By default, this adds the directories to the end of
+@code{$PATH}, in the order they were passed on the command line; by
+passing @code{-b} or @code{--begin}, Eshell will instead add the
+directories to the beginning.
+
+With no directories, print the list of directories currently stored in
+@code{$PATH}.
+
+@item alias
+@itemx alias @var{name} [@var{command}]
+@cmindex alias
+Define an alias named @var{name} and expanding to @var{command},
+adding it to the aliases file (@pxref{Aliases}).  If @var{command} is
+omitted, delete the alias named @var{name}.  With no arguments at all,
+list all the currently-defined aliases.
+
+@item compile [-p | -i] [-m @var{mode-name}] @var{command}@dots{}
+@cmindex compile
+Run an external command, sending its output to a compilation buffer if
+the command would output to the screen and is not part of a pipeline
+or subcommand.
+
+With the @code{-p} or @code{--plain} options, always send the output
+to the Eshell buffer; similarly, with @code{-i} or
+@code{--interactive}, always send the output to a compilation buffer.
+You can also set the mode of the compilation buffer with @code{-m
+@var{mode-name}} or @code{--mode @var{mode-name}}.
+
+@command{compile} is particularly useful when defining aliases, so
+that interactively, the output shows up in a compilation buffer, but
+you can still pipe the output elsewhere if desired.  For example, if
+you have a grep-like command on your system, you might define an alias
+for it like so: @samp{alias mygrep 'compile --mode=grep-mode -- mygrep
+$*'}.
+
+@item jobs
+@cmindex jobs
+List subprocesses of the Emacs process, if any, using the function
+@code{list-processes}.
+
+@item kill [-@var{signal}] [@var{pid} | @var{process}]
+@cmindex kill
+Kill processes.  Takes a PID or a process object and an optional
+@var{signal} specifier which can either be a number or a signal name.
+
 @item source @var{file} [@var{argument}]@dots{}
 @cmindex source
 Source an Eshell script named @var{file} in a subshell environment,
@@ -1165,20 +1097,6 @@ Built-ins
 @cmindex time
 Show the time elapsed during the execution of @var{command}.
 
-@item umask [-S]
-@itemx umask @var{mode}
-@cmindex umask
-View the default file permissions for newly created files and
-directories.  If you pass @code{-S} or @code{--symbolic}, view the
-mode symbolically.  With @var{mode}, set the default permissions to
-this value.
-
-@item unset [@var{var}]@dots{}
-@cmindex unset
-Unset one or more variables.  As with @command{set}, the value of
-@var{var} can be a symbol, in which case it refers to a Lisp variable,
-or a string, referring to an environment variable.
-
 @item wait [@var{process}]@dots{}
 @cmindex wait
 Wait until each specified @var{process} has exited.
@@ -1188,6 +1106,130 @@ Built-ins
 For each @var{command}, identify what kind of command it is and its
 location.
 
+@end table
+
+@node Miscellaneous Commands
+@subsection Miscellaneous Commands
+@table @code
+
+@item basename @var{filename}
+@cmindex basename
+Return @var{filename} without its directory.
+
+@item clear [@var{scrollback}]
+@cmindex clear
+Scrolls the contents of the Eshell window out of sight, leaving a
+blank window.  If @var{scrollback} is non-@code{nil}, the scrollback
+contents are cleared instead, as with @command{clear-scrollback}.
+
+@item clear-scrollback
+@cmindex clear-scrollback
+Clear the scrollback contents of the Eshell window.  Unlike the
+command @command{clear}, this command deletes content in the Eshell
+buffer.
+
+@item date [@var{specified-time} [@var{zone}]]
+@cmindex date
+Print the current local time as a human-readable string.  This command
+is an alias to the Emacs Lisp function @code{current-time-string}
+(@pxref{Time of Day,,, elisp, GNU Emacs Lisp Reference Manual}).
+
+@item dirname @var{filename}
+@cmindex dirname
+Return the directory component of @var{filename}.
+
+@item echo [-n | -N] [@var{arg}]@dots{}
+@cmindex echo
+Prints the value of each @var{arg}.  By default, this prints in a
+Lisp-friendly fashion (so that the value is useful to a Lisp command
+using the result of @command{echo} as an argument).  If a single
+argument is passed, @command{echo} prints that; if multiple arguments
+are passed, it prints a list of all the arguments; otherwise, it
+prints the empty string.
+
+@vindex eshell-plain-echo-behavior
+If @code{eshell-plain-echo-behavior} is non-@code{nil}, @command{echo}
+will try to behave more like a plain shell's @command{echo}, printing
+each argument as a string, separated by a space.
+
+You can control whether @command{echo} outputs a trailing newline
+using @code{-n} to disable the trailing newline (the default behavior)
+or @code{-N} to enable it (the default when
+@code{eshell-plain-echo-behavior} is non-@code{nil}).
+
+@item eshell-debug [error | form | process]@dots{}
+@cmindex eshell-debug
+Toggle debugging information for Eshell itself.  You can pass this
+command one or more of the following arguments:
+
+@itemize @bullet
+
+@item
+@code{error}, to enable/disable Eshell trapping errors when
+evaluating commands;
+
+@item
+@code{form}, to show/hide Eshell command form manipulation in the
+buffer @code{*eshell last cmd*}; or
+
+@item
+@code{process}, to show/hide external process events in the buffer
+@code{*eshell last cmd*}.
+
+@end itemize
+
+@item exit
+@cmindex exit
+@vindex eshell-kill-on-exit
+Exit Eshell and save the history.  By default, this command kills the
+Eshell buffer, but if @code{eshell-kill-on-exit} is @code{nil}, then
+the buffer is merely buried instead.
+
+@item history [@var{n}]
+@itemx history [-arw] [@var{filename}]
+@cmindex history
+Prints Eshell's input history.  With a numeric argument @var{n}, this
+command prints the @var{n} most recent items in the history.
+Alternately, you can specify the following options:
+
+@table @asis
+
+@item @code{-a}, @code{--append}
+Append new history items to the history file.
+
+@item @code{-r}, @code{--read}
+Read history items from the history file and append them to the
+current shell's history.
+
+@item @code{-w}, @code{--write}
+Write the current history list to the history file.
+
+@end table
+
+@item listify [@var{arg}]@dots{}
+@cmindex listify
+Return the arguments as a single list.  With a single argument, return
+it as-is if it's already a list, or otherwise wrap it in a list.  With
+multiple arguments, return a list of all of them.
+
+@item make [@var{arg}]@dots{}
+@cmindex make
+Run @command{make} through @code{compile} when run asynchronously
+(e.g., @samp{make &}).  @xref{Compilation, , , emacs, The GNU Emacs
+Manual}.  Otherwise call the external @command{make} command.
+
+@item printnl [@var{arg}]@dots{}
+@cmindex printnl
+Print all the @var{arg}s separated by newlines.
+
+@item umask [-S]
+@itemx umask @var{mode}
+@cmindex umask
+View the default file permissions for newly created files and
+directories.  If you pass @code{-S} or @code{--symbolic}, view the
+mode symbolically.  With @var{mode}, set the default permissions to
+this value.
+
 @item whoami
 @cmindex whoami
 Print the current user.  This Eshell version of @command{whoami} is
@@ -1195,7 +1237,8 @@ Built-ins
 associated with that connection.
 @end table
 
-@subsection Defining new built-in commands
+@node Defining New Built-in Commands
+@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

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

[Eli Zaretskii]

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

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

[Jim Porter]

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?" Since 
those were previously interspersed throughout the full command list, it 
would take a fair bit of skimming past irrelevant commands to find the 
directory-related ones.

For looking up a specific command though, I agree that the current 
manual is fine.

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

[Eli Zaretskii]

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

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Tue, 6 Feb 2024 20:26:08 -0800
>> Cc: 68963@debbugs.gnu.org
>> From: Jim Porter <jporterbugs@gmail.com>
>>
>> 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.

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

[Jim Porter]

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

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

[Eli Zaretskii]

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

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

[Jim Porter]

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

On 2/7/2024 11:07 PM, Eli Zaretskii wrote:
> 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.

I think you and Stefan have successfully convinced me that there's no 
need to try and fuss with making arbitrary divisions of the built-in 
commands. It's tricky to split them up just right, and time spent on 
that should go towards adding indexing instead.

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

Attached are some initial improvements to the indexing (patch 0003 in 
the series). It would probably be worth adding concept indices to 
most/all of the built-in commands, but the few I added here are pretty 
straightforward, and I can just poke at this a bit at a time for the 
remainder. (Writing documentation isn't the most viscerally exciting 
thing to do, so I prefer to spread the work out.)

I also added patch 0002, which moves the indexing above the "@item"s. 
That way, when you navigate to the entry from the index, it shows the 
header line listing the supported arguments when viewing the 
documentation as HTML.

[-- Attachment #2: 0001-Put-the-list-of-built-in-Eshell-commands-in-its-own-.patch --]
[-- Type: text/plain, Size: 1928 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 1/3] 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


[-- Attachment #3: 0002-In-Eshell-manual-put-command-index-anchors-above-the.patch --]
[-- Type: text/plain, Size: 18880 bytes --]

From d5a16713b470617b989ed210b4d3ec2abd90fc14 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Thu, 8 Feb 2024 11:31:17 -0800
Subject: [PATCH 2/3] In Eshell manual, put command index anchors above the
 item

This makes sure that when navigating to the command's documentation from
the index, it shows the item heading (which lists the supported
arguments).

* doc/misc/eshell.texi (List of Built-ins, Tramp extensions)
(Extra built-in commands): Adjust placement of '@cmindex'.
---
 doc/misc/eshell.texi | 134 +++++++++++++++++++++----------------------
 1 file changed, 67 insertions(+), 67 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 9e5eea6cb61..3ff8e55ed03 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -490,16 +490,16 @@ List of Built-ins
 
 @table @code
 
-@item . @var{file} [@var{argument}]@dots{}
 @cmindex .
+@item . @var{file} [@var{argument}]@dots{}
 Source an Eshell script named @var{file} in the current environment,
 passing any @var{arguments} to the script (@pxref{Scripts}).  This is
 not to be confused with the command @command{source}, which sources a
 file in a subshell environment.
 
+@cmindex addpath
 @item addpath
 @itemx addpath [-b] @var{directory}@dots{}
-@cmindex addpath
 Adds each specified @var{directory} to the @code{$PATH} environment
 variable.  By default, this adds the directories to the end of
 @code{$PATH}, in the order they were passed on the command line; by
@@ -509,30 +509,30 @@ List of Built-ins
 With no directories, print the list of directories currently stored in
 @code{$PATH}.
 
+@cmindex alias
 @item alias
 @itemx alias @var{name} [@var{command}]
-@cmindex alias
 Define an alias named @var{name} and expanding to @var{command},
 adding it to the aliases file (@pxref{Aliases}).  If @var{command} is
 omitted, delete the alias named @var{name}.  With no arguments at all,
 list all the currently-defined aliases.
 
-@item basename @var{filename}
 @cmindex basename
+@item basename @var{filename}
 Return @var{filename} without its directory.
 
-@item cat @var{file}@dots{}
 @cmindex cat
+@item cat @var{file}@dots{}
 Concatenate the contents of @var{file}s to standard output.  If in a
 pipeline, or if any of the files is not a regular file, directory, or
 symlink, then this command reverts to the system's definition of
 @command{cat}.
 
+@cmindex cd
 @item cd
 @itemx cd @var{directory}
 @itemx cd -[@var{n}]
 @itemx cd =[@var{regexp}]
-@cmindex cd
 Change the current working directory.  This command can take several
 forms:
 
@@ -567,20 +567,20 @@ List of Built-ins
 @code{eshell-list-files-after-cd} is non-@code{nil}, then @command{ls}
 is called with any remaining arguments after changing directories.
 
-@item clear [@var{scrollback}]
 @cmindex clear
+@item clear [@var{scrollback}]
 Scrolls the contents of the Eshell window out of sight, leaving a
 blank window.  If @var{scrollback} is non-@code{nil}, the scrollback
 contents are cleared instead, as with @command{clear-scrollback}.
 
-@item clear-scrollback
 @cmindex clear-scrollback
+@item clear-scrollback
 Clear the scrollback contents of the Eshell window.  Unlike the
 command @command{clear}, this command deletes content in the Eshell
 buffer.
 
-@item compile [-p | -i] [-m @var{mode-name}] @var{command}@dots{}
 @cmindex compile
+@item compile [-p | -i] [-m @var{mode-name}] @var{command}@dots{}
 Run an external command, sending its output to a compilation buffer if
 the command would output to the screen and is not part of a pipeline
 or subcommand.
@@ -598,9 +598,9 @@ List of Built-ins
 for it like so: @samp{alias mygrep 'compile --mode=grep-mode -- mygrep
 $*'}.
 
+@cmindex cp
 @item cp [@var{option}@dots{}] @var{source} @var{dest}
 @item cp [@var{option}@dots{}] @var{source}@dots{} @var{directory}
-@cmindex cp
 Copy the file @var{source} to @var{dest} or @var{source} into
 @var{directory}.
 
@@ -644,14 +644,14 @@ List of Built-ins
 
 @end table
 
-@item date [@var{specified-time} [@var{zone}]]
 @cmindex date
+@item date [@var{specified-time} [@var{zone}]]
 Print the current local time as a human-readable string.  This command
 is an alias to the Emacs Lisp function @code{current-time-string}
 (@pxref{Time of Day,,, elisp, GNU Emacs Lisp Reference Manual}).
 
-@item diff [@var{option}]@dots{} @var{old} @var{new}
 @cmindex diff
+@item diff [@var{option}]@dots{} @var{old} @var{new}
 Compare the files @var{old} and @var{new} using Emacs's internal
 @code{diff} (not to be confused with @code{ediff}).  @xref{Comparing
 Files, , , emacs, The GNU Emacs Manual}.
@@ -661,18 +661,18 @@ List of Built-ins
 command does not use Emacs's internal @code{diff}.  This is the same
 as using @samp{alias diff '*diff $@@*'}.
 
-@item dirname @var{filename}
 @cmindex dirname
+@item dirname @var{filename}
 Return the directory component of @var{filename}.
 
-@item dirs
 @cmindex dirs
+@item dirs
 Prints the directory stack.  Directories can be added or removed from
 the stack using the commands @command{pushd} and @command{popd},
 respectively.
 
-@item du [@var{option}]@dots{} @var{file}@dots{}
 @cmindex du
+@item du [@var{option}]@dots{} @var{file}@dots{}
 Summarize disk usage for each file, recursing into directories.
 
 @command{du} accepts the following options:
@@ -720,8 +720,8 @@ List of Built-ins
 
 @end table
 
-@item echo [-n | -N] [@var{arg}]@dots{}
 @cmindex echo
+@item echo [-n | -N] [@var{arg}]@dots{}
 Prints the value of each @var{arg}.  By default, this prints in a
 Lisp-friendly fashion (so that the value is useful to a Lisp command
 using the result of @command{echo} as an argument).  If a single
@@ -739,16 +739,16 @@ List of Built-ins
 or @code{-N} to enable it (the default when
 @code{eshell-plain-echo-behavior} is non-@code{nil}).
 
-@item env [@var{var}=@var{value}]@dots{} [@var{command}]@dots{}
 @cmindex env
+@item env [@var{var}=@var{value}]@dots{} [@var{command}]@dots{}
 With no arguments, print the current environment variables.  If you
 pass arguments to this command, then @command{env} will execute the
 arguments as a command.  If you pass any initial arguments of the form
 @samp{@var{var}=@var{value}}, @command{env} will first set @var{var}
 to @var{value} before running the command.
 
-@item eshell-debug [error | form | process]@dots{}
 @cmindex eshell-debug
+@item eshell-debug [error | form | process]@dots{}
 Toggle debugging information for Eshell itself.  You can pass this
 command one or more of the following arguments:
 
@@ -768,30 +768,30 @@ List of Built-ins
 
 @end itemize
 
-@item exit
 @cmindex exit
+@item exit
 @vindex eshell-kill-on-exit
 Exit Eshell and save the history.  By default, this command kills the
 Eshell buffer, but if @code{eshell-kill-on-exit} is @code{nil}, then
 the buffer is merely buried instead.
 
-@item export [@var{name}=@var{value}]@dots{}
 @cmindex export
+@item export [@var{name}=@var{value}]@dots{}
 Set environment variables using input like Bash's @command{export}, as
 in @samp{export @var{var1}=@var{val1} @var{var2}=@var{val2} @dots{}}.
 
-@item grep [@var{arg}]@dots{}
 @cmindex grep
-@itemx agrep [@var{arg}]@dots{}
+@item grep [@var{arg}]@dots{}
 @cmindex agrep
-@itemx egrep [@var{arg}]@dots{}
+@itemx agrep [@var{arg}]@dots{}
 @cmindex egrep
-@itemx fgrep [@var{arg}]@dots{}
+@itemx egrep [@var{arg}]@dots{}
 @cmindex fgrep
-@itemx rgrep [@var{arg}]@dots{}
+@itemx fgrep [@var{arg}]@dots{}
 @cmindex rgrep
-@itemx glimpse [@var{arg}]@dots{}
+@itemx rgrep [@var{arg}]@dots{}
 @cmindex glimpse
+@itemx glimpse [@var{arg}]@dots{}
 The @command{grep} commands are compatible with GNU @command{grep},
 but open a compilation buffer in @code{grep-mode} instead.
 @xref{Grep Searching, , , emacs, The GNU Emacs Manual}.
@@ -803,9 +803,9 @@ List of Built-ins
 $@@*'}, though this setting applies to all of the built-in commands
 for which you would need to create a separate alias.
 
+@cmindex history
 @item history [@var{n}]
 @itemx history [-arw] [@var{filename}]
-@cmindex history
 Prints Eshell's input history.  With a numeric argument @var{n}, this
 command prints the @var{n} most recent items in the history.
 Alternately, you can specify the following options:
@@ -824,8 +824,8 @@ List of Built-ins
 
 @end table
 
-@item info [@var{manual} [@var{item}]@dots{}]
 @cmindex info
+@item info [@var{manual} [@var{item}]@dots{}]
 Browse the available Info documentation.  With no arguments, browse
 the top-level menu.  Otherwise, show the manual for @var{manual},
 selecting the menu entry for @var{item}.
@@ -834,25 +834,25 @@ List of Built-ins
 uses Emacs's internal Info reader.  @xref{Misc Help, , , emacs, The
 GNU Emacs Manual}.
 
-@item jobs
 @cmindex jobs
+@item jobs
 List subprocesses of the Emacs process, if any, using the function
 @code{list-processes}.
 
-@item kill [-@var{signal}] [@var{pid} | @var{process}]
 @cmindex kill
+@item kill [-@var{signal}] [@var{pid} | @var{process}]
 Kill processes.  Takes a PID or a process object and an optional
 @var{signal} specifier which can either be a number or a signal name.
 
-@item listify [@var{arg}]@dots{}
 @cmindex listify
+@item listify [@var{arg}]@dots{}
 Return the arguments as a single list.  With a single argument, return
 it as-is if it's already a list, or otherwise wrap it in a list.  With
 multiple arguments, return a list of all of them.
 
+@cmindex ln
 @item ln [@var{option}]@dots{} @var{target} [@var{link-name}]
 @itemx ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
-@cmindex ln
 Create a link to the specified @var{target} named @var{link-name} or
 create links to multiple @var{targets} in @var{directory}.
 
@@ -886,8 +886,8 @@ List of Built-ins
 
 @end table
 
-@item locate @var{arg}@dots{}
 @cmindex locate
+@item locate @var{arg}@dots{}
 Alias to Emacs's @code{locate} function, which simply runs the external
 @command{locate} command and parses the results.
 @xref{Dired and Find, , , emacs, The GNU Emacs Manual}.
@@ -897,8 +897,8 @@ List of Built-ins
 internal @code{locate} is not used.  This is the same as using
 @samp{alias locate '*locate $@@*'}.
 
-@item ls [@var{option}]@dots{} [@var{file}]@dots{}
 @cmindex ls
+@item ls [@var{option}]@dots{} [@var{file}]@dots{}
 List information about each @var{file}, including the contents of any
 specified directories.  If @var{file} is unspecified, list the
 contents of the current directory.
@@ -999,25 +999,25 @@ List of Built-ins
 
 @end table
 
-@item make [@var{arg}]@dots{}
 @cmindex make
+@item make [@var{arg}]@dots{}
 Run @command{make} through @code{compile} when run asynchronously
 (e.g., @samp{make &}).  @xref{Compilation, , , emacs, The GNU Emacs
 Manual}.  Otherwise call the external @command{make} command.
 
-@item man [@var{arg}]@dots{}
 @cmindex man
+@item man [@var{arg}]@dots{}
 Display Man pages using the Emacs @code{man} command.
 @xref{Man Page, , , emacs, The GNU Emacs Manual}.
 
-@item mkdir [-p] @var{directory}@dots{}
 @cmindex mkdir
+@item mkdir [-p] @var{directory}@dots{}
 Make new directories.  With @code{-p} or @code{--parents},
 automatically make any necessary parent directories as well.
 
+@cmindex mv
 @item mv [@var{option}]@dots{} @var{source} @var{dest}
 @itemx mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
-@cmindex mv
 Rename the file @var{source} to @var{dest} or move @var{source} into
 @var{directory}.
 
@@ -1048,14 +1048,14 @@ List of Built-ins
 
 @end table
 
-@item occur @var{regexp} [@var{nlines}]
 @cmindex occur
+@item occur @var{regexp} [@var{nlines}]
 Alias to Emacs's @code{occur}.
 @xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
 
+@cmindex popd
 @item popd
 @item popd +@var{n}
-@cmindex popd
 Pop a directory from the directory stack and switch to a another place
 in the stack.  This command can take the following forms:
 
@@ -1071,14 +1071,14 @@ List of Built-ins
 
 @end table
 
-@item printnl [@var{arg}]@dots{}
 @cmindex printnl
+@item printnl [@var{arg}]@dots{}
 Print all the @var{arg}s separated by newlines.
 
+@cmindex pushd
 @item pushd
 @itemx pushd @var{directory}
 @itemx pushd +@var{n}
-@cmindex pushd
 Push the current directory onto the directory stack, then change to
 another directory.  This command can take the following forms:
 
@@ -1107,12 +1107,12 @@ List of Built-ins
 
 @end table
 
-@item pwd
 @cmindex pwd
+@item pwd
 Prints the current working directory.
 
-@item rm [@var{option}]@dots{} @var{item}@dots{}
 @cmindex rm
+@item rm [@var{option}]@dots{} @var{item}@dots{}
 Removes files, buffers, processes, or Emacs Lisp symbols, depending on
 the type of each @var{item}.
 
@@ -1146,59 +1146,59 @@ List of Built-ins
 
 @end table
 
-@item rmdir @var{directory}@dots{}
 @cmindex rmdir
+@item rmdir @var{directory}@dots{}
 Removes directories if they are empty.
 
-@item set [@var{var} @var{value}]@dots{}
 @cmindex set
+@item set [@var{var} @var{value}]@dots{}
 Set variable values, using the function @code{set} like a command
 (@pxref{Setting Variables,,, elisp, GNU Emacs Lisp Reference Manual}).
 The value of @var{var} can be a symbol, in which case it refers to a
 Lisp variable, or a string, referring to an environment variable
 (@pxref{Arguments}).
 
-@item setq [@var{symbol} @var{value}]@dots{}
 @cmindex setq
+@item setq [@var{symbol} @var{value}]@dots{}
 Set variable values, using the function @code{setq} like a command
 (@pxref{Setting Variables,,, elisp, GNU Emacs Lisp Reference Manual}).
 
-@item source @var{file} [@var{argument}]@dots{}
 @cmindex source
+@item source @var{file} [@var{argument}]@dots{}
 Source an Eshell script named @var{file} in a subshell environment,
 passing any @var{argument}s to the script (@pxref{Scripts}).  This is
 not to be confused with the command @command{.}, which sources a file
 in the current environment.
 
-@item time @var{command}@dots{}
 @cmindex time
+@item time @var{command}@dots{}
 Show the time elapsed during the execution of @var{command}.
 
+@cmindex umask
 @item umask [-S]
 @itemx umask @var{mode}
-@cmindex umask
 View the default file permissions for newly created files and
 directories.  If you pass @code{-S} or @code{--symbolic}, view the
 mode symbolically.  With @var{mode}, set the default permissions to
 this value.
 
-@item unset [@var{var}]@dots{}
 @cmindex unset
+@item unset [@var{var}]@dots{}
 Unset one or more variables.  As with @command{set}, the value of
 @var{var} can be a symbol, in which case it refers to a Lisp variable,
 or a string, referring to an environment variable.
 
-@item wait [@var{process}]@dots{}
 @cmindex wait
+@item wait [@var{process}]@dots{}
 Wait until each specified @var{process} has exited.
 
-@item which @var{command}@dots{}
 @cmindex which
+@item which @var{command}@dots{}
 For each @var{command}, identify what kind of command it is and its
 location.
 
-@item whoami
 @cmindex whoami
+@item whoami
 Print the current user.  This Eshell version of @command{whoami} is
 connection-aware, so for remote directories, it will print the user
 associated with that connection.
@@ -2601,17 +2601,17 @@ Tramp extensions
 
 @table @code
 
-@item su [- | -l] [@var{user}]
 @cmindex su
+@item su [- | -l] [@var{user}]
 Uses TRAMP's @command{su} method (@pxref{Inline methods, , , tramp,
 The Tramp Manual}) to change the current user to @var{user} (or root
 if unspecified).  With @code{-}, @code{-l}, or @code{--login}, provide
 a login environment.
 
-@item sudo [-u @var{user}] [-s | @var{command}@dots{}]
 @cmindex sudo
-@itemx doas [-u @var{user}] [-s | @var{command}@dots{}]
+@item sudo [-u @var{user}] [-s | @var{command}@dots{}]
 @cmindex doas
+@itemx doas [-u @var{user}] [-s | @var{command}@dots{}]
 Uses TRAMP's @command{sudo} or @command{doas} method (@pxref{Inline
 methods, , , tramp, The Tramp Manual}) to run @var{command} as root
 via @command{sudo} or @command{doas}.  When specifying @code{-u
@@ -2630,59 +2630,59 @@ Extra built-in commands
 
 @table @code
 
-@item count @var{item} @var{seq} [@var{option}]@dots{}
 @cmindex count
+@item count @var{item} @var{seq} [@var{option}]@dots{}
 A wrapper around the function @code{cl-count} (@pxref{Searching
 Sequences,,, cl, GNU Emacs Common Lisp Emulation}).  This command can
 be used for comparing lists of strings.
 
-@item expr @var{str} [@var{separator}] [@var{arg}]@dots{}
 @cmindex expr
+@item expr @var{str} [@var{separator}] [@var{arg}]@dots{}
 An implementation of @command{expr} using the Calc package.
 @xref{Top,,, calc, The GNU Emacs Calculator}.
 
-@item ff @var{directory} @var{pattern}
 @cmindex ff
+@item ff @var{directory} @var{pattern}
 Shorthand for the the function @code{find-name-dired} (@pxref{Dired
 and Find, , , emacs, The Emacs Editor}).
 
-@item gf @var{directory} @var{regexp}
 @cmindex gf
+@item gf @var{directory} @var{regexp}
 Shorthand for the the function @code{find-grep-dired} (@pxref{Dired
 and Find, , , emacs, The Emacs Editor}).
 
-@item intersection @var{list1} @var{list2} [@var{option}]@dots{}
 @cmindex intersection
+@item intersection @var{list1} @var{list2} [@var{option}]@dots{}
 A wrapper around the function @code{cl-intersection} (@pxref{Lists as
 Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command
 can be used for comparing lists of strings.
 
-@item mismatch @var{seq1} @var{seq2} [@var{option}]@dots{}
 @cmindex mismatch
+@item mismatch @var{seq1} @var{seq2} [@var{option}]@dots{}
 A wrapper around the function @code{cl-mismatch} (@pxref{Searching
 Sequences,,, cl, GNU Emacs Common Lisp Emulation}).  This command can
 be used for comparing lists of strings.
 
-@item set-difference @var{list1} @var{list2} [@var{option}]@dots{}
 @cmindex set-difference
+@item set-difference @var{list1} @var{list2} [@var{option}]@dots{}
 A wrapper around the function @code{cl-set-difference} (@pxref{Lists
 as Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command can be
 used for comparing lists of strings.
 
-@item set-exclusive-or @var{list1} @var{list2} [@var{option}]@dots{}
 @cmindex set-exclusive-or
+@item set-exclusive-or @var{list1} @var{list2} [@var{option}]@dots{}
 A wrapper around the function @code{cl-set-exclusive-or} (@pxref{Lists
 as Sets,,, cl, GNU Emacs Common Lisp Emulation}).  This command can be
 used for comparing lists of strings.
 
-@item substitute @var{new} @var{old} @var{seq} [@var{option}]@dots{}
 @cmindex substitute
+@item substitute @var{new} @var{old} @var{seq} [@var{option}]@dots{}
 A wrapper around the function @code{cl-substitute} (@pxref{Sequence
 Functions,,, cl, GNU Emacs Common Lisp Emulation}).  This command can
 be used for comparing lists of strings.
 
-@item union @var{list1} @var{list2} [@var{option}]@dots{}
 @cmindex union
+@item union @var{list1} @var{list2} [@var{option}]@dots{}
 A wrapper around the function @code{cl-union} (@pxref{Lists as Sets,,,
 cl, GNU Emacs Common Lisp Emulation}).  This command can be used for
 comparing lists of strings.
-- 
2.25.1


[-- Attachment #4: 0003-Add-concept-indices-for-some-Eshell-commands.patch --]
[-- Type: text/plain, Size: 2439 bytes --]

From 0c843a8634d5fea5d3d8a21d6c5819abb3f9136c Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Thu, 8 Feb 2024 11:44:05 -0800
Subject: [PATCH 3/3] Add concept indices for some Eshell commands

* doc/misc/eshell.texi (List of Built-ins): Add indices for some
directory- and process-related commands.
(Aliases): Change to concept index.
---
 doc/misc/eshell.texi | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 3ff8e55ed03..3d0ace51d1e 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -3,7 +3,7 @@
 @setfilename ../../info/eshell.info
 @settitle Eshell: The Emacs Shell
 @include docstyle.texi
-@defindex cm
+@defcodeindex cm
 @syncodeindex vr fn
 @c %**end of header
 
@@ -529,6 +529,7 @@ List of Built-ins
 @command{cat}.
 
 @cmindex cd
+@cindex directories, changing
 @item cd
 @itemx cd @var{directory}
 @itemx cd -[@var{n}]
@@ -666,6 +667,7 @@ List of Built-ins
 Return the directory component of @var{filename}.
 
 @cmindex dirs
+@cindex directory stack, listing
 @item dirs
 Prints the directory stack.  Directories can be added or removed from
 the stack using the commands @command{pushd} and @command{popd},
@@ -835,11 +837,13 @@ List of Built-ins
 GNU Emacs Manual}.
 
 @cmindex jobs
+@cindex processes, listing
 @item jobs
 List subprocesses of the Emacs process, if any, using the function
 @code{list-processes}.
 
 @cmindex kill
+@cindex processes, signaling
 @item kill [-@var{signal}] [@var{pid} | @var{process}]
 Kill processes.  Takes a PID or a process object and an optional
 @var{signal} specifier which can either be a number or a signal name.
@@ -1054,6 +1058,7 @@ List of Built-ins
 @xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
 
 @cmindex popd
+@cindex directory stack, removing from
 @item popd
 @item popd +@var{n}
 Pop a directory from the directory stack and switch to a another place
@@ -1076,6 +1081,7 @@ List of Built-ins
 Print all the @var{arg}s separated by newlines.
 
 @cmindex pushd
+@cindex directory stack, adding to
 @item pushd
 @itemx pushd @var{directory}
 @itemx pushd +@var{n}
@@ -1501,7 +1507,7 @@ Aliases
 
 @node Remote Access
 @section Remote Access
-@cmindex remote access
+@cindex remote access
 
 Since Eshell uses Emacs facilities for most of its functionality, you
 can access remote hosts transparently.  To connect to a remote host,
-- 
2.25.1

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

[Stefan Kangas]

Jim Porter <jporterbugs@gmail.com> writes:

> 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 don't want to object to splitting it up or anything like that.
I'm only offering my perspective and ideas.

Should you go a different route, here are some ideas to improve your
categorization:

    # Commands for Directories
    cd, dirs, du, ls, mkdir, popd, pushd, pwd, rmdir

    # Commands for Files
    cat, cp, diff, ln, mv, rm

Probably unify these into one?

    # Commands for Searching
    grep, agrep, egrep, fgrep, rgrep, glimpse, info, locate, man, occur

"info" and "man" might belong under Miscellaneous Commands.

BTW, the "glimpse" command could use some documentation.  It's not as
popular as "grep", AFAIK, and many users don't know what it does.

    # Commands for Variables
    env, export, set, setq, unset

    # Commands for Using Other Commands
    ., addpath, alias, compile, jobs, kill, source, time, wait, which

Rather than "Using Other Commands" isn't this called "job control" or
something like that?

    # Miscellaneous Commands
    basename, clear, clear-scrollback, date, dirname, echo, eshell-debug,
    exit, history, listify, make, printnl, umask, whoami

"basename", "dirname" might belong under files/directories.

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

Yeah, this would also be an improvement.

BTW, another idea that might work is to offer both a summary in the form
of a table/list, and the detailed documentation in subnodes.  For
example, the above list placing commands into different categories could
go on the first page of your most recent patch.

Indexing would definitely help, too.  It's the first thing I reach for
in any manual.

Thanks again for working on improving the Eshell manual.  It's much
appreciated.

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

[Eli Zaretskii]

> Date: Thu, 8 Feb 2024 12:30:46 -0800
> Cc: stefankangas@gmail.com, 68963@debbugs.gnu.org
> From: Jim Porter <jporterbugs@gmail.com>
> 
> > 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.
> 
> Attached are some initial improvements to the indexing (patch 0003 in 
> the series). It would probably be worth adding concept indices to 
> most/all of the built-in commands, but the few I added here are pretty 
> straightforward, and I can just poke at this a bit at a time for the 
> remainder. (Writing documentation isn't the most viscerally exciting 
> thing to do, so I prefer to spread the work out.)
> 
> I also added patch 0002, which moves the indexing above the "@item"s. 
> That way, when you navigate to the entry from the index, it shows the 
> header line listing the supported arguments when viewing the 
> documentation as HTML.

LGTM, thanks.  Yes, index entries should always be before the
corresponding @item's.

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

[Jim Porter]

On 2/8/2024 11:05 PM, Eli Zaretskii wrote:
> LGTM, thanks.  Yes, index entries should always be before the
> corresponding @item's.

Thanks, good to know for sure. Merged to master as de5acc3b0d8, so 
closing this now. I'll keep looking for more places to add indexing to 
the manual as I go through it.