GNU bug report logs - #60846
29.0.60; [PATCH] Add more documentation about Eshell command invocation

Previous Next

Full log

Message #14 received at 60846 <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 60846 <at> debbugs.gnu.org
Subject: Re: bug#60846: 29.0.60; [PATCH] Add more documentation about Eshell
 command invocation
Date: Mon, 16 Jan 2023 12:18:13 -0800

[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)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.