manual

manual

[Ray Andrews]

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

-----------------------------------------------------------------------------

1): set [+]:
Print all parameters.  If '+' is given print them without their values.

Where usable:
-s: Ascending sort of the input.
+s: Descending sort of the input.

2): set {+|-}s [STRING] [STRING] ... :
If no flags other than +s or -s are given then the arguments following 
'set' are assigned to the
positional parameters:

Example:

$ set one "two's company" three
$ print -l -- $1 $2 $3
one
two's company
three

3,4) An array will be set.  Notice there is no equal sign and the array 
members are NOT to be enclosed in parentheses.

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.

Example:

$ set +s -A ARRAY_NAME A B C  'dee licious'
$ typeset -p ARRAY_NAME
typeset -a ARRAY_NAME=( 'dee licious' C B A )  # Sort is descending

$ set +A ARRAY_NAME 1 2 3
$ typeset -p ARRAY_NAME
typeset -a ARRAY_NAME=( 1 2 3 A )              # Only three elements 
overwritten.

$ set +A ARRAY_NAME aaaa
$ typeset -p ARRAY_NAME
typeset -a ARRAY_NAME=( aaaa 2 3 A )           # Only first element 
overwritten.

The processing of arguments after -A or +A depends on whether the
option KSH_ARRAYS  is set.  If not set, all arguments following 
ARRAY_NAME are
treated as values for the array, regardless of their form -- zsh will 
attempt no
interpretation or expansion of the arguments.  But if the option is set, 
normal
option processing will occur and only 'regular' arguments are treated as 
values
for the array.  This means that:

$ set -A array -x -- foo

... sets array to '-x -- foo' if KSH_ARRAYS is not set, but sets the
array to 'foo' and turns on the option '-x' if it is set.

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

... otherwise NEW_ARRAY will not be associative.  Be warned.

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

6): set +o:
Print all options and values formatted as commands.

7): set -o:
Print all options and values as a nice columnized display.

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



COMMENTS ON MAN PAGE:


               argFor the meaning of the other flags, see zshoptions(1).

WHAT OTHER FLAGS?


               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.


               If the -A flag is specified, name is set to an array 
containing  the  given
               args;  if  no name is specified, all arrays are printed 
together with their
               values.

IS THAT CORRECT?  SEEMS TO ME ALL PARAMETERS ARE PRINTED NOT JUST ARRAYS.

Re: manual

[Lawrence Velázquez]

On Tue, Dec 20, 2022, at 5:41 PM, Ray Andrews wrote:
>                If the -A flag is specified, name is set to an array 
> containing  the  given
>                args;  if  no name is specified, all arrays are printed 
> together with their
>                values.
>
> IS THAT CORRECT?

It is correct.

> SEEMS TO ME ALL PARAMETERS ARE PRINTED NOT JUST ARRAYS.

This is incorrect.

-- 
vq

Re: manual

[Ray Andrews]

On 2022-12-20 16:43, Lawrence Velázquez wrote:
>               args;  if  no name is specified, all arrays are printed
>> together with their
>>                 values.
>>
>> IS THAT CORRECT?
> It is correct.
>
>
> 0 /aWorking/Zsh/Source/Wk 2 $ set | grep red=
> COMMAND0=$'set | grep red=\nset | grep red=\nset | grep red=\n'
> Dred=$'\C-[[31m'
> _red=$'%{\C-[[1;31m%}'
> red=$'\C-[[31;1m'
>
> 0 /aWorking/Zsh/Source/Wk 2 $ typeset -p red
> typeset red=$'\C-[[31;1m'

red is scalar, no?

Re: manual

[Lawrence Velázquez]

On Tue, Dec 20, 2022, at 8:15 PM, Ray Andrews wrote:
> On 2022-12-20 16:43, Lawrence Velázquez wrote:
>>               args;  if  no name is specified, all arrays are printed
>>> together with their
>>>                 values.
>>>
>>> IS THAT CORRECT?
>> It is correct.
>>
>>
>> 0 /aWorking/Zsh/Source/Wk 2 $ set | grep red=
>> COMMAND0=$'set | grep red=\nset | grep red=\nset | grep red=\n'
>> Dred=$'\C-[[31m'
>> _red=$'%{\C-[[1;31m%}'
>> red=$'\C-[[31;1m'
>>
>> 0 /aWorking/Zsh/Source/Wk 2 $ typeset -p red
>> typeset red=$'\C-[[31;1m'
>
> red is scalar, no?

