From 8f205a66e86cd72636558f2974d99440dec8e097 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Tue, 15 Aug 2023 18:51:20 -0700
Subject: [PATCH] Document arguments to Eshell's built-in commands

* lisp/eshell/em-unix.el (eshell/ln): LINK_NAME is required.

* lisp/eshell/esh-ext.el (eshell/addpath):
* lisp/eshell/esh-var.el (eshell/env): Improve help strings slightly.

* doc/misc/eshell.texi (Scripts): Explain $0, $1, etc.
(Dollars Expansion): Use "@dots{}" instead of "...".
(Built-ins, Tramp extensions, Extra built-in commands): Document
command-line arguments.
---
 doc/misc/eshell.texi   | 651 ++++++++++++++++++++++++++++++-----------
 lisp/eshell/em-unix.el |   8 +-
 lisp/eshell/esh-ext.el |   6 +-
 lisp/eshell/esh-var.el |   2 +-
 4 files changed, 495 insertions(+), 172 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index da5e1ef1d03..d7e51445dd7 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -481,72 +481,88 @@ Built-ins
 
 @table @code
 
-@item .
+@item . @var{file} [@var{argument}]@dots{}
 @cmindex .
-Source an Eshell file in the current environment.  This is not to be
-confused with the command @command{source}, which sources a file in a
-subshell environment.
+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 a given path or set of paths to the PATH environment variable, or,
-with no arguments, prints the current paths in this variable.
+Adds the directory (or list of directories) @var{directory} to the
+@code{$PATH} environment variable.  By default, this adds the
+directories to the end of @code{$PATH}; 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 (@pxref{Aliases}).  This adds it to the aliases file.
+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
+@item basename @var{filename}
 @cmindex basename
-Return a file name without its directory.
+Return @var{filename} without its directory.
 
-@item cat
+@item cat @var{file}@dots{}
 @cmindex cat
-Concatenate file contents into standard output.  If in a pipeline, or
-if the file is not a regular file, directory, or symlink, then this
-command reverts to the system's definition of @command{cat}.
+Concatenate the contents of @var{files} 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 cd
+@itemx cd @var{directory}
+@itemx cd -[@var{n}]
+@itemx cd =[@var{regexp}]
 @cmindex cd
-This command changes the current working directory.  Usually, it is
-invoked as @kbd{cd @var{dir}} where @file{@var{dir}} is the new
-working directory.  But @command{cd} knows about a few special
-arguments:
+Change the current working directory.  This command can take several
+forms:
 
-@itemize @minus{}
-@item
-When it receives no argument at all, it changes to the home directory.
+@table @code
 
-@item
-Giving the command @kbd{cd -} changes back to the previous working
-directory (this is the same as @kbd{cd $-}).
+@item cd
+Change to the user's home directory.
 
-@item
-The command @kbd{cd =} shows the directory ring.  Each line is
-numbered.
+@item cd @var{directory}
+Change to the directory @var{directory}.
 
-@item
-With @kbd{cd =foo}, Eshell searches the directory ring for a directory
-matching the regular expression @samp{foo}, and changes to that
-directory.
+@item cd -
+Change back to the previous working directory (this is the same as
+@kbd{cd $-}).
 
-@item
-With @kbd{cd -42}, you can access the directory stack slots by number.
+@item cd -@var{n}
+Change to the directory in the @var{nth} slot of the directory stack.
+
+@item cd =
+Show the directory ring.  Each line is numbered.
+
+@item cd =@var{regex}
+Search the directory ring for a directory matching the regular
+expression @var{regexp} and change to that directory.
+
+@end table
 
-@item
 @vindex eshell-cd-shows-directory
 @vindex eshell-list-files-after-cd
 If @code{eshell-cd-shows-directory} is non-@code{nil}, @command{cd}
 will report the directory it changes to.  If
 @code{eshell-list-files-after-cd} is non-@code{nil}, then @command{ls}
 is called with any remaining arguments after changing directories.
