Subject: bug#68838: closed (Re: bug#68838: 30.0.50; [PATCH] Document Eshell built-in commands' arguments in the manual)

From: [email-masked] (GNU bug Tracking System)
Date: Mon, 05 Feb 2024 05:23:02 +0000

Your bug report

#68838: 30.0.50; [PATCH] Document Eshell built-in commands' arguments in the manual

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

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

Subject: Re: bug#68838: 30.0.50; [PATCH] Document Eshell built-in commands' arguments in the manual
From: Jim Porter <[email-masked]>
To: Eli Zaretskii <[email-masked]>
Cc: [email-masked]
Date: Sun, 4 Feb 2024 21:21:46 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

I've now merged my latest patch to master as 5c43ef86bf1, so closing 
this bug. (Mainly so I can get to work on splitting this section up into 
small chunks.) Of course, if there are any followup issues, just let me 
know.

Subject: 30.0.50; [PATCH] Document Eshell built-in commands' arguments in the manual
From: Jim Porter <[email-masked]>
To: [email-masked]
Date: Tue, 30 Jan 2024 21:49:39 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

Eshell's manual documents all its built-in commands, but the 
documentation is too brief in my opinion. It should document the 
command-line options. Here's a patch to do so.

(Later, I'd like to break this giant list into subsections, but I'll 
wait on that since any changes to *this* patch would likely cause all 
sorts of headaches with a reorganization patch.)

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