The command in question is "set -A", not "set".

-- 
vq

Re: manual

[Ray Andrews]

On 2022-12-20 17:44, Lawrence Velázquez wrote:
>
> The command in question is "set -A", not "set".
>
Ah!  I missed that in the manual as written.  My own doc would have to 
be edited to include that.  Anyway it was just an exercise.

Re: manual

[Daniel Shahaf]

Ray Andrews wrote on Tue, Dec 20, 2022 at 14:41:44 -0800:
> Daniel was interested in what I'd do with the 'set' man page.  It has a
> completely different flavor but:
> 

Thanks.  I was hoping you'd send new text just for that one three-line
paragraph, actually.  Glad to see more, but I don't have time to review
more, unfortunately, so I'll reply just to parts:

> 3): set {+|-}s -A [ARRAY_NAME] [VALUE]
> 4): set        +A [ARRAY_NAME] [VALUE]         # sorting not available with
⋮
> 3,4) An array will be set.  Notice there is no equal sign and the array
> members are NOT to be enclosed in parentheses.

The last sentence goes without saying, for several reasons:

- As a rule, the manual isn't in the business of describing what the
  syntax is not; the manual should describe what the syntax /is/.
  
  Putting =(…) there isn't nearly common enough an error to make an
  exception to the rule for.

- The synopsis doesn't show any equals signs or parentheses.

