bug#52289: Update Info documentation of Eshell's built-in commands

bug#52289: Update Info documentation of Eshell's built-in commands

[ej32u--- via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

Hello,

This patch adds the remaining Eshell built-ins to the Eshell Info
documentation.  It also expands on some of the existing commands and
mentions user options that affect a command's behavior.

To be clear, I am not very familiar with some of the commands (Eshell or
GNU/Bash) or their settings and behavior, which is why I think more
information would be helpful.

Thank you.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v1-0001-Update-the-Info-documentation-of-Eshell-s-built-i.patch --]
[-- Type: text/x-patch; name=v1-0001-Update-the-Info-documentation-of-Eshell-s-built-i.patch, Size: 14457 bytes --]

From b933f53818148676547dea7d587a9a6a3cd92d7e Mon Sep 17 00:00:00 2001
From: Earl Hyatt <okamsn@protonmail.com>
Date: Wed, 1 Dec 2021 20:47:18 -0500
Subject: [PATCH v1] Update the Info documentation of Eshell's built-in
 commands.

* doc/misc/eshell.texi (Built-in commands):
Add the remaining built-in Eshell commands to the list of built-ins.
Expand some of the descriptions and mention user options affecting
command behavior.  Sort these commands in alphabetical order.
---
 doc/misc/eshell.texi | 338 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 313 insertions(+), 25 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index fc2e3f3b11..4792ea9fc2 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -271,8 +271,30 @@ Built-ins
 external counterparts, and some have no external counterpart.  Most of
 these will print a usage message when given the @code{--help} option.
 
+In some cases, a built-in command's behavior can be configured via
+user settings, some of which are mentioned below.  For example,
+certain commands have two user settings to allow them to overwrite
+files without warning and to ensure that they always prompt before
+overwriting files.  If both settings are non-nil, the commands always
+prompt.  If both settings are nil (the default), the commands signal
+an error.
+
+Several commands observe the value of
+@code{eshell-default-target-is-dot}.  If non-nil, then the default
+target for the commands @command{cp}, @command{mv}, and @command{ln}
+is the current directory.
+
+A few commands are wrappers for more niche Emacs features, and can be
+loaded as part of the eshell-xtra module.  @xref{Extension modules}.
+
 @table @code
 
+@item .
+@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.
+
 @item addpath
 @cmindex addpath
 Adds a given path or set of paths to the PATH environment variable, or,
@@ -282,26 +304,128 @@ Built-ins
 @cmindex alias
 Define an alias (@pxref{Aliases}).  This adds it to the aliases file.
 
+@item basename
+@cmindex basename
+Return a file name without its directory.
+
+@item cat
+@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}.
+
+@item cd
+@cmindex cd
+This command changes the current working directory.  Usually, it is
+invoked as @samp{cd foo} where @file{foo} is the new working directory.
+But @command{cd} knows about a few special arguments:
+
+When it receives no argument at all, it changes to the home directory.
+
+Giving the command @samp{cd -} changes back to the previous working
+directory (this is the same as @samp{cd $-}).
+
+The command @samp{cd =} shows the directory stack.  Each line is
+numbered.
+
+With @samp{cd =foo}, Eshell searches the directory stack for a directory
+matching the regular expression @samp{foo} and changes to that
+directory.
+
+With @samp{cd -42}, you can access the directory stack by number.
+
+If @code{eshell-cd-shows-directory} is non-nil, @command{cd} will
+report the directory it changes to.  If
+@code{eshell-list-files-after-cd} is non-nil, then @command{ls} is
+called with any remaining arguments after changing directories.
+
 @item clear
 @cmindex clear
-Scrolls the contents of the eshell window out of sight, leaving a blank window.
-If provided with an optional non-nil argument, the scrollback contents are
-cleared instead.
+Scrolls the contents of the Eshell window out of sight, leaving a
+blank window.  If provided with an optional non-nil argument, the
+scrollback contents are cleared instead.
+
+@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 cp
+@cmindex cp
+Copy a file to a new location or copy multiple files to the same
+directory.
+
+If @code{eshell-cp-overwrite-files} is non-nil, then @command{cp} will
+overwrite files without warning.  If
+@code{eshell-cp-interactive-query} is non-nil, then @command{cp} will
+ask before overwriting anything.
 
 @item date
 @cmindex date
-Similar to, but slightly different from, the GNU Coreutils
+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.
 
 @item define
 @cmindex define
