GNU bug report logs - #68838
30.0.50; [PATCH] Document Eshell built-in commands' arguments in the manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 68838 in the body.
You can then email your comments to 68838 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 30.0.50; [PATCH] Document Eshell built-in commands' arguments in the
 manual
Date: Tue, 30 Jan 2024 21:49:39 -0800

[Message part 1 (text/plain, inline)]

Eshell's manual documents all its built-in commands, but the 
documentation is too brief in my opinion. It should document the 
command-line options. Here's a patch to do so.

(Later, I'd like to break this giant list into subsections, but I'll 
wait on that since any changes to *this* patch would likely cause all 
sorts of headaches with a reorganization patch.)

[0001-Document-arguments-to-Eshell-s-built-in-commands.patch (text/plain, attachment)]

Message #8 received at 68838 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jim Porter <jporterbugs <at> gmail.com>
Cc: 68838 <at> debbugs.gnu.org
Subject: Re: bug#68838: 30.0.50;
 [PATCH] Document Eshell built-in commands' arguments in the manual
Date: Wed, 31 Jan 2024 21:25:16 +0200

> Date: Tue, 30 Jan 2024 21:49:39 -0800
> From: Jim Porter <jporterbugs <at> gmail.com>
> 
> Eshell's manual documents all its built-in commands, but the 
> documentation is too brief in my opinion. It should document the 
> command-line options. Here's a patch to do so.

Thanks.  Some comments below.

>  @item addpath
> +@itemx addpath [-b] @var{directory}@dots{}
>  @cmindex addpath
> -Adds a given path or set of paths to the PATH environment variable, or,
> -with no arguments, prints the current paths in this variable.
> +Adds the directory (or list of directories) @var{directory} to the
> +@code{$PATH} environment variable.  By default, this adds the
> +directories to the end of @code{$PATH}; by passing @code{-b} or
> +@code{--begin}, Eshell will instead add the directories to the
> +beginning.

This could benefit from explaining how to specify a list of
directories.

> +@item cat @var{file}@dots{}
>  @cmindex cat
> -Concatenate file contents into standard output.  If in a pipeline, or
> -if the file is not a regular file, directory, or symlink, then this
> -command reverts to the system's definition of @command{cat}.
> +Concatenate the contents of @var{files} to standard output.  If in a
                               ^^^^^^^^^^^
@var{file}s, since the argument is @var{file}.

> +@item cd @var{directory}
> +Change to the directory @var{directory}.

It is better to use

  Change to the specified @var{directory}.

so as to avoid repeating the same word twice.

> +@item cd =@var{regex}
> +Search the directory ring for a directory matching the regular
> +expression @var{regexp} and change to that directory.
                   ^^^^^^
Typo.

> -@item info
> +@item @code{-r}, @code{--read}
> +Read history items from the history file and append it to the current
> +shell's history.                             ^^^^^^^^^

"append them"

> +@item printnl [@var{arg}]@dots{}
>  @cmindex printnl
> -Print the arguments separated by newlines.
> +Print each argument separated by newlines.

"Print all the @var{arg}s separated by newlines."

> -@item rm
> +@item rm [@var{option}]@dots{} @var{item}@dots{}
>  @cmindex rm
>  Removes files, buffers, processes, or Emacs Lisp symbols, depending on
>  the argument.

"...depending on the type of each @var{item}."

> +@item source @var{file} [@var{argument}]@dots{}
>  @cmindex source
> -Source an Eshell file in a subshell environment.  This is not to be
> -confused with the command @command{.}, which sources a file in the
> -current environment.
> +Source an Eshell script named @var{file} in a subshell environment,
> +passing any @var{arguments} to the script (@pxref{Scripts}).  This is
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
"passing any @var{argument}s"

> +@item umask [-S] [@var{mode}]
>  @cmindex umask
> -Set or view the default file permissions for newly created files and
> -directories.
> +View the default file permissions for newly created files and
> +directories.  With @var{mode}, set the default permissions to this
> +value.  If you pass @code{-s} or @code{--symbolic}, view the mode
> +symbolically.                                       ^^^^

