Re: Should we put command options in alphabetical order in the doc?

On Wed, Apr 19, 2023 at 2:33 PM Melanie Plageman
<melanieplageman(at)gmail(dot)com> wrote:
> As for alphabetical ordering vs importance ordering: while I do think
> that if a user does not know what parameter they are looking for, an
> alphabetical ordering is unhelpful, I also think the primary issue with
> grouping them by "importance" is that it is difficult to maintain. Doing
> so requires a discussion of importance for every new option added.

Not really. It's a matter that requires some amount of individual
judgement, in some cases. It may require effort, but I think that
that's likely to be worth it.

I won't be the one that quibbles over every little thing.

> For VACUUM, I'd perhaps suggest the options in alphabetical order
> followed by table_name and then column_name and then putting the
> parameter argument types at the end alphabetically.
>
> Of course, we could decide VACUUM is special and group its options by
> importance because this is especially helpful for users. I think that
> there are other SQL commands whose options' importance is not
> particularly worth debating.

That's very likely true -- it may be that most individual commands
really wouldn't be any worse off if they just used a standard
alphabetical order. I agree that consistency can be a virtue. But it's
not the highest virtue. There will be a number of important
exceptions, which will have outsized impact. VACUUM, ANALYZE, maybe
CREATE INDEX. So if there is going to be a new standard, there should
also be significant wiggle-room. Kind of like with the guidelines for
rmgr desc authors discussion.

--
Peter Geoghegan