-@end itemize
 
-@item clear
+@item clear [@var{scrollback}]
 @cmindex clear
 Scrolls the contents of the Eshell window out of sight, leaving a
-blank window.  If provided with an optional non-@code{nil} argument,
-the scrollback contents are cleared instead.
+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
@@ -554,21 +570,30 @@ Built-ins
 command @command{clear}, this command deletes content in the Eshell
 buffer.
 
-@item compile
+@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.  This is particularly useful when defining aliases, so
+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
+@item cp [@var{option}@dots{}] @var{source} @var{dest}
+@item cp [@var{option}@dots{}] @var{source}@dots{} @var{directory}
 @cmindex cp
-Copy a file to a new location or copy multiple files to the same
-directory.
+Copy the file @var{source} to @var{dest} or @var{source} into
+@var{directory}.
 
 @vindex eshell-cp-overwrite-files
 @vindex eshell-cp-interactive-query
@@ -577,26 +602,59 @@ Built-ins
 @code{eshell-cp-interactive-query} is non-@code{nil}, then
 @command{cp} will ask before overwriting anything.
 
-@item date
+@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 similar to, but slightly different from, the GNU Coreutils
-@command{date} 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
+@item diff [@var{option}]@dots{} @var{old} @var{new}
 @cmindex diff
-Compare files using Emacs's internal @code{diff} (not to be confused
-with @code{ediff}).  @xref{Comparing Files, , , emacs, The GNU Emacs
-Manual}.
+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
+@item dirname @var{filename}
 @cmindex dirname
-Return the directory component of a file name.
+Return the directory component of @var{filename}.
 
 @item dirs
 @cmindex dirs
@@ -604,25 +662,75 @@ Built-ins
 the stack using the commands @command{pushd} and @command{popd},
 respectively.
 
-@item du
+@item du [@var{option}]@dots{} @var{file}@dots{}
 @cmindex du
-Summarize disk usage for each file.
+Summarize disk usage for each file, recursing into directories.
+
+@command{du} accepts the following options:
+
+@table @asis
+
+@item @code{-a}, @code{--all}
+Print sizes for files, not just directories.
 
-@item echo
+@item @code{--block-size=@var{size}}
+Print sizes as number of blocks of size @var{size}.
+
+@item @code{-b}, @code{--bytes}
+Print file sizes in bytes.
+
+@item @code{-c}, @code{--total}
+Print a grand total of the sizes at the end.
+
+@item @code{-d}, @code{--max-depth=@var{depth}}
+Only print sizes for directories (or files with @code{--all}) that are
+@var{depth} or fewer levels below the command line arguments.
+
+@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{-k}, @code{--kilobytes}
+Print file sizes in kilobytes (like @code{--block-size=1024}).
+
+@item @code{-L}, @code{--dereference}
+Follow symbolic links when traversing files.
+
+@item @code{-m}, @code{--megabytes}
+Print file sizes in megabytes (like @code{--block-size=1048576}).
+
+@item @code{-s}, @code{--summarize}
+Don't recurse into subdirectories (like @code{--max-depth=0}).
+
+@item @code{-x}, @code{--one-file-system}
+Skip any directories that reside on different filesystems.
+
+@end table
+
+@item echo [-n | -N] [@var{arg}]@dots{}
 @cmindex echo
-Echoes its input.  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.
+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.
 
-@item env
+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 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
@@ -630,7 +738,7 @@ Built-ins
 @samp{@var{var}=@var{value}}, @command{env} will first set @var{var}
 to @var{value} before running the command.
 
-@item eshell-debug
+@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:
@@ -658,65 +766,86 @@ Built-ins
 Eshell buffer, but if @code{eshell-kill-on-exit} is @code{nil}, then
 the buffer is merely buried instead.
 
-@item export
+@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 grep
+@item grep [@var{arg}]@dots{}
 @cmindex grep
