From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Jim Porter Newsgroups: gmane.emacs.devel Subject: Re: Eshell manual is (hopefully) complete! Date: Fri, 7 Jul 2023 22:57:35 -0700 Message-ID: <044aa267-89dd-d02d-3b05-a31d619e1eb9@gmail.com> References: <87jzvdt1w3.fsf@gmx.de> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15588"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Michael Albinus Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jul 08 07:58:20 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 1qI0xY-0003xP-Ms for ged-emacs-devel@m.gmane-mx.org; Sat, 08 Jul 2023 07:58:20 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qI0wy-0006v0-Gk; Sat, 08 Jul 2023 01:57:44 -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 1qI0wx-0006ub-9b for emacs-devel@gnu.org; Sat, 08 Jul 2023 01:57:43 -0400 Original-Received: from mail-pg1-x52d.google.com ([2607:f8b0:4864:20::52d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qI0wv-0007Ro-97 for emacs-devel@gnu.org; Sat, 08 Jul 2023 01:57:43 -0400 Original-Received: by mail-pg1-x52d.google.com with SMTP id 41be03b00d2f7-55b1238a024so2052798a12.0 for ; Fri, 07 Jul 2023 22:57:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1688795859; x=1691387859; h=content-transfer-encoding:in-reply-to:from:content-language :references:cc:to:subject:mime-version:date:message-id:from:to:cc :subject:date:message-id:reply-to; bh=bzwaR/A+YX79f50mcF2y7qWhc841Z/aVvcIVch1BjNA=; b=FUHTwp6NHX+LnBQ3Rn8Fm4BfDS64lYRAJLGvZYMMiDDTLijGRwNSWic41wqT8CkXzM rbpJADneSVEeDxGI49kqUqnGBBoB1NCn/1VhEO/xIYiAL9VQg7Icek/pgFD7W5W48mKr ZelDTw2DmTrp0WTPaDXGnFMJJl10aVm21vS5n2R2gzCqNk8CsPv/GFNaRCib1e5xXiPY ccJMVwXapoU2ldgsgO8a3lIO14UWutXHFHWfY1Deuur7j/gb+ucspZH4c3xutxqDy6th aMZZMemRjRJqHDeFEfSUg7spnKHyNkZjh2s+NXUn/t0cGo3S2ESqvwIhxl55IZOnqCe7 vfkQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1688795859; x=1691387859; h=content-transfer-encoding:in-reply-to:from:content-language :references:cc:to:subject:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=bzwaR/A+YX79f50mcF2y7qWhc841Z/aVvcIVch1BjNA=; b=Nt9j5EyL0BVh+VbtFNbVh+8DWZ+23GWE5raM5QQujPBAqtve/KkJrFb1y7wMIsY7YX a4SQFm4E3mhjLqaayJ+ArCuShFc9Tw2hLMVdF3aFpV5GnwWcaPAVr1o2LTHkqK7R8kOG 03F6TiRw/7vriMEK/AahXbpaw1dz3fhqiVOEFm8IVr3ZoYaICxMkzSkI2GwW8D9Zr7jS FktD2sQWKu4WJ3ykJ7LmcY62Fkma995Upd1xVDRrh/8bslHZ2QiplHShcYF7C7T6UrLL RAqkFJ7XxnfNsG4l9VGfHS7VeOE71iOvuQy6wBK5rGNak8DJOpTxELn6KyWaIK2pPDPK nnSQ== X-Gm-Message-State: ABy/qLbmYYQ9rxIN2tY8a0aXjrmZX5MsaVUbXk4Qurt35s1d3yUfXI3+ nGRJA3P64w0T4Q8sXjGcI+A= X-Google-Smtp-Source: APBJJlFtgrunUsEbfos4mXXD/gZcVIxdViX72DhspSwlQupMYA/dEZCjegULObO0VnK7IqfbA2gZ9Q== X-Received: by 2002:a05:6a20:3257:b0:120:1baf:e56e with SMTP id hm23-20020a056a20325700b001201bafe56emr7131050pzc.19.1688795859050; Fri, 07 Jul 2023 22:57:39 -0700 (PDT) Original-Received: from [192.168.1.2] (cpe-76-168-148-233.socal.res.rr.com. [76.168.148.233]) by smtp.googlemail.com with ESMTPSA id m30-20020a637d5e000000b0054fe07d2f3dsm3685014pgn.11.2023.07.07.22.57.38 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 07 Jul 2023 22:57:38 -0700 (PDT) Content-Language: en-US In-Reply-To: <87jzvdt1w3.fsf@gmx.de> Received-SPF: pass client-ip=2607:f8b0:4864:20::52d; envelope-from=jporterbugs@gmail.com; helo=mail-pg1-x52d.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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_NONE=-0.0001, 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:307594 Archived-At: On 7/6/2023 9:56 AM, Michael Albinus wrote: > I gave it a full proof-reading (based on 14e57b8f4cf). Here my comments: Thanks for the thorough review. Responses inline below. > - Top page "(*note Emacs Lisp Interaction: (emacs)Lisp Interaction.)" > Shouldn't the period be at the end of the phrase? Fixed. > - 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." I'll have to think about that. It might make sense to bump Eshell's version to 3.0.0 for Emacs 29 (there are quite a few changes), and then maybe 3.1.0 for Emacs 30 (where there are not so many changes - at least not yet). I'm open to ideas though. > - 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). Possibly. I'm not sure what the standard is, but it would probably be ok to add descriptions for everything. > - 1 Introduction > Menu is doubled. It misses node "What is Eshell?" This might take a bit of reorganizing. Maybe someone else knows the right way to arrange Texinfo sections here? Otherwise, I can look into it later. > - 1.2 Contributors to Eshell > I miss at least your name, and Amin Bandali. I'll start a separate thread to see if any past Eshell contributors whose names aren't on the list would like to be added. > - 2.2 Arguments "(*note Eshell commands: Built-ins.)" > The period looks superfluous. Fixed. > - 2.2.1 Quoting and escaping ‘"The answer is: \"$answer\""’ > Shouldn't it be ‘"The answer is: \"$ANSWER\""’ Well, that depends. Eshell variables can be Lisp variables or environment variables, so in the former case, "$answer" would make sense, I think. > - 2.3 Built-in commands > I suppose built-in commands are the functions `eshell/*', perhaps you > could mention this. That's actually mentioned farther down, in the "Defining new built-in commands" section, but it probably makes sense to mention it here too. Fixed. > 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. I added documentation for 'count', 'eshell-debug', 'ff', and 'gf'. 'define' is obsolete (I'm not sure it ever worked, and maybe I should have just removed it entirely). 'urgrep' is from the Urgrep package on GNU ELPA (which I wrote :)). > ‘kill’ > 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) I'll have to look into this. Improving Tramp support in Eshell is definitely on my list of things to do. > - 2.4.1 Built-in variables > You offer $UID, but not $GID. Why? Oops. I actually thought I had done that already (see bug#63221), but evidently I forgot to add a special built-in variable for it. I'll file a separate bug for this. > ‘$INSIDE_EMACS’ > 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 ‘EMACS-VERSION,eshell’. > > For remote processes, the value is 'EMACS-VERSION,eshell,tramp:TRAMP-VERSION'. > Or even longer, f.e. if there is a compilation process. So you should say > "The value starts with '...'". Fixed. > - 2.5 Aliases > "an alias’s arguments" => "an alias’s argument" I think the current text is correct, actually. There's one alias in the example, but it has several arguments. > - 2.7 Completion > "lisp forms" => "Lisp forms" (2 times) > > - 2.8 Control Flow > "lisp forms" => "Lisp forms" Fixed. > - 3.1 Dollars Expansion > > ‘$’ > As with ‘${COMMAND}’, evaluates the Eshell command invocation > ‘COMMAND’, but writes the output to a temporary file and 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? Hmm, I'm not sure. Looking at the code, I *think* it's always local, but I'll have to test it out. > "(*note Sequences: (elisp)Sequences Arrays Vectors.)." > There seems to be a superfluous period. Fixed. > - 3.2 Globbing > Customize group “eshell-glob” => Customize group 'eshell-glob' > > - 3.3 Argument Predication and Modification > Customize group “eshell-pred” => Customize group 'eshell-pred' Fixed. > - 4.2 Redirection > ‘>>> BUFFER’ > ‘FD>>> BUFFER’ > I would still say DEST instead of BUFFER. > > ‘&> FILE’ > ‘>& FILE’ > ‘&>> FILE’ > ‘>>& FILE’ > ‘&>>> FILE’ > ‘>>>& FILE’ > I would still say DEST instead of FILE. Fixed. > - 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. All the modules *should* be optional (although there are several that I can't imagine a user disabling, like 'eshell-dirs'). I'll have to think about how to document this more clearly... > - 6 Bugs and ideas > "Once symbolic mode is supported for ‘umask’, implement ‘chmod’ 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). ... There's a built-in version of umask ('eshell/umask'), but it doesn't support symbolic mode yet. I actually have a patch in progress for this... > "Write an ‘info’ alias that can take arguments > So that the user can enter ‘info chmod’, for example." > > This seems to be implemented. Looks like it. Fixed. > "Write a ‘tail’ command which uses ‘view-file’ > It would move point to the end of the buffer, and then turns on > auto-revert mode in that buffer at frequent intervals—and a ‘head’ > alias which assumes an upper limit of ‘eshell-maximum-line-length’ > characters per line. > > Perhaps auto-revert-tail-mode is better suited? Perhaps. I'll look into that and how it would work exactly.