Subject: bug#60846: closed (Re: bug#60846: 29.0.60; [PATCH] Add more documentation about Eshell command invocation)

From: [email-masked] (GNU bug Tracking System)
Date: Tue, 17 Jan 2023 22:02:02 +0000

Your bug report

#60846: 29.0.60; [PATCH] Add more documentation about Eshell command invocation

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

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

Subject: Re: bug#60846: 29.0.60; [PATCH] Add more documentation about Eshell command invocation
From: Jim Porter <[email-masked]>
To: Eli Zaretskii <[email-masked]>
Cc: [email-masked]
Date: Tue, 17 Jan 2023 14:01:27 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

On 1/17/2023 5:05 AM, Eli Zaretskii wrote:
> Thanks, the patch LGTM now.

Thanks. I merged this to the Emacs 29 branch as c4f0b6ccea. Closing this 
bug now.

Subject: 29.0.60; [PATCH] Add more documentation about Eshell command invocation
From: Jim Porter <[email-masked]>
To: [email-masked]
Date: Sun, 15 Jan 2023 18:51:25 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

The Eshell manual isn't as thorough as it could be about how users 
should invoke commands. While there's a reasonable amount of 
documentation about the details, it never directly describes how to run 
a simple command.

Attached is a patch to remedy this. I also corrected the documentation 
about how Eshell picks what command to run in command form; previously, 
it stated that ordinary Lisp functions had higher priority than external 
commands, which isn't actually the case (unless you set 
'eshell-prefer-lisp-functions').

Since this is purely a documentation change, I'd like to merge this to 
the Emacs 29 branch.

From d0e4b94623b5840a212c97c75b1641dbbbff77ea Mon Sep 17 00:00:00 2001
From: Jim Porter <[email-masked]>
Date: Sun, 15 Jan 2023 18:35:31 -0800
Subject: [PATCH] Add more detail about how to invoke Eshell commands

* doc/misc/eshell.texi (Commands): Move explanation about kernel
functions to here.
(Invocation): Describe command form and Lisp form.  Fix documentation
about priority of commands in command form.
---
 doc/misc/eshell.texi | 93 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 70 insertions(+), 23 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index fc7d52eb711..b5444741b66 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -193,6 +193,12 @@ Commands
 chapter covers command invocations in Eshell, including the command
 history and invoking commands in a script file.
 
+Unlike regular system shells, Eshell never invokes kernel functions
+directly, such as @code{exec(3)}.  Instead, it uses the Lisp functions
+available in the Emacs Lisp library.  It does this by transforming the
+input line into a callable Lisp form.@footnote{To see the Lisp form
+that will be invoked, type: @samp{eshell-parse-command 'echo hello'}}
+
 @menu
 * Invocation::
 * Arguments::
@@ -207,23 +213,16 @@ Commands
 
 @node Invocation
 @section Invocation
-Unlike regular system shells, Eshell never invokes kernel functions
-directly, such as @code{exec(3)}.  Instead, it uses the Lisp functions
-available in the Emacs Lisp library.  It does this by transforming the
-input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}}
+Eshell is both a command shell and an Emacs Lisp @acronym{REPL}.  As a
+result, you can invoke commands in two different ways: in @dfn{command
+form} or in @dfn{lisp form}.
 
-The command can be either an Elisp function or an external command.
-Eshell looks first for an alias (@pxref{Aliases}) with the same name as the
-command, then a built-in (@pxref{Built-ins}) or a function with the
-same name; if there is no match, it then tries to execute it as an
-external command.
-
-The semicolon (@code{;}) can be used to separate multiple command
-invocations on a single line.  You can also separate commands with
-@code{&&} or @code{||}. When using @code{&&}, Eshell will execute the
-second command only if the first succeeds (i.e.@: has an exit
-status of 0); with @code{||}, Eshell will execute the second command
-only if the first fails.
+You can use the semicolon (@code{;}) to separate multiple command
+invocations on a single line, executing each in turn.  You can also
+separate commands with @code{&&} or @code{||}. When using @code{&&},
+Eshell will execute the second command only if the first succeeds
+(i.e.@: has an exit status of 0); with @code{||}, Eshell will execute
+the second command only if the first fails.
 
 A command invocation followed by an ampersand (@code{&}) will be run
 in the background.  Eshell has no job control, so you can not suspend
@@ -232,12 +231,64 @@ Invocation
 can be controlled the same way as any other background process in
 Emacs.
 
+@subsection Command form
+Command form looks much the same as in other shells.  A command
+consists of arguments separated by spaces; the first argument is the
+command to run, with any subsequent arguments being passed to that
+command.
+
+@example
+~ $ echo hello
+hello
+@end example
+
+The command can be either an Elisp function or an external command.
+Eshell looks for the command in the following order:
+
+@enumerate
+@item
+As a command alias (@pxref{Aliases})
+
+@item
+As a built-in command (@pxref{Built-ins})
+
+@item
+As an external program
+
+@item
+As an ordinary Lisp function
+@end enumerate
+
+@vindex eshell-prefer-lisp-functions
+If you would prefer to use ordinary Lisp functions over external
+programs, set the option @code{eshell-prefer-lisp-functions} to
+@code{t}.
+
+@subsection Lisp form
+Lisp form looks like ordinary Emacs Lisp code, because that's what it
+is.  As a result, you can use any syntax normally available to an
+Emacs Lisp program (@pxref{Top, , , elisp, The Emacs Lisp Reference
+Manual}).
+
+@example
+~ $ (format "hello, %s" user-login-name)
+hello, user
+@end example
+
+In addition, you can @emph{combine} command forms and Lisp forms
+together into single statements, letting you use whatever form is the
+most convenient for expressing your intentions.
+
+@example
+~ $ ls *.patch > (format-time-string "%F.log")
+@end example
+
 @node Arguments
 @section Arguments
-Ordinarily, command arguments are parsed by Eshell as either strings
+Ordinarily, Eshell parses arguments in command form as either strings
 or numbers, depending on what the parser thinks they look like.  To
-specify an argument of some other data type, you can use an
-@ref{Dollars Expansion, Elisp expression}:
+specify an argument of some other data type, you can use a
+@ref{Invocation, Lisp form}:
 
 @example
 ~ $ echo (list 1 2 3)
@@ -354,10 +405,6 @@ Built-ins
 sudo is an alias, defined as "*sudo $@@*"
 @end example
 
-@vindex eshell-prefer-lisp-functions
-If you would prefer to use the built-in commands instead of the external
-commands, set @code{eshell-prefer-lisp-functions} to @code{t}.
-
 Some of the built-in commands have different behavior from their
 external counterparts, and some have no external counterpart.  Most of
 these will print a usage message when given the @code{--help} option.
-- 
2.25.1