-@itemx agrep
+@itemx agrep [@var{arg}]@dots{}
 @cmindex agrep
-@itemx egrep
+@itemx egrep [@var{arg}]@dots{}
 @cmindex egrep
-@itemx fgrep
+@itemx fgrep [@var{arg}]@dots{}
 @cmindex fgrep
-@itemx rgrep
+@itemx rgrep [@var{arg}]@dots{}
 @cmindex rgrep
-@itemx glimpse
+@itemx glimpse [@var{arg}]@dots{}
 @cmindex glimpse
 The @command{grep} commands are compatible with GNU @command{grep},
-but use Emacs's internal @code{grep} instead.
+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 Emacs's internal @code{grep}.  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.
+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 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.
+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 info
+@item @code{-r}, @code{--read}
+Read history items from the history file and append it 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.  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}.
+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
+@item kill [-@var{signal}] [@var{pid} | @var{process}]
 @cmindex kill
 Kill processes.  Takes a PID or a process object and an optional
-signal specifier which can either be a number or a signal name.
+@var{signal} specifier which can either be a number or a signal name.
 
-@item listify
+@item listify [@var{arg}]@dots{}
 @cmindex listify
-Eshell version of @code{list}.  Allows you to create a list using Eshell
-syntax, rather than Elisp syntax.  For example, @samp{listify foo bar}
-and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}.
+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
+@item ln [@var{option}]@dots{} @var{target} [@var{link-name}]
+@itemx ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
 @cmindex ln
-Create links to files.
+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
@@ -725,7 +854,30 @@ Built-ins
 @code{eshell-ln-interactive-query} is non-@code{nil}, then
 @command{ln} will ask before overwriting files.
 
-@item locate
+@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.
@@ -736,51 +888,129 @@ Built-ins
 internal @code{locate} is not used.  This is the same as using
 @samp{alias locate '*locate $@@*'}.
 
-@item ls
+@item ls [@var{option}]@dots{} [@var{file}]@dots{}
 @cmindex ls
-Lists the contents of directories.
+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}}}.
+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.
 
 @vindex eshell-ls-date-format
-The user option @code{eshell-ls-date-format} determines how the date
-is displayed when using the @option{-l} option.  The date is produced
-using the function @code{format-time-string} (@pxref{Time Parsing,,,
-elisp, GNU Emacs Lisp Reference Manual}).
+@item @code{-l}
+Use a long listing format showing details for each file.  The user
+option @code{eshell-ls-date-format} determines how the date is
+displayed when using this option.  The date is produced using the
+function @code{format-time-string} (@pxref{Time Parsing,,, elisp, GNU
+Emacs Lisp Reference Manual}).
 
-@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 @code{-L}, @code{--dereference}
+Follow symbolic links when listing entries.
+
+@item @code{-n}, @code{--numeric-uid-gid}
+Show UIDs and GIDs numerically, instead of using their names.
+
+@item @code{-r}, @code{--reverse}
+Reverse order when sorting.
+
+@item @code{-R}, @code{--recursive}
+List subdirectories recursively.
+
+@item @code{-s}, @code{--size}
+Show the size of each file in blocks.
 
 @vindex eshell-ls-default-blocksize
-The user option @code{eshell-ls-default-blocksize} determines the
-default blocksize used when displaying file sizes with the option
-@option{-s}.
+@item @code{-S}
+Sort by file size, with largest files first.  The user option
+@code{eshell-ls-default-blocksize} determines the default blocksize
+used when displaying file sizes with this option.
+
+@item @code{-t}
+Sort by modification time, with newest files first.
 
-@item make
+@item @code{-u}
+Sort by last access time, with newest files first.
+
+@item @code{-U}
+Do not sort results.  Instead, list entries in their directory order.
+
+@item @code{-x}
+List entries by lines instead of by columns.
+
+@item @code{-X}
+Sort alphabetically by file extension.
+
+@item @code{-1}
+List one file per line.
+
+@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
+@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
+@item mkdir [-p] @var{directory}@dots{}
 @cmindex mkdir
