Re: manual

["Lawrence Velázquez" <larryv@zsh.org>]

On Tue, Dec 20, 2022, at 5:41 PM, Ray Andrews wrote:
> Daniel was interested in what I'd do with the 'set' man page.  It has a 
> completely different flavor but:
>
> 'set' has too many uses:
>
> 1): set [+]
> 2): set {+|-}s [STRING] [STRING] ...
> 3): set {+|-}s -A [ARRAY_NAME] [VALUE]
> 4): set        +A [ARRAY_NAME] [VALUE]         # sorting not available 
> with '+A'
> 5): set {+|-}OPTION_NAME
> 6): set +o
> 7): set -o
> 8): set {+|-}o [OPTION_NAME] [OPTION_NAME]  ... [--]

Partitioning the synopsis isn't a bad idea, but your partition is
misleading because most of the options you separated can actually
be used together in a single "set" command.

	% print $options[ALIASES] $options[ERR_EXIT]
	on off
	% typeset -p argv
	typeset -a argv=(  )
	% set +o ALIASES -e foo bar baz
	% print $options[ALIASES] $options[ERR_EXIT]
	off on
	% typeset -p argv
	typeset -a argv=( foo bar baz )
	% typeset -p arr || true
	typeset: no such variable: arr
	% set -o ALIASES +e -A arr v1 v2 v3
	% print $options[ALIASES] $options[ERR_EXIT]
	on off
	% typeset -p arr
	typeset -a arr=( v1 v2 v3 )

POSIX.1-2017 does partition its synopsis [*], but later it has to
explicitly explain that setting and unsetting attributes can be
mixed in a single invocation because the synopsis implies otherwise.

	set [-abCefhmnuvx] [-o option] [argument...]
	set [+abCefhmnuvx] [+o option] [argument...]
	set -- [argument...]
	set -o
	set +o

[*]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set


> 2): set {+|-}s [STRING] [STRING] ... :

The term "string" is next to useless when discussing shell.  Almost
everything is what you might consider a string.


> If no flags other than +s or -s are given then the arguments following 
> 'set' are assigned to the
> positional parameters:

As I already mentioned, this is incorrect.  Options and positional
parameters can be mixed in the same invocation.


> 3): set {+|-}s -A [ARRAY_NAME] [VALUE]:
> ARRAY_NAME is set to VALUE, completely erasing any former contents:
>
> 4): set +A [ARRAY_NAME] [VALUE]:
> ARRAY_NAME is overwritten by the new VALUE but not truncated if the new
> VALUE is shorter than the old.

These are incorrect.  Multiple arguments can be provided, all of
which are assigned to the array.  Additionally, -s and +s work with
+A, and it is not clear what "value" is supposed to mean.


> Note that 'typeset -A' is quite different from 'set -A'!  If you are 
> copying an
> associative array to another array you must do this:
>
> $ typeset -A NEW_ARRAY
> $ set -A NEW_ARRAY OLD_ARRAY

This example incorrectly implies that this should work:

	% typeset -A old_arr=(a 1 b 2 c 3)
	% typeset -A new_arr
	% set -A new_arr old_arr
	zsh: bad set of key/value pairs for associative array


> 5): set {+|-}[OPTION]
> Turn on|off a single OPTION.

This incorrectly implies that it is not possible to enable options,
disable options, and set positional parameters in the same invocation.


> 8): set {+|-}o [OPTION] [OPTION} ... [--]
> Turn on|off the given OPTIONS.  If the list is followed by '--' the 
> positional
> parameters will be unset.

It is not possible to enable or disable multiple options this way.
All but the first will actually be used as positional parameters.

	% set -o EXTENDED_GLOB ERR_EXIT
	% print $options[EXTENDED_GLOB] $options[ERR_EXIT]
	on off
	% typeset -p argv
	typeset -a argv=( ERR_EXIT )

Additionally, this incorrectly implies that the positional parameters
can only be cleared after -o or +o.


>                For historical reasons, `set -' is treated as `set +xv' 
> and `set - args' as
>                `set +xv -- args' when in any other emulation mode than 
> zsh's native mode.
>
> DON'T KNOW WHAT TO DO WITH THAT.

Leave it in?


-- 
vq