From: Eli Zaretskii <eliz@gnu.org>
To: Jim Porter <jporterbugs@gmail.com>
Cc: 68838@debbugs.gnu.org
Subject: bug#68838: 30.0.50; [PATCH] Document Eshell built-in commands' arguments in the manual
Date: Wed, 31 Jan 2024 21:25:16 +0200 [thread overview]
Message-ID: <86r0hx1f1f.fsf@gnu.org> (raw)
In-Reply-To: <a76adc47-af07-2147-cc9a-f9d585975115@gmail.com> (message from Jim Porter on Tue, 30 Jan 2024 21:49:39 -0800)
> Date: Tue, 30 Jan 2024 21:49:39 -0800
> From: Jim Porter <jporterbugs@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)?
next prev parent reply other threads:[~2024-01-31 19:25 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-01-31 5:49 bug#68838: 30.0.50; [PATCH] Document Eshell built-in commands' arguments in the manual Jim Porter
2024-01-31 19:25 ` Eli Zaretskii [this message]
2024-01-31 20:38 ` Jim Porter
2024-02-05 5:21 ` Jim Porter
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=86r0hx1f1f.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=68838@debbugs.gnu.org \
--cc=jporterbugs@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.