-Make new directories.
+Make new directories.  With @code{-p} or @code{--parents},
+automatically make any necessary parent directories as well.
 
-@item mv
+@item mv [@var{option}]@dots{} @var{source} @var{dest}
+@itemx mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
 @cmindex mv
-Move or rename files.
+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
@@ -789,37 +1019,90 @@ Built-ins
 @code{eshell-mv-interactive-query} is non-@code{nil}, @command{mv}
 will prompt before overwriting anything.
 
-@item occur
+@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
 Pop a directory from the directory stack and switch to a another place
-in the stack.
+in the stack.  This command can take the following forms:
 
-@item printnl
+@table @code
+
+@item popd
+Remove the current directory from the directory stack and change to
+the directory beneath it.
+
+@item popd +@var{n}
+Remove the current directory from the directory stack and change to
+the @var{nth} directory in the stack (counting from zero).
+
+@end table
+
+@item printnl [@var{arg}]@dots{}
 @cmindex printnl
-Print the arguments separated by newlines.
+Print each argument separated by newlines.
 
 @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.
+another directory.  This command can take the following forms:
+
+@table @code
+
+@vindex eshell-pushd-tohome
+@item pushd
+Swap the current directory with the directory on the top of the stack.
+If @code{eshell-pushd-tohome} is non-@code{nil}, push the current
+directory onto the stack and change to the user's home directory (like
+@samp{pushd ~}).
 
 @vindex eshell-pushd-dunique
+@item pushd @var{directory}
+Push the current directory onto the stack and change to
+@var{directory}.  If @code{eshell-pushd-dunique} is non-@code{nil},
+then only unique directories will be added to the stack.
+
 @vindex eshell-pushd-dextract
-If @code{eshell-pushd-dunique} is non-@code{nil}, then only unique
-directories will be added to the stack.  If
-@code{eshell-pushd-dextract} is non-@code{nil}, then @samp{pushd
-+@var{n}} will pop the @var{n}th directory to the top of the stack.
+@item pushd +@var{n}
+Change to the @var{nth} directory in the directory stack (counting
+from zero), and ``rotate'' the stack by moving any elements before the
+@var{nth} to the bottom.  If @code{eshell-pushd-dextract} is
+non-@code{nil}, then @samp{pushd +@var{n}} will instead pop the
+@var{n}th directory to the top of the stack.
+
+@end table
 
 @item pwd
 @cmindex pwd
 Prints the current working directory.
 
-@item rm
+@item rm [@var{option}]@dots{} @var{item}@dots{}
 @cmindex rm
 Removes files, buffers, processes, or Emacs Lisp symbols, depending on
 the argument.
@@ -832,56 +1115,83 @@ Built-ins
 @command{rm} can also remove directories.  Otherwise, @command{rmdir}
 is required.
 
-@item rmdir
+@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
+
+@item rmdir @var{directory}@dots{}
 @cmindex rmdir
 Removes directories if they are empty.
 
-@item set
+@item set [@var{var} @var{value}]@dots{}
 @cmindex set
 Set variable values, using the function @code{set} like a command
 (@pxref{Setting Variables,,, elisp, GNU Emacs Lisp Reference Manual}).
-A variable name can be a symbol, in which case it refers to a Lisp
-variable, or a string, referring to an environment variable
+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
+@item setq [@var{symbol} @var{value}]@dots{}
 @cmindex setq
 Set variable values, using the function @code{setq} like a command
 (@pxref{Setting Variables,,, elisp, GNU Emacs Lisp Reference Manual}).
 
-@item source
+@item source @var{file} [@var{argument}]@dots{}
 @cmindex source
-Source an Eshell file in a subshell environment.  This is not to be
-confused with the command @command{.}, which sources a file in the
-current environment.
+Source an Eshell script named @var{file} in a subshell environment,
+passing any @var{arguments} 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
+@item time @var{command}@dots{}
 @cmindex time