-Define a varalias.
+Define a variable alias.
 @xref{Variable Aliases, , , elisp, The Emacs Lisp Reference Manual}.
 
 @item diff
 @cmindex diff
-Use Emacs's internal @code{diff} (not to be confused with
-@code{ediff}).  @xref{Comparing Files, , , emacs, The GNU Emacs Manual}.
+Compare files using Emacs's internal @code{diff} (not to be confused
+with @code{ediff}).  @xref{Comparing Files, , , emacs, The GNU Emacs
+Manual}.
+
+If @code{eshell-plain-diff-behavior} is non-nil, then this command
+does not use Emacs's internal @code{diff}.  This is the same as using
+@samp{alias diff '*diff $*'}.
+
+@item dirname
+@cmindex dirname
+Return the directory component of a file name.
+
+@item dirs
+@cmindex dirs
+Prints the directory stack.  Directories can be added or removed from
+the stack using the commands @command{pushd} and @command{popd},
+respectively.
+
+@item du
+@cmindex du
+Summarize disk usage for each file.
+
+@item echo
+@cmindex echo
+Echos its input.  If @code{eshell-plain-echo-behavior} is non-nil,
+@command{echo} will try to behave more like a plain shell's
+@command{echo}.
+
+@item env
+@cmindex env
+Prints the current environment variables.  Unlike in Bash, this
+command does not yet support running commands with a modified
+environment.
+
+@item exit
+@cmindex exit
+Exit Eshell and save the history.  By default, this command kills the
+Eshell buffer, but if @code{eshell-kill-on-exit} is nil, then the
+buffer is merely buried instead.
+
+@item export
+@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 expr
+@cmindex expr
+An implementation of @command{expr} using the Calc package.
+@xref{Top,,, calc, The GNU Emacs Calculator}.
+
+This command can be loaded as part of the eshell-xtra module, which is
+disabled by default.
 
 @item grep
 @cmindex grep
@@ -313,13 +437,35 @@ Built-ins
 @cmindex fgrep
 @itemx glimpse
 @cmindex glimpse
-The @command{grep} commands are compatible with GNU @command{grep}, but
-use Emacs's internal @code{grep} instead.
+The @command{grep} commands are compatible with GNU @command{grep},
+but use Emacs's internal @code{grep} instead.
+@xref{Grep Searching, , , emacs, The GNU Emacs Manual}.
+
+If @code{eshell-plain-grep-behavior} is non-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.
+
+@item history
+@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.
 
 @item info
 @cmindex info
-Same as the external @command{info} command, but uses Emacs's internal
-Info reader.
+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}.
+
+@item intersection
+@cmindex intersection
+A wrapper around the function @code{cl-intersection}.  This command
+can be used for comparing lists of strings.
+
+This command can be loaded as part of the eshell-xtra module, which is
+disabled by default.
 
 @item jobs
 @cmindex jobs
@@ -337,46 +483,146 @@ Built-ins
 syntax, rather than Elisp syntax.  For example, @samp{listify foo bar}
 and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}.
 
+@item ln
+@cmindex ln
+Create links to files.
+
+If @code{eshell-ln-overwrite-files} is non-nil, @command{ln} will
+overwrite files without warning.  If
+@code{eshell-ln-interactive-query} is non-nil, then @command{ln} will
+ask before overwriting files.
+
 @item locate
 @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}.
 
+If @code{eshell-plain-locate-behavior} is non-nil, then Emacs's
+internal @code{locate} is not used.  This is the same as using
+@samp{alias locate '*locate $*'}.
+
+@item ls
+@cmindex ls
+Lists the contents of directories.
+
+If @code{eshell-ls-use-colors} is non-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 @samp{M-x customize-group RET eshell-ls RET}.
+
+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}.
+
+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.
+
+The user option @code{eshell-ls-default-blocksize} determines the
+default blocksize used when displaying file sizes with the option
+@option{-s}.
+
 @item make
 @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
+@cmindex man
+Display Man pages using the Emacs @code{man} command.
+@xref{Man Page, , , emacs, The GNU Emacs Manual}.
+
+@item mismatch
+@cmindex mismatch
+A wrapper around the function @code{cl-mismatch}.  This command can be
+used for comparing lists of strings.
+
+This command can be loaded as part of the eshell-xtra module, which is
+disabled by default.
+
+@item mkdir
+@cmindex mkdir
+Make new directories.
+
+@item mv
+@cmindex mv
+Move or rename files.
+
+If @code{eshell-mv-overwrite-files} is non-nil, @command{mv} will
+overwrite files without warning.  If
+@code{eshell-mv-interactive-query} is non-nil, @command{mv} will
+prompt before overwriting anything.
+
 @item occur
 @cmindex occur
 Alias to Emacs's @code{occur}.
 @xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
 
