From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#60846: 29.0.60; [PATCH] Add more documentation about Eshell command invocation Date: Mon, 16 Jan 2023 15:38:15 +0200 Message-ID: <83wn5m4n20.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="40106"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 60846@debbugs.gnu.org To: Jim Porter Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Jan 16 14:39:08 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1pHPhc-000AIe-4N for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 16 Jan 2023 14:39:08 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pHPhY-0003LG-9k; Mon, 16 Jan 2023 08:39:04 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHPhW-0003KM-Ly for bug-gnu-emacs@gnu.org; Mon, 16 Jan 2023 08:39:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pHPhW-0002yo-Dq for bug-gnu-emacs@gnu.org; Mon, 16 Jan 2023 08:39:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pHPhW-0002RP-9s for bug-gnu-emacs@gnu.org; Mon, 16 Jan 2023 08:39:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 16 Jan 2023 13:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 60846 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 60846-submit@debbugs.gnu.org id=B60846.16738762979307 (code B ref 60846); Mon, 16 Jan 2023 13:39:02 +0000 Original-Received: (at 60846) by debbugs.gnu.org; 16 Jan 2023 13:38:17 +0000 Original-Received: from localhost ([127.0.0.1]:60819 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHPgn-0002Q3-Bn for submit@debbugs.gnu.org; Mon, 16 Jan 2023 08:38:17 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:48710) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pHPgl-0002Pr-Ij for 60846@debbugs.gnu.org; Mon, 16 Jan 2023 08:38:16 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHPgg-0002op-1S; Mon, 16 Jan 2023 08:38:10 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=EuwMkAUee5M7oxPKl3plEzx2O7IL0yVKuKlcoij/hH8=; b=n820A2VCsLC/ uwkYNkSsh9O6Pd3nTaHQ2yzD/ptsn6JOAzLKIZ6AbmAatvmRBYc7eQqSFngeehQXwnrm1b+rLbquK 3ywGLRrTWFp90oc3u2dYpVi+0nUi7RvrX4Z5iAqD9mLXzBKfbt3ILL6kOfGyw9jTepmRTBaHRqTLs ssU9riaxbfOWsvX7LKCWeZ7gjPvW5AH7+9eSsTplMtPF9mqbaEhNy/pxMMzZwHD8YfXm6woLUVqpy QrPFh2Y2GTd+Y0Kg/Ekr3wt0XfxXxj3u/cR8AgLyr6XFDVcFI0nRxuQnw3LcuKu1NHrMPGWj0006g /MsNp225Ft+1cihViyOupw==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHPge-00013y-Jx; Mon, 16 Jan 2023 08:38:09 -0500 In-Reply-To: (message from Jim Porter on Sun, 15 Jan 2023 18:51:25 -0800) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:253488 Archived-At: > Date: Sun, 15 Jan 2023 18:51:25 -0800 > From: Jim Porter > > 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}):