-Show the time elapsed during a command's execution.
+Show the time elapsed during the execution of @var{command}.
 
-@item umask
+@item umask [-S] [@var{mode}]
 @cmindex umask
-Set or view the default file permissions for newly created files and
-directories.
+View the default file permissions for newly created files and
+directories.  With @var{mode}, set the default permissions to this
+value.  If you pass @code{-s} or @code{--symbolic}, view the mode
+symbolically.
 
-@item unset
+@item unset [@var{var}]@dots{}
 @cmindex unset
-Unset one or more variables.  As with @command{set}, a variable name
-can be a symbol, in which case it refers to a Lisp variable, or a
-string, referring to an environment variable.
+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
+@item wait [@var{process}]@dots{}
 @cmindex wait
-Wait until a process has successfully completed.
+Wait until one or more processes have exited.
 
-@item which
+@item which @var{command}@dots{}
 @cmindex which
-Identify a command and its location.
+For each @var{command}, identify what kind of command it is and its
+location.
 
 @item whoami
 @cmindex whoami
-Print the current user.  This Eshell version of @command{whoami}
-supports Tramp.
+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.
 @end table
 
 @subsection Defining new built-in commands
@@ -1353,6 +1663,11 @@ Scripts
 are invoked from Eshell with @command{source}, or from anywhere in Emacs
 with @code{eshell-source-file}.
 
+Like with aliases (@pxref{Aliases}), Eshell scripts can accept any
+number of arguments.  Within the script, you can refer to these with
+the special variables @code{$0}, @code{$1}, @dots{}, @code{$9}, and
+@code{$*}.
+
 @cmindex .
 If you wish to load a script into your @emph{current} environment,
 rather than in a subshell, use the @code{.} command.
@@ -1452,7 +1767,7 @@ Dollars Expansion
 @command{@var{command}}, but writes the output to a temporary file and
 returns the file name.
 
-@item $@var{expr}[@var{i...}]
+@item $@var{expr}[@var{i@dots{}}]
 Expands to the @var{i}th element of the result of @var{expr}, an
 expression in one of the above forms listed here.  If multiple indices
 are supplied, this will return a list containing the elements for each
@@ -1501,7 +1816,7 @@ Dollars Expansion
 expand to @code{2}, i.e.@: the second element of the first list member
 (all indices are zero-based).
 
-@item $@var{expr}[@var{regexp} @var{i...}]
+@item $@var{expr}[@var{regexp} @var{i@dots{}}]
 As above (when @var{expr} expands to a string), but use @var{regexp}
 to split the string.  @var{regexp} can be any form other than a
 number.  For example, @samp{$@var{var}[: 0]} will return the first
@@ -2275,15 +2590,23 @@ Tramp extensions
 
 @table @code
 
-@item su
+@item su [- | -l] [@var{user}]
 @cmindex su
-@itemx sudo
+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}...]
 @cmindex sudo
-@itemx doas
+@itemx doas [-u @var{user}] [-s | @var{command}...]
 @cmindex doas
-Uses TRAMP's @command{su}, @command{sudo}, or @command{doas} method
-(@pxref{Inline methods, , , tramp, The Tramp Manual}) to run a command
-via @command{su}, @command{sudo}, or @command{doas}.
+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
+@var{user}} or @code{--user @var{user}}, run the command as @var{user}
+instead.  With @code{-s} or @code{--shell}, start a shell instead of
+running @var{command}.
 
 @end table
 
@@ -2296,58 +2619,58 @@ Extra built-in commands
 
 @table @code
 
-@item count
+@item count @var{item} @var{seq} [@var{option}]...
 @cmindex count
 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
+@item expr @var{str} [@var{separator}] [@var{arg}]...
 @cmindex expr
 An implementation of @command{expr} using the Calc package.
 @xref{Top,,, calc, The GNU Emacs Calculator}.
 