"set or view", perhaps?

> +@item wait [@var{process}]@dots{}
>  @cmindex wait
> -Wait until a process has successfully completed.
> +Wait until one or more processes have exited.

"Wait until one or more of @var{process}es have exited."

> +@item intersection @var{list1} @var{list2} [@var{option}]...

What happened to @dots{} (here and elsewhere in the rest of the
patch)?

Message #11 received at 68838 <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 68838 <at> debbugs.gnu.org
Subject: Re: bug#68838: 30.0.50; [PATCH] Document Eshell built-in commands'
 arguments in the manual
Date: Wed, 31 Jan 2024 12:38:03 -0800

[Message part 1 (text/plain, inline)]

On 1/31/2024 11:25 AM, Eli Zaretskii wrote:
>> Date: Tue, 30 Jan 2024 21:49:39 -0800
>> From: Jim Porter <jporterbugs <at> gmail.com>
>>
>> Eshell's manual documents all its built-in commands, but the
>> documentation is too brief in my opinion. It should document the
>> command-line options. Here's a patch to do so.
> 
> Thanks.  Some comments below.

Thanks for taking a look. Unless otherwise noted below, I just took your 
suggestions exactly as-is.

> This could benefit from explaining how to specify a list of
> directories.

Done. (You just pass them as separate arguments.)

>> +@item cat @var{file}@dots{}
>>   @cmindex cat
>> -Concatenate file contents into standard output.  If in a pipeline, or
>> -if the file is not a regular file, directory, or symlink, then this
>> -command reverts to the system's definition of @command{cat}.
>> +Concatenate the contents of @var{files} to standard output.  If in a
>                                 ^^^^^^^^^^^
> @var{file}s, since the argument is @var{file}.

Oh, I thought were weren't supposed to put the "s" for plurals outside 
of the @var{...} part. That's good, since I prefer the way you suggested 
too.

>> +@item cd =@var{regex}
>> +Search the directory ring for a directory matching the regular
>> +expression @var{regexp} and change to that directory.
>                     ^^^^^^
> Typo.

Fixed (by changing regex to regexp in the heading).

>> +@item umask [-S] [@var{mode}]
>>   @cmindex umask
>> -Set or view the default file permissions for newly created files and
>> -directories.
>> +View the default file permissions for newly created files and
>> +directories.  With @var{mode}, set the default permissions to this
>> +value.  If you pass @code{-s} or @code{--symbolic}, view the mode
>> +symbolically.                                       ^^^^
> 
> "set or view", perhaps?

-S actually only applies to viewing (since umask can tell by looking if 
MODE is symbolic when you set it). I've rearranged this to hopefully 
make it clearer.

>> +@item wait [@var{process}]@dots{}
>>   @cmindex wait
>> -Wait until a process has successfully completed.
>> +Wait until one or more processes have exited.
> 
> "Wait until one or more of @var{process}es have exited."

Fixed (with a slightly clearer wording to make sure people know that 
"wait" will wait for *each* process).

>> +@item intersection @var{list1} @var{list2} [@var{option}]...
> 
> What happened to @dots{} (here and elsewhere in the rest of the
> patch)?

Oops, I thought I'd fixed all those cases. Now done.

[0001-Document-arguments-to-Eshell-s-built-in-commands.patch (text/plain, attachment)]

Message #18 received at 68838-done <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 68838-done <at> debbugs.gnu.org
Subject: Re: bug#68838: 30.0.50; [PATCH] Document Eshell built-in commands'
 arguments in the manual
Date: Sun, 4 Feb 2024 21:21:46 -0800

I've now merged my latest patch to master as 5c43ef86bf1, so closing 
this bug. (Mainly so I can get to work on splitting this section up into 
small chunks.) Of course, if there are any followup issues, just let me 
know.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.