bug#52999: 29.0.50; [PATCH v3] `eshell-eval-using-options' should follow POSIX/GNU argument conventions

[Eli Zaretskii <eliz@gnu.org>]

> Cc: 52999@debbugs.gnu.org
> From: Jim Porter <jporterbugs@gmail.com>
> Date: Tue, 4 Jan 2022 13:09:29 -0800
> 
> I just wasn't sure if `eshell-eval-using-options' should be in the 
> manual or not. Thinking it over a bit more, it would have helped me if 
> it had been in the manual (I encountered this bug while trying to write 
> my own Eshell built-in command), so I added some info about it to the 
> manual, mostly adapted from the docstring for 
> `eshell-eval-using-options'. Hopefully I followed the right conventions 
> here; I'm only vaguely familiar with the Texinfo format.

Yes, the documentation part is fine, modulo some minor comments below.

> > Can these tests be made less platform-specific?  For example, not all
> > the supported platforms have /dev/null, and we have a portable
> > abstraction for it.
> 
> They should actually work cross-platform, since the tests don't invoke 
> the commands at all; they just make sure that 
> `eshell-eval-using-options' can parse the switches correctly. To make 
> this a bit clearer though, I replaced "/dev/null" with "/some/path". 
> Hopefully when people see that, they'll understand that this is a "fake" 
> path not corresponding to anything on the actual filesystem.

Apologies for misreading this part of the code.

> +@item symbol
> +This element is the name of the Lisp symbol that will be bound to
> +@var{value}.

Is it a symbol or its name (a string)?  You say "name", but the
example:

>               If @var{symbol} is @code{nil}, specifying this switch

uses a symbol, not its name.

> +@item :preserve-args
> +If present, do not pass @var{macro-args} through @code{flatten-tree}
> +and @code{eshell-stringify-list}.

I think this should explain the effect of that, or the difference
between using and not using this keyword.

> +---
> +** 'eshell-eval-using-options' now follows POSIX/GNU argument syntax conventions.
> +This now accepts command-line options with values passed as a single
   ^^^^
"Eshell" instead of "This" will make it more clear what you mean.

Thanks.