Re: Eshell manual is (hopefully) complete!

[Michael Albinus]

Jim Porter <jporterbugs@gmail.com> 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 ‘"The answer is: \"$answer\""’
  Shouldn't it be ‘"The answer is: \"$ANSWER\""’

- 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.

  ‘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)

- 2.4.1 Built-in variables
  You offer $UID, but not $GID. Why?

  ‘$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 '...'".

- 2.5 Aliases
  "an alias’s arguments" => "an alias’s argument"

- 2.7 Completion
  "lisp forms" => "Lisp forms" (2 times)

- 2.8 Control Flow
  "lisp forms" => "Lisp forms"

- 3.1 Dollars Expansion

  ‘$<COMMAND>’
     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 $<COMMAND> is
  executed there?

  "(*note Sequences: (elisp)Sequences Arrays Vectors.)."
  There seems to be a superfluous period.

- 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'

- 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.

- 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 ‘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). ...

  "Write an ‘info’ alias that can take arguments
    So that the user can enter ‘info chmod’, for example."

  This seems to be implemented.

  "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?

Finally, since you are the de-facto maintainer of eshell, you might
consider to add yourself to admin/MAINTAINERS.

> - Jim

Best regards, Michael.