- «set» is a builtin.  The basic syntax of calling builtins, functions,
  and external commands is documented elsewhere in the manual, and in
  the context of this section is assumed knowledge.
  
  The assumed knowledge includes the fact that calling any builtin,
  function, or external command with anything enclosed in parentheses
  would be a syntax error.

  To see this:
  .
      f() { }
      for i in "autoload" "f" "/usr/bin/env" "[["; do
          "$i"
      done

  The fourth one fails, because «[[» is a keyword, and results of
  expansion are not considered as keywords.

  All of the first three work, because they all follow exactly the same
  "list of shell words" syntax; the only difference between them is what
  relative order they are considered (looked up) in.  (Functions are
  looked up first, which is why a function named "autoload" or "env"
  would shadow the builtin or the external command respectively.)

> 3): set {+|-}s -A [ARRAY_NAME] [VALUE]:
> ARRAY_NAME is set to VALUE, completely erasing any former contents:
> 

Normally the manual would end such a sentence at the comma.  Rule
against surplusage, I guess ☺

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

Unfortunately, as written this assumes the reader takes "overwriting" to
be an operation that involves "truncation" at some point, and we can't
assume the reader's mental model of overwriting is that.

> 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
> 
> ... otherwise NEW_ARRAY will not be associative.  Be warned.

Good point.  Right now the docs of -A just say the parameter "is set to
an array", which could be taken to mean it's forced to be a numerically-indexed
array.

So, that's a second issue in this section we should fix.

> COMMENTS ON MAN PAGE:
> 
> 
>               argFor the meaning of the other flags, see zshoptions(1).
> 
> WHAT OTHER FLAGS?
> 

The synopsis just says «{+|-}options», with "options" in var() markup.

That's unusual: most synopses spell out all valid flags.  See
<https://www.freebsd.org/cgi/man.cgi?ssh#SYNOPSIS> for example.

That sentence is saying that the flags covered by the mentioned part of
the synopsis are documented in zshoptions(1).

>

So, thanks again for the contribution.  Let's try and focus please and
the two specific issues identified («set -A» and types; «set -A» and
prefixes).

Re: manual

[Ray Andrews]

On 2022-12-20 18:00, Daniel Shahaf wrote:
> The last sentence goes without saying, for several reasons: 

Even in the unlikely event that the devs were interested in my writing, 
it goes without saying that there will be edits. And obviously the devs 
have the last word on any issue, however:

> - As a rule, the manual isn't in the business of describing what the
>    syntax is not; the manual should describe what the syntax /is/.
>    
>    Putting =(…) there isn't nearly common enough an error to make an
>    exception to the rule for.
It's part of my philosophy to throw in 'helpful hints'.  It's what makes 
a document actually helpful.  OTOH, as you correctly say, manuals are 
not focused on that, and in any case it would have to be broadly agreed 
that any particular helpful hint is really needed.  I needed it, but 
that's not sufficient.
> The assumed knowledge includes the fact that calling any builtin,
>    function, or external command with anything enclosed in parentheses
>    would be a syntax error.
First I've heard of that!  Seemed to me 'obvious' that there'd be 
parentheses -- an array is being assigned..  Mind, again, my particular 
ignorance is no test of what's worth mentioning.
>    All of the first three work, because they all follow exactly the same
>    "list of shell words" syntax; the only difference between them is what
>    relative order they are considered (looked up) in.  (Functions are
>    looked up first, which is why a function named "autoload" or "env"
>    would shadow the builtin or the external command respectively.)
I need to know more about all that.
> Normally the manual would end such a sentence at the comma. Rule
> against surplusage, I guess ☺
Yes of course, but it was a first draft!  Actually not even a draft, 
more like a sample of how I think a manual should be written.  Lots of 
examples -- actual runnable code that could be pasted to the CL and 
run.  Break up the synopsis into several lines,  each one covering some 
specific subset of functionality.  Give some thought to readability.  
Remember that people reading the doc are looking for usable information 
and the test of a doc is that it is helpful to the non-expert.  And so on.
> Unfortunately, as written this assumes the reader takes "overwriting" to
> be an operation that involves "truncation" at some point, and we can't
> assume the reader's mental model of overwriting is that.
Indeed.  It's clear to me but maybe not to the next guy.  The main thing 
I was trying to communicate with that little effort is that it's the 
*example* that makes it clear, not the exposition.
> That's unusual: most synopses spell out all valid flags
Yes!  Very lazy.  And I took 'options' there to mean option names. Mind, 
it does actually work that way.
> So, thanks again for the contribution. Let's try and focus please and
> the two specific issues identified («set -A» and types; «set -A» and
> prefixes).
>
After you mentioned it, I couldn't stop thinking about it, so had to 
give it a go.  I was writing it in my dreams last night.

Re: manual

[Bart Schaefer]

On Tue, Dec 20, 2022 at 6:00 PM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>
> The synopsis just says «{+|-}options», with "options" in var() markup.
>
> That's unusual: most synopses spell out all valid flags.

"No; it is too much.  Let me sum up."  -- Inigo Montoya

There was for a long time an effort made to keep the first-line
synopsis of each command short enough to fit on one line of "man"
output.  For a few commands that was impossible so we started adding
explicit line breaks with the expectation that the reader would
understand it was still all one command line.  For some others there
was no way to add a line break at a sensible place.

In this particular case (as you noted) there's an entire other section
already dedicated to the single-letter options that can be manipulated
with "set" and another for the long names for "set -o".

It might have been nice to be consistent about what was an "option"
and what was a "flag" or a "switch", but those terms are thrown around
colloquially with interpretation expected from context.

Re: manual

[Ray Andrews]

On 2022-12-20 20:43, Bart Schaefer wrote:
> In this particular case (as you noted) there's an entire other section 
> already dedicated to the single-letter options that can be manipulated 
Yabut they sent you to the head of an entire nother section of the 
manual.  Avoiding an entire block of duplication could be OK but say 
something like: "There are many other 'set' switches that are duplicated 
in/for the 'setopt' command (q.v.) which you can read just below this 
entry."
> with "set" and another for the long names for "set -o".
Ah!  Another thing I missed.  It's far from clear that they're even 
talking about single-letter options.  Why not say that?  I spent about 
two hours reading, experimenting, re-writing, trying to get every bit of 
information out of that page and I missed 'set -A' (by itself) and 
single letter options entirely.  Not to be too whiny but 'set' is a dogs 
breakfast of bad design.  It is a bizarre bazaar of bits and pieces of 
semi-related functionality rather like a junk-shop or a gypsy camp.  
It's like jazz -- don't ask for a definition.
> It might have been nice to be consistent about what was an "option"
> and what was a "flag" or a "switch", but those terms are thrown around
> colloquially with interpretation expected from context.

More than nice.  As discussed, manuals are not really focused on being 
helpful, but they should be absolutely consistent.  Perhaps a bit of 
literary license is welcome in a paragraph of exposition, but in a 
synopsis, if the word is 'flag' then stick with flag throughout.  I like 
'switch' myself but that's DOSey.  (A flag is a variable used to 
communicate some bit of information between one part of code an another 
IMHO.)  Nope, the entire Linux word (no doubt UNIX too but I've never 
touched it) should be ashamed of itself for it's abominable 
documentation.  Our manual is far from the worst.


>

Re: manual

