Re: Bash Reference Manual Type

[Robert Elz]

    Date:        Fri, 31 Mar 2023 14:41:37 -0400
    From:        Chet Ramey <chet.ramey@case.edu>
    Message-ID:  <625e93f4-280b-2cd4-f84d-2305bd347716@case.edu>

  | On 3/31/23 12:30 PM, Martin Schulte wrote:
  | > Hi Chet!
  | > 
  | >> Thanks for the report. The synopsis should read
  | >>
  | >> cd [-L|[-P [-e]]] [-@] [dir]
  | >         ^       ^
  | > But aren't these two brackets just superfluous?
  |
  | -L and -P are mutually exclusive, and -e is valid only when -P is
  | supplied.

-e only means anything when -P is specified, but there's no reason
to prohibit its use without -P, it simply does nothing in that case,
the option is simply meaningless.  (Better to prohibit -L, that's a
loony option - but also a whole different issue.)

The real issue here however is that there is no defined notation for
expressing these usage synopses.  What that means is that it isn't
specified whether alternation ('|') or concatenation (' ') has higher
precedence.

That is, whether

        cd [ -L | -P [-e] ]

means (with the addition of parentheses, which are never really
used in these things, or users would try to type them, just to make
precedence explicit)

        cd [ -L | ( -P [-e] ) ]
or
        cd [ ( -L | -P ) [-e] ]

In most languages the former would be the interpretation, but as there
is no spec for this one, we really don't know.   What we do know is that
we should be consistent.   If the first interpretation is the one that
applies, then the extra [] around -P [-e] aren't necessary.   If the second
is, then they are, but in that case

        cd -L | [-P [-e]] [-@]...

would be sufficient, as that would be interpreted as

        cd ( -L | ( [ -P [-e]] ) ) [-@]...

(the assumption is that alternation has higher precedence than
concatenation - we don't need to make the -L explicitly optional,
as its alternative can be empty, so to omit both -L and -P, we
would just take 2nd alternative (the optional -P) and then not
take the option.

But all of this is just intended to be a hint to users as to what
is possible, sometimes we'd make it clearer and give multiple
different possible synopsis lines

        cd [-L] [-@] [dir]
        cd -P [-e] [-@] [dir]

which can be clearer, but takes more space.

All of this is why (in the manual anyway) no-one should ever rely
upon the synopsis to convey much more than a hint - the text should
always be explicit about which "options" are required (if any), which
are mutually exclusive, ...

kre