Subject: bug#71987: closed (Re: bug#71987: 30.0.60; [PATCH] Document Eshell entry points)

From: [email-masked] (GNU bug Tracking System)
Date: Tue, 09 Jul 2024 17:07:02 +0000

Your bug report

#71987: 30.0.60; [PATCH] Document Eshell entry points

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

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

Subject: Re: bug#71987: 30.0.60; [PATCH] Document Eshell entry points
From: Jim Porter <[email-masked]>
To: Eli Zaretskii <[email-masked]>
Cc: [email-masked]
Date: Tue, 9 Jul 2024 10:05:21 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

On 7/9/2024 4:33 AM, Eli Zaretskii wrote:
> LGTM, thanks.

Thanks. Pushed to the release branch as 37475c9af7a. Closing this bug now.

Subject: 30.0.60; [PATCH] Document Eshell entry points
From: Jim Porter <[email-masked]>
To: [email-masked]
Date: Sun, 7 Jul 2024 21:29:22 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

Recently, I noticed a fairly important thing missing from the Eshell 
manual: it never actually tells users how to *start* Eshell! As there 
are several ways, I think it would be useful to describe all of them. 
Patch attached (intended for Emacs 30).

From abc4eafa179a5a258a0f2ac2ef683b59b3d451b2 Mon Sep 17 00:00:00 2001
From: Jim Porter <[email-masked]>
Date: Sun, 7 Jul 2024 21:24:47 -0700
Subject: [PATCH] Document Eshell entry points

* doc/misc/eshell.texi (Entry Points): New chapter.
(Scripts): Move under Entry Points.  Expand documentation.
---
 doc/misc/eshell.texi | 131 ++++++++++++++++++++++++++++++++++---------
 1 file changed, 103 insertions(+), 28 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 69f94fab469..212253babe6 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -76,6 +76,7 @@ Top
 
 @menu
 * Introduction::             A brief introduction to the Emacs Shell.
+* Entry Points::
 * Commands::
 * Expansion::
 * Input/Output::
@@ -186,6 +187,108 @@ Contributors to Eshell
 requests, bug reports and encouragement.  Thanks a lot!  Without you
 there would be no new releases of Eshell.
 
+@node Entry Points
+@chapter Entry Points
+
+Eshell provides several different ways to start it, depending on the
+situation.
+
+@menu
+* Interactive Shell::
+* One-Off Commands::
+* Scripts::
+@end menu
+
+@node Interactive Shell
+@section Interactive Shell
+
+The most common way to use Eshell is via an interactive shell.  You can
+start this via the @code{eshell} command:
+
+@deffn Command eshell &optional arg
+Start a new interactive Eshell session, or switch to an already active
+session.  The exact behavior depends on the value of @var{arg}
+(interactively, the prefix argument):
+
+@table @asis
+
+@item @code{nil}
+Start or switch to the default Eshell session.
+
+@item a number
+Start or switch to the Eshell session with the specified number (e.g.@:
+@samp{*eshell*<2>}).
+
+@item anything else
+Start a new Eshell session, no matter if another one already exists.
+
+@end table
+@end deffn
+
+@node One-Off Commands
+@section One-Off Commands
+
+You can also run individual Eshell commands from anywhere within Emacs:
+
+@deffn Command eshell-command command &optional to-current-buffer
+Execute the Eshell command string @var{command} and show the output in a
+buffer.  If @var{to-current-buffer} is non-@code{nil} (interactively,
+with the prefix argument), then insert output into the current buffer at
+point.
+
+When the command ends with @kbd{&}, Eshell will evaluate the command
+asynchronously.  Otherwise, it will wait until the command has finished
+execution.
+@end deffn
+
+@defun eshell-command-result command &optional status-var
+Execute the Eshell command string @var{command} and return the result,
+like using the variable @code{$$} in an interactive session
+(@pxref{Variables}).  If @var{status-var} is a symbol, this function
+will set it to the exit status of the command (like using the variable
+@code{$?} in an interactive session).
+@end defun
+
+@node Scripts
+@section Scripts
+@cmindex source
+@cmindex .
+Like other shells, you can create Eshell @dfn{scripts}.  An Eshell
+script is simply a file containing a sequence of commands that will be
+executed as though you entered them one at a time in an interactive
+Eshell session.  You can invoke these scripts from within Eshell with
+@command{source}, which will run the script in a subshell.  If you wish
+to run a script in your @emph{current} Eshell environment, use the
+@code{.} command instead.
+
+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{$*}.
+
+You can also invoke Eshell scripts from outside of Eshell:
+
+@defun eshell-execute-file file &optional args destination
+Execute the Eshell commands contained in @var{file}, passing an optional
+list of @var{args} to the script.  If @var{destination} is @code{t},
+write the command output to the current buffer.  If @code{nil}, don't
+write the output anywhere.  For any other value, output to the
+corresponding Eshell target (@pxref{Redirection}).
+@end defun
+
+@defun eshell-batch-file
+This function lets you make an Eshell script file executable from
+outside of Emacs by adding it to the script's interpreter directive like
+this:
+
+@example
+#!/usr/bin/env -S emacs --batch -f eshell-batch-file
+@end example
+
+As with other ways of invoking Eshell scripts, you can pass extra
+arguments to the script on the command line.
+@end defun
+
 @node Commands
 @chapter Commands
 
@@ -208,7 +311,6 @@ Commands
 * Aliases::
 * Remote Access::
 * Control Flow::
-* Scripts::
 @end menu
 
 @node Invocation
@@ -1594,33 +1696,6 @@ Control Flow
 
 @end table
 
-@node Scripts
-@section Scripts
-@cmindex source
-@fnindex eshell-execute-file
-@fnindex eshell-batch-file
-You can run Eshell scripts much like scripts for other shells; the main
-difference is that since Eshell is not a system command, you have to run
-it from within Emacs.  An Eshell script is simply a file containing a
-sequence of commands, as with almost any other shell script.  You can
-invoke scripts from within Eshell with @command{source}, or from
-anywhere in Emacs with @code{eshell-execute-file}.  Additionally, you
-can make an Eshell script file executable by calling
-@code{eshell-batch-file} in the interpreter directive:
-
-@example
-#!/usr/bin/env -S emacs --batch -f eshell-batch-file
-@end example
-
-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.
-
 @node Expansion
 @chapter Expansion
 Expansion in a command shell is somewhat like macro expansion in macro
-- 
2.25.1