[Lawrence Velázquez]

On Wed, Dec 21, 2022, at 9:04 AM, Ray Andrews wrote:
> Yabut they sent you to the head of an entire nother section of the 
> manual.  Avoiding an entire block of duplication could be OK but say 
> something like: "There are many other 'set' switches that are duplicated 
> in/for the 'setopt' command (q.v.) which you can read just below this 
> entry."

It already says where to look.

	For the meaning of the other flags, see zshoptions(1).


>> with "set" and another for the long names for "set -o".
> Ah!  Another thing I missed.  It's far from clear that they're even 
> talking about single-letter options.  Why not say that?

That wouldn't hurt, but zshoptions(1) goes into this at some length.

	Some options also have one or more single letter names.
	There are two sets of single letter options: one used by
	default, and another used to emulate sh/ksh (used when the
	SH_OPTION_LETTERS option is set).  The single letter options
	can be used on the shell command line, or with the `set',
	`setopt' and `unsetopt' builtins, as normal Unix options preceded
	by `-'.

	The sense of the single letter options may be inverted by
	using `+' instead of `-'.  Some of the single letter option
	names refer to an option being off, in which case the
	inversion of that name refers to the option being on.  For
	example, `+n' is the short name of `exec', and `-n' is the
	short name of its inversion, `noexec'.


> I spent about 
> two hours reading, experimenting, re-writing, trying to get every bit of 
> information out of that page and I missed 'set -A' (by itself) and 
> single letter options entirely.

The synopsis makes it quite clear that -A and +A can be used alone.

	set ... [ {+|-}A [ name ] ] ...

The square brackets indicate that the enclosed items are optional.
Thus the "name" option-argument is optional when using -A or +A,
and -A and +A are themselves optional.


-- 
vq

Re: manual

[Ray Andrews]

On 2022-12-21 22:31, Lawrence Velázquez wrote:
>
> It already says where to look.
>
> 	For the meaning of the other flags, see zshoptions(1).

I know it.  They send you to another section entirely which is 1487 
lines long.  Not very friendly.  Please understand that it's my 'job' in 
a discussion like this to be crabby and snotty and hard to please.   
Devil's advocate is what I'm being.


> 	Some options also have one or more single letter names.
> 	There are two sets of single letter options: one used by
> 	default, and another used to emulate sh/ksh (used when the
> 	SH_OPTION_LETTERS option is set).  The single letter options
> 	can be used on the shell command line, or with the `set',
> 	`setopt' and `unsetopt' builtins, as normal Unix options preceded
> 	by `-'.
>
> 	The sense of the single letter options may be inverted by
> 	using `+' instead of `-'.  Some of the single letter option
> 	names refer to an option being off, in which case the
> 	inversion of that name refers to the option being on.  For
> 	example, `+n' is the short name of `exec', and `-n' is the
> 	short name of its inversion, `noexec'.
>
That's quite well written.  Throw in some examples and it's good. But 
one should not have to go hunting for that information.  Unless ... 
there is some heavy reason why that's needed, in which case there should 
be a note to that effect: "( The subject of options is so extensive that 
it requires it's own elaboration and can't be fully explained here.  
Please see 'zshoptions' in the manual for a full development of the 
topic.)" ... or something like that.
>
> The synopsis makes it quite clear that -A and +A can be used alone.
>
> 	set ... [ {+|-}A [ name ] ] ...

Clear to you but not to me.  I missed it.  The expert will always find 
the manual good enough but that's not the test.  The test is whether the 
student found it good enough.  (Mind, there will be times when the 
student, fallible human that he is, might miss something that really is 
well explained.  And to be honest, I think that's the case here -- it is 
good enough, but overwhelmed as I was by everything else, I missed the 
easy part.)  Again, I hardly expected to get it right the first time, 
that would be a miracle.  It was a template.

The only thing that matters is that I've got a few of you guys thinking 
about all this :-)

Re: manual

[Lawrence Velázquez]

On Tue, Dec 20, 2022, at 9:00 PM, Daniel Shahaf wrote:
> Let's try and focus please and
> the two specific issues identified («set -A» and types; «set -A» and
> prefixes).

Here's an attempt.  Instead of trying to address every possible
case, I chose to describe the behavior in terms of other assignment
constructs which (to my knowledge) operate equivalently.


diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 56428a714..fca6db8e5 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -1687,13 +1687,19 @@ the description of tt(setopt) below for more information on the format.
 With tt(PLUS()o) they are printed in a form that can be used as input
 to the shell.
 
-If the tt(-A) flag is specified, var(name) is set to an array containing
-the given var(arg)s; if no var(name) is specified, all arrays are printed
-together with their values.
-
-If tt(PLUS()A) is used and var(name) is an array, the
-given arguments will replace the initial elements of that array; if no
-var(name) is specified, all arrays are printed without their values.
+If tt(-A) var(name) is specified, the var(arg)s are assigned to
+var(name) as with `var(name)tt(=LPAR())var(arg) ...tt(RPAR())'.  If
+tt(-A) is specified without var(name), all arrays are printed together
+with their values.
+
+If tt(PLUS()A) var(name) is specified, and var(name) is a normal array,
+the var(arg)s are assigned to var(name) as with
+`var(name)tt([1,)var(N)tt(]=LPAR())var(arg) ...tt(RPAR())' (or
+`var(name)tt([0,)var(N)tt(-1]=LPAR())var(arg) ...tt(RPAR())' with
+tt(KSH_ARRAYS) set), where var(N) is the number of var(arg)s provided.
+If var(name) is not a normal array, tt(PLUS()A) var(name) behaves like
+tt(-A) var(name).  If tt(PLUS()A) is specified without var(name), all
+arrays are printed without their values.
 
 The behaviour of arguments after tt(-A) var(name) or tt(PLUS()A) var(name)
 depends on whether the option tt(KSH_ARRAYS) is set.  If it is not set, all
