Re: manual

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

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