+@item popd
+@cmindex popd
+Pop a directory from the directory stack and switch to a another place
+in the stack.
+
 @item printnl
 @cmindex printnl
 Print the arguments separated by newlines.
 
-@item cd
-@cmindex cd
-This command changes the current working directory.  Usually, it is
-invoked as @samp{cd foo} where @file{foo} is the new working directory.
-But @command{cd} knows about a few special arguments:
+@item pushd
+@cmindex pushd
+Change to a directory and push that directory onto the directory
+stack.
 
-When it receives no argument at all, it changes to the home directory.
+If @code{eshell-pushd-dunique} is non-nil, then only unique
+directories will be added to the stack.  If
+@code{eshell-pushd-dextract} is non-nil, then @samp{pushd +@var{n}}
+will pop the @var{n}th directory to the top of the stack.
 
-Giving the command @samp{cd -} changes back to the previous working
-directory (this is the same as @samp{cd $-}).
+@item pwd
+@cmindex pwd
+Prints the current working directory.
 
-The command @samp{cd =} shows the directory stack.  Each line is
-numbered.
+@item rm
+@cmindex rm
+Removes files, buffers, processes, or Emacs Lisp symbols, depending on
+the argument.
 
-With @samp{cd =foo}, Eshell searches the directory stack for a directory
-matching the regular expression @samp{foo} and changes to that
-directory.
+If @code{eshell-rm-interactive-query} is non-nil, @command{rm} will
+prompt before removing anything.  If
+@code{eshell-rm-removes-directories} is non-nil, then @command{rm} can
+also remove directories.  Otherwise, @command{rmdir} is required.
 
-With @samp{cd -42}, you can access the directory stack by number.
+@item rmdir
+@cmindex rmdir
+Removes directories if they are empty.
+
+@item set-difference
+@cmindex set-difference
+A wrapper around the function @code{cl-set-difference}.  This command
+can be used for comparing lists of strings.
+
+This command can be loaded as part of the eshell-xtra module, which is
+disabled by default.
+
+@item set-exclusive-or
+@cmindex set-exclusive-or
+A wrapper around the function @code{cl-set-exclusive-or}.  This
+command can be used for comparing lists of strings.
+
+This command can be loaded as part of the eshell-xtra module, which is
+disabled by default.
+
+@item setq
+@cmindex setq
+Set variable values, using the function @code{setq} like a command.
+
+@item source
+@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.
 
 @item su
 @cmindex su
@@ -386,6 +632,48 @@ Built-ins
 to run a command via @command{su} or @command{sudo}.  These commands
 are in the eshell-tramp module, which is disabled by default.
 
+
+@item substitute
+@cmindex substitute
+A wrapper around the function @code{cl-substitute}.  This command can
+be used for comparing lists of strings.
+
+This command can be loaded as part of the eshell-xtra module, which is
+disabled by default.
+
+@item time
+@cmindex time
+Show the time elapsed during a command's execution.
+
+@item umask
+@cmindex umask
+Set or view the default file permissions for newly created files and
+directories.
+
+@item union
+@cmindex union
+A wrapper around the function @code{cl-union}.  This command can be
+used for comparing lists of strings.
+
+This command can be loaded as part of the eshell-xtra module, which is
+disabled by default.
+
+@item unset
+@cmindex unset
+Unset an environment variable.
+
+@item wait
+@cmindex wait
+Wait until a process has successfully completed.
+
+@item which
+@cmindex which
+Identify a command and its location.
+
+@item whoami
+@cmindex whoami
+Print the current user.  This Eshell version of @command{whoami}
+supports Tramp.
 @end table
 
 @subsection Built-in variables
-- 
2.25.1

bug#52289: Update Info documentation of Eshell's built-in commands

[Lars Ingebrigtsen]

ej32u@protonmail.com writes:

> This patch adds the remaining Eshell built-ins to the Eshell Info
> documentation.  It also expands on some of the existing commands and
> mentions user options that affect a command's behavior.

Thanks; applied to Emacs 29 (with some trivial changes -- mostly nil =>
@code{nil}).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no