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

From: [email-masked] (GNU bug Tracking System)
Date: Sat, 10 Feb 2024 01:46:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
68963: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=68963
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command documentation into subsections
From: Jim Porter <[email-masked]>
To: Eli Zaretskii <[email-masked]>
Cc: [email-masked], [email-masked]
Date: Fri, 9 Feb 2024 17:44:59 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

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.

Subject: 30.0.50; [PATCH] Split Eshell built-in command documentation into subsections
From: Jim Porter <[email-masked]>
To: [email-masked]
Date: Tue, 6 Feb 2024 16:02:32 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

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

From dff38b933051b9a9a496814093b5984662cc2255 Mon Sep 17 00:00:00 2001
From: Jim Porter <[email-masked]>
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