Re: documentation structure

>
> I havent dealt with variadic yet, since the two styles are visually
> different, not just markup (<optional>...</optional> renders as [...]).
>
> The two styles for variadic are the what I call caller-style:
>
> concat ( val1 "any" [, val2 "any" [, ...] ] )
> format(formatstr text [, formatarg "any" [, ...] ])
>

While this style is obviously clumsier for us to compose, it does avoid
relying on the user understanding what the word variadic means. Searching
through online documentation of the python *args parameter, the word
variadic never comes up, the closest they get is "variable length
argument". I realize that python is not SQL, but I think it's a good point
of reference for what concepts the average reader is likely to know.

Looking at the patch, I think it is good, though I'd consider doing some
indentation for the nested <optional>s to allow the author to do more
visual tag-matching. The ']'s were sufficiently visually distinct that we
didn't really need or want nesting, but <optional> is just another tag to
my eyes in a sea of tags.