-@item ff
+@item ff @var{directory} @var{pattern}
 @cmindex ff
 Shorthand for the the function @code{find-name-dired} (@pxref{Dired
 and Find, , , emacs, The Emacs Editor}).
 
-@item gf
+@item gf @var{directory} @var{regexp}
 @cmindex gf
 Shorthand for the the function @code{find-grep-dired} (@pxref{Dired
 and Find, , , emacs, The Emacs Editor}).
 
-@item intersection
+@item intersection @var{list1} @var{list2} [@var{option}]...
 @cmindex intersection
 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
+@item mismatch @var{seq1} @var{seq2} [@var{option}]...
 @cmindex mismatch
 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
+@item set-difference @var{list1} @var{list2} [@var{option}]...
 @cmindex set-difference
 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
+@item set-exclusive-or @var{list1} @var{list2} [@var{option}]...
 @cmindex set-exclusive-or
 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
+@item substitute @var{new} @var{old} @var{seq} [@var{option}]...
 @cmindex substitute
 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
+@item union @var{list1} @var{list2} [@var{option}]...
 @cmindex union
 A wrapper around the function @code{cl-union} (@pxref{Lists as Sets,,,
 cl, GNU Emacs Common Lisp Emulation}).  This command can be used for
diff --git a/lisp/eshell/em-unix.el b/lisp/eshell/em-unix.el
index a88c7e09946..1296b1603e6 100644
--- a/lisp/eshell/em-unix.el
+++ b/lisp/eshell/em-unix.el
@@ -618,11 +618,11 @@ eshell/ln
      :preserve-args
      :external "ln"
      :show-usage
-     :usage "[OPTION]... TARGET [LINK_NAME]
+     :usage "[OPTION]... TARGET LINK_NAME
    or:  ln [OPTION]... TARGET... DIRECTORY
-Create a link to the specified TARGET with optional LINK_NAME.  If there is
-more than one TARGET, the last argument must be a directory;  create links
-in DIRECTORY to each TARGET.  Create hard links by default, symbolic links
+Create a link to the specified TARGET with LINK_NAME.  If there is more
+than one TARGET, the last argument must be a directory;  create links in
+DIRECTORY to each TARGET.  Create hard links by default, symbolic links
 with `--symbolic'.  When creating hard links, each TARGET must exist.")
    (let ((no-dereference t))
      (eshell-mvcpln-template "ln" "linking"
diff --git a/lisp/eshell/esh-ext.el b/lisp/eshell/esh-ext.el
index dc2b93e574b..44861c222b8 100644
--- a/lisp/eshell/esh-ext.el
+++ b/lisp/eshell/esh-ext.el
@@ -253,10 +253,10 @@ eshell/addpath
   "Add a set of paths to PATH."
   (eshell-eval-using-options
    "addpath" args
-   '((?b "begin" nil prepend "add path element at beginning")
+   '((?b "begin" nil prepend "add to beginning of $PATH")
      (?h "help" nil nil  "display this usage message")
-     :usage "[-b] PATH
-Adds the given PATH to $PATH.")
+     :usage "[-b] DIR...
+Adds the given DIR to $PATH.")
    (let ((path (eshell-get-path t)))
      (if args
          (progn
diff --git a/lisp/eshell/esh-var.el b/lisp/eshell/esh-var.el
index 537bc4b0641..02b5c785625 100644
--- a/lisp/eshell/esh-var.el
+++ b/lisp/eshell/esh-var.el
@@ -433,7 +433,7 @@ eshell/env
      (?h "help" nil nil "show this usage screen")
      :external "env"
      :parse-leading-options-only
-     :usage "[NAME=VALUE]... [COMMAND [ARG]...]")
+     :usage "[NAME=VALUE]... [COMMAND]...")
    (if args
        (or (eshell-parse-local-variables args)
            (eshell-named-command (car args) (cdr args)))
-- 
2.25.1