GNU bug report logs -
#60846
29.0.60; [PATCH] Add more documentation about Eshell command invocation
Previous Next
Reported by: Jim Porter <jporterbugs <at> gmail.com>
Date: Mon, 16 Jan 2023 02:52:01 UTC
Severity: normal
Tags: patch
Found in version 29.0.60
Done: Jim Porter <jporterbugs <at> gmail.com>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 60846 in the body.
You can then email your comments to 60846 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#60846
; Package
emacs
.
(Mon, 16 Jan 2023 02:52:01 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Jim Porter <jporterbugs <at> gmail.com>
:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org
.
(Mon, 16 Jan 2023 02:52:01 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
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.
[0001-Add-more-detail-about-how-to-invoke-Eshell-commands.patch (text/plain, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#60846
; Package
emacs
.
(Mon, 16 Jan 2023 04:02:02 GMT)
Full text and
rfc822 format available.
Message #8 received at 60846 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Oops. Forgot to save the file, so I missed part of my update in the
patch. Fixed here.
[0001-Add-more-detail-about-how-to-invoke-Eshell-commands.patch (text/plain, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#60846
; Package
emacs
.
(Mon, 16 Jan 2023 13:39:02 GMT)
Full text and
rfc822 format available.
Message #11 received at 60846 <at> debbugs.gnu.org (full text, mbox):
> Date: Sun, 15 Jan 2023 18:51:25 -0800
> From: Jim Porter <jporterbugs <at> gmail.com>
>
> 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').
Thanks.
> Since this is purely a documentation change, I'd like to merge this to
> the Emacs 29 branch.
That's fine.
> +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'}}
This should use the @kbd markup, like any command the user should
type. I also suggest to say explicitly that you mean to type this at
the Eshell prompt, as it wasn't clear when I read it.
> +The command can be either an Elisp function or an external command.
> +Eshell looks for the command in the following order:
Here I would add a few useful index entries
@cindex order of looking for commands
@cindex command look up, order
> +@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}.
I'm guessing this swaps the order of the two last candidates, but the
text doesn't say that explicitly for some reason. Just saying
"prefer" is not enough when you have more than 2 candidates.
> +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
Either explain here the meaning of redirecting into a Lisp form, or
add a cross-reference to where it is explained in detail.
> +specify an argument of some other data type, you can use a
> +@ref{Invocation, Lisp form}:
This kind of cross-references is usually a bad idea in Texinfo: it
looks nifty in HTML, but reads awkwardly in all other formats. It is
better to use the slightly wordier alternative:
specify an argument of some other data type, you can use a Lisp form
(@pxref{Invocation}):
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#60846
; Package
emacs
.
(Mon, 16 Jan 2023 20:19:02 GMT)
Full text and
rfc822 format available.
Message #14 received at 60846 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
On 1/16/2023 5:38 AM, Eli Zaretskii wrote:
> Thanks.
Thanks for the useful feedback as always.
>> +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'}}
>
> This should use the @kbd markup, like any command the user should
> type. I also suggest to say explicitly that you mean to type this at
> the Eshell prompt, as it wasn't clear when I read it.
Fixed.
>> +The command can be either an Elisp function or an external command.
>> +Eshell looks for the command in the following order:
>
> Here I would add a few useful index entries
>
> @cindex order of looking for commands
> @cindex command look up, order
Done.
>> +@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}.
>
> I'm guessing this swaps the order of the two last candidates, but the
> text doesn't say that explicitly for some reason. Just saying
> "prefer" is not enough when you have more than 2 candidates.
Good point. I added an extra sentence explicitly stating that the last
two items are swapped in priority.
>> +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
>
> Either explain here the meaning of redirecting into a Lisp form, or
> add a cross-reference to where it is explained in detail.
Done both. I've explained what the command does as well as
cross-referenced the globbing and redirection sections.
>> +specify an argument of some other data type, you can use a
>> +@ref{Invocation, Lisp form}:
>
> This kind of cross-references is usually a bad idea in Texinfo: it
> looks nifty in HTML, but reads awkwardly in all other formats. It is
> better to use the slightly wordier alternative:
>
> specify an argument of some other data type, you can use a Lisp form
> (@pxref{Invocation}):
Ah ha, I didn't realize. Fixed.
[0001-Add-more-detail-about-how-to-invoke-Eshell-commands.patch (text/plain, attachment)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org
:
bug#60846
; Package
emacs
.
(Tue, 17 Jan 2023 13:06:02 GMT)
Full text and
rfc822 format available.
Message #17 received at 60846 <at> debbugs.gnu.org (full text, mbox):
> Date: Mon, 16 Jan 2023 12:18:13 -0800
> Cc: 60846 <at> debbugs.gnu.org
> From: Jim Porter <jporterbugs <at> gmail.com>
>
> On 1/16/2023 5:38 AM, Eli Zaretskii wrote:
> > Thanks.
>
> Thanks for the useful feedback as always.
>
> >> +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'}}
> >
> > This should use the @kbd markup, like any command the user should
> > type. I also suggest to say explicitly that you mean to type this at
> > the Eshell prompt, as it wasn't clear when I read it.
>
> Fixed.
>
> >> +The command can be either an Elisp function or an external command.
> >> +Eshell looks for the command in the following order:
> >
> > Here I would add a few useful index entries
> >
> > @cindex order of looking for commands
> > @cindex command look up, order
>
> Done.
>
> >> +@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}.
> >
> > I'm guessing this swaps the order of the two last candidates, but the
> > text doesn't say that explicitly for some reason. Just saying
> > "prefer" is not enough when you have more than 2 candidates.
>
> Good point. I added an extra sentence explicitly stating that the last
> two items are swapped in priority.
>
> >> +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
> >
> > Either explain here the meaning of redirecting into a Lisp form, or
> > add a cross-reference to where it is explained in detail.
>
> Done both. I've explained what the command does as well as
> cross-referenced the globbing and redirection sections.
>
> >> +specify an argument of some other data type, you can use a
> >> +@ref{Invocation, Lisp form}:
> >
> > This kind of cross-references is usually a bad idea in Texinfo: it
> > looks nifty in HTML, but reads awkwardly in all other formats. It is
> > better to use the slightly wordier alternative:
> >
> > specify an argument of some other data type, you can use a Lisp form
> > (@pxref{Invocation}):
>
> Ah ha, I didn't realize. Fixed.
Thanks, the patch LGTM now.
Reply sent
to
Jim Porter <jporterbugs <at> gmail.com>
:
You have taken responsibility.
(Tue, 17 Jan 2023 22:02:01 GMT)
Full text and
rfc822 format available.
Notification sent
to
Jim Porter <jporterbugs <at> gmail.com>
:
bug acknowledged by developer.
(Tue, 17 Jan 2023 22:02:02 GMT)
Full text and
rfc822 format available.
Message #22 received at 60846-done <at> debbugs.gnu.org (full text, mbox):
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.
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org
.
(Wed, 15 Feb 2023 12:24:08 GMT)
Full text and
rfc822 format available.
This bug report was last modified 1 year and 64 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.