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

[Jim Porter]

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
Description: Text document