-- 
vq

Re: manual

[Lawrence Velázquez]

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

Re: manual

[Ray Andrews]

On 2022-12-21 23:03, Lawrence Velázquez wrote:
> 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.
I'm pleased to have made as few mistakes as I did.  There was no hope 
that I'd get it right the first time.  It was just a sort of 
template/sample for my thoughts on how a manual page could be made more 
useful.  Indeed the way functionalities can be piled on top of each 
other is why I called 'set' a dog's breakfast.  IMHO we should have 
setopt (already do), setarray, and setparam.  But I appreciate that set 
probably got that way by accretion -- over the years stuff got added on 
and there was no point at which anyone wanted to back out and rethink 
the thing from the ground up.  London vs. Paris. As you say, a more 
broken up synopsis -- tho always the better way -- runs into trouble 
when functionalities can be piled on top of each other but with all 
sorts of ifs ands buts and maybees  (like the way that '+s' works with 
'-A' but not with '+A').  It's something to explore how that might be 
handled.  (Mostly by shaking out the commands themselves!)
> 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

Ironically IMHO that's going too far.

	set [{+,-}abCefhmnuvx] [{+,-}o option] [argument...]

... would be quite tractable.  (I myself prefer the comma to the pipe but that's just me.)

Dunno, on the one hand I think that manuals should be quite rigid in their use of terminology and the syntax of things like synopses, OTOH there are times when you hafta just 'get it done' -- explain the thing however it needs to be explained and that might mean bending a rule as to synopsis grammar.  Interesting questions!  But we're out of time anyway.  The only real test of/for any doc is whether or not it is useful to the people who might actually need to read it.  That means force feeding it to newbies -- the way you force feed medicine to lab rats -- and then asking them if the document is understandable.  If it is the doc is good, if not it needs work -- simple as that.  I'm trying to be that lab rat.  But there are so few of me.

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

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

That very well could be.  In the world according to Ray, the manual 
would start with a glossary of terms which would have rigid usage 
throughout.  Not 'flag' or 'switch' or 'option', pick one and define it 
exactly and use it exclusively.  Note that even in my experimental run, 
I took 'option' to mean a switch (cuz it's often used that way) whereas 
in that case it meant a single letter OPTION -- which is not explained 
in any way.  One could read that man-page and never know there is any 
such thing as a single-letter option.

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

No worries, it was just a dry run.  You're taking it more seriously than 
I did.  If ever a man-page were to be rewritten by me, it would be 
subject to checking and editing by knowledgeable people like yourself.  
I would never presume to have the final word on anything.  We'd  get it 
right on the 5th edit.  But I do have a talent for clarity.


>> DON'T KNOW WHAT TO DO WITH THAT.
> Leave it in?

As you would decide.  I'm only saying I myself can't do anything with it.

Good writing is a very difficult thing.  Especially good technical 
writing and coders are notoriously bad at it.