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

[Eli Zaretskii]

> Date: Mon, 16 Jan 2023 12:18:13 -0800
> Cc: 60846@debbugs.gnu.org
> From: Jim Porter <jporterbugs@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.