From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Michael Albinus Newsgroups: gmane.emacs.devel Subject: Re: Eshell manual is (hopefully) complete! Date: Thu, 06 Jul 2023 18:56:12 +0200 Message-ID: <87jzvdt1w3.fsf@gmx.de> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="1166"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: emacs-devel@gnu.org To: Jim Porter Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Jul 06 18:57:25 2023 Return-path: Envelope-to: ged-emacs-devel@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 1qHSIH-0000BZ-Jo for ged-emacs-devel@m.gmane-mx.org; Thu, 06 Jul 2023 18:57:25 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qHSHK-0004b8-1F; Thu, 06 Jul 2023 12:56:26 -0400 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 1qHSHE-0004as-76 for emacs-devel@gnu.org; Thu, 06 Jul 2023 12:56:21 -0400 Original-Received: from mout.gmx.net ([212.227.15.19]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qHSHA-0006hD-BZ for emacs-devel@gnu.org; Thu, 06 Jul 2023 12:56:18 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.de; s=s31663417; t=1688662573; x=1689267373; i=michael.albinus@gmx.de; bh=ksaZvqu+zlJrceuOr7ChmLnHx/oIyfsuA3uWkDrwYHI=; h=X-UI-Sender-Class:From:To:Cc:Subject:In-Reply-To:References:Date; b=UK2LeEg5cl+0Eplw2/b4JwPQdJSTGK/G7jvD8UFEe866nPNnMzp8zPjtR5uR6naR4U6Fm4X O4ZF5S1bv4E36tIIKJ5+ipYcMoccjI+wQEEk/YqJKMfKWg7COI1yluN4kcbdZThsbCSDyArAM eoGxnG5IjBa3CXkFisYc07K2mg+ibBaXedJ0lFDYUlg1ceineimY36WqTcO91AYdZo4ioiXw8 gFsGbtM9ViYwMs2yuu102LzySidCcwXT/TGtcJDsIJiKPa2kfNJoBk4ivRL9e3Lc6paalDceh Mj4rT41S4fkpoYoH1kqG2xTPPitqg0ThxGNwOKrdFYGXN7BzB29A== X-UI-Sender-Class: 724b4f7f-cbec-4199-ad4e-598c01a50d3a Original-Received: from gandalf.gmx.de ([185.89.39.13]) by mail.gmx.net (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1M3lc9-1qHB9z3htT-000v03; Thu, 06 Jul 2023 18:56:12 +0200 In-Reply-To: (Jim Porter's message of "Sat, 1 Jul 2023 12:35:36 -0700") X-Provags-ID: V03:K1:CZH8P+xZvgBZNBHhM/EbyXRm237beP5YQQkyCTHLUm+5F+j24Zs woqaL37unJvOWntLfXDs6uSiNgpWQgIQoJ9o3UpMAEewViXuCUOhs/9HxuTv6D4nc77YEtg sZR/gABCgppfMNaSmfpoPAUymn6pdIeECxxHh7VqTRMwSd5i6AqzxQSP4g94cx15mUicQuG fkZVeMHZG0E7El8OIbinw== UI-OutboundReport: notjunk:1;M01:P0:UgGuB69SE/g=;tqV90J+wue+iwzf7GU4roJEauh8 xnL041NzzPfpBf2qdJBKei9WWlkJdDAyU2yUZAkOffmH8kYkYufr2wX9Xb7piyIo1prNU4vgY GZSU1DNGrfnVfuttNoMpMo6tsNnk0LLn+co5djQBlWnArlxzaHhtim7WyGI+scM1niVtn7lFE tY7q1YqBbUnCpZC3/Sios358on3eLQNwmVy61qTD1dYT6eLTXUnTxC9uQJYZy884+UwDOOqTg XFuOaL2zBnSIYyu/i4bKv9qoIemw0QAi9KQeOgvBKWv1iYSpVHIOoDua48lmh6p1KIhRF9nuU wUNynVjsrjpSz6hdZfOZmdN67sEneL2rB/tBzoD3vSBlBvK6G3ylgT6iOcOeIG9ZAXnkCZfhN QsuuDAkWoafRImzBhGCIJTCq11Wb8uxO25TcQV7XLeFPuxycOreW3ZhVs01R5HDNGoHYZ2wae Jx9aonRuInV4X81QvtEVfaBe7Znj/JNfijf1r5mvuf5/fdINSJBHmafNL+Lu6X43QaMCfRS05 jKUcsYPQlEyZXCSLvQJNKiJbgCVHmd2871+ot90IyGlOQG/SrepmT8SY193aDha8+ESirCBWm X5BBAb18z+/YPuRCU7s0dngWMo70cNmJHi99mgUeh4EOjpu0fA3Q5GNMtvotbVkUqIoerU+LI 8Xal1cc62eEN1Iw+cswOS5Cp/yiLEHSkt7k14R710x/OojpzYnUHXIy89sISc1vBu/C8yi26f HnbqwqhEpr2bVb3Ctvt0npjQgZ4h/b87pTlQMQrenKSRtq8uuM2MLlOIUITAY6Cxpk+VCuoj Received-SPF: pass client-ip=212.227.15.19; envelope-from=michael.albinus@gmx.de; helo=mout.gmx.net X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:307522 Archived-At: Jim Porter writes: Hi Jim, > I've just merged to master (75278855f4a) some additions to the Eshell > manual to try and fill in the last of the missing > documentation. Hopefully I haven't missed anything. > > To that end, could people take a quick look over the latest version of > the Eshell manual to make sure it seems reasonably complete? There's a > lot more detail to various sections since Emacs 28, and a fair bit > since 29 too. I've spent quite a while looking at the manual though, > so it would be helpful to have some fresh eyes take a look as well. > > If anyone finds any major gaps, I'll try to get that fixed (or to help > get patches merged if you'd like to write the documentation yourself). I gave it a full proof-reading (based on 14e57b8f4cf). Here my comments: - Top page "(*note Emacs Lisp Interaction: (emacs)Lisp Interaction.)" Shouldn't the period be at the end of the phrase? - Top page: "This manual is for Eshell, the Emacs shell." eshell.el speaks about version 2.4.2, shouldn't this be mentioned here? And more general, is this a proper version today? Somewhere else in the manual we find "Eshell version 2.4.2, which is the version included with Emacs 22." - Top page: --8<---------------cut here---------------start------------->8--- * Introduction:: A brief introduction to the Emacs Shell. * Commands:: * Expansion:: * Input/Output:: * Extension modules:: * Bugs and ideas:: Known problems, and future ideas. * GNU Free Documentation License:: The license for this documentation. * Concept Index:: * Function and Variable Index:: * Command Index:: --8<---------------cut here---------------end--------------->8--- Shouldn't all entries have a description? The same for all other menus (I don't mention it, again). - 1 Introduction Menu is doubled. It misses node "What is Eshell?" - 1.2 Contributors to Eshell I miss at least your name, and Amin Bandali. - 2.2 Arguments "(*note Eshell commands: Built-ins.)" The period looks superfluous. - 2.2.1 Quoting and escaping =E2=80=98"The answer is: \"$answer\""=E2=80=99 Shouldn't it be =E2=80=98"The answer is: \"$ANSWER\""=E2=80=99 - 2.3 Built-in commands I suppose built-in commands are the functions `eshell/*', perhaps you could mention this. Comparing this list, and the built-in commands in "5.1.4 Tramp extensions" and "5.1.5 Extra built-in commands", I miss the built-in commands eshell/count, eshell/define, eshell/eshell-debug, eshell/ff, eshell/gf, eshell/urgrep. =E2=80=98kill=E2=80=99 As I understand, it kills local processes. Since signal-process supports also remote processes: WIBNI eshell does it as well? (This comment is not part of the review, just being curious) - 2.4.1 Built-in variables You offer $UID, but not $GID. Why? =E2=80=98$INSIDE_EMACS=E2=80=99 This variable indicates to external commands that they are being invoked from within Emacs so they can adjust their behavior if necessary. Its value is =E2=80=98EMACS-VERSION,eshell=E2=80=99. For remote processes, the value is 'EMACS-VERSION,eshell,tramp:TRAMP-VERS= ION'. Or even longer, f.e. if there is a compilation process. So you should say "The value starts with '...'". - 2.5 Aliases "an alias=E2=80=99s arguments" =3D> "an alias=E2=80=99s argument" - 2.7 Completion "lisp forms" =3D> "Lisp forms" (2 times) - 2.8 Control Flow "lisp forms" =3D> "Lisp forms" - 3.1 Dollars Expansion =E2=80=98$=E2=80=99 As with =E2=80=98${COMMAND}=E2=80=99, evaluates the Eshell command inv= ocation =E2=80=98COMMAND=E2=80=99, but writes the output to a temporary file a= nd returns the file name. I'm curious: is it always a *local* temporary file, or can the temporary file being located on a remote system, if $ is executed there? "(*note Sequences: (elisp)Sequences Arrays Vectors.)." There seems to be a superfluous period. - 3.2 Globbing Customize group =E2=80=9Ceshell-glob=E2=80=9D =3D> Customize group 'eshel= l-glob' - 3.3 Argument Predication and Modification Customize group =E2=80=9Ceshell-pred=E2=80=9D =3D> Customize group 'eshel= l-pred' - 4.2 Redirection =E2=80=98>>> BUFFER=E2=80=99 =E2=80=98FD>>> BUFFER=E2=80=99 I would still say DEST instead of BUFFER. =E2=80=98&> FILE=E2=80=99 =E2=80=98>& FILE=E2=80=99 =E2=80=98&>> FILE=E2=80=99 =E2=80=98>>& FILE=E2=80=99 =E2=80=98&>>> FILE=E2=80=99 =E2=80=98>>>& FILE=E2=80=99 I would still say DEST instead of FILE. - 5.1 Optional modules "In addition to the various modules enabled by default (documented above)" I haven't seen any module description "above". That is, the following modules aren't mentioned anywhere in the manual: eshell-alias, eshell-banner, eshell-basic, eshell-cmpl, eshell-dirs, eshell-extpipe, eshell-glob, eshell-hist, eshell-ls, eshell-pred, eshell-prompt, eshell-script, eshell-term, eshell-unix. All of them can be deselected via user option eshell-modules-list, which looks to me like they are optional. Of course, some of them aren't optional. So it might be needed to explain this user option, and to explain what shall be selected or deselected. Which modules are mandatory, and which are optional. - 6 Bugs and ideas "Once symbolic mode is supported for =E2=80=98umask=E2=80=99, implement = =E2=80=98chmod=E2=80=99 in Lisp" "man umask" tells me umask [-p] [-S] [mode] The user file-creation mask is set to mode. If mode begins with a digit, it is interpreted as an octal number; otherwise it is interpreted as a symbolic mode mask similar to that accepted by chmod(1). ... "Write an =E2=80=98info=E2=80=99 alias that can take arguments So that the user can enter =E2=80=98info chmod=E2=80=99, for example." This seems to be implemented. "Write a =E2=80=98tail=E2=80=99 command which uses =E2=80=98view-file=E2= =80=99 It would move point to the end of the buffer, and then turns on auto-revert mode in that buffer at frequent intervals=E2=80=94and a =E2= =80=98head=E2=80=99 alias which assumes an upper limit of =E2=80=98eshell-maximum-line-leng= th=E2=80=99 characters per line. Perhaps auto-revert-tail-mode is better suited? Finally, since you are the de-facto maintainer of eshell, you might consider to add yourself to admin/MAINTAINERS. > - Jim Best regards, Michael.