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

On Wed, Apr 19, 2023 at 05:33:47PM -0400, Melanie Plageman wrote:
> On Wed, Apr 19, 2023 at 2:39 PM Peter Geoghegan <pg(at)bowt(dot)ie> wrote:
> >
> > On Wed, Apr 19, 2023 at 3:04 AM Alvaro Herrera <alvherre(at)alvh(dot)no-ip(dot)org> wrote:
> > > > While I'm certain that nobody will agree with me on every little
> > > > detail, I have to imagine that most would find my preferred ordering
> > > > quite understandable and unsurprising, at a high level -- this is not
> > > > a hopelessly idiosyncratic ranking, that could just as easily have
> > > > been generated by a PRNG. People may not easily agree that "apples are
> > > > more important than oranges, or vice-versa", but what does it matter?
> > > > I've really only put each option into buckets of items with *roughly*
> > > > the same importance. All of the details beyond that don't matter to
> > > > me, at all.
> > >
> > > I agree with you that roughly bucketing items is a good approach.
> > > Within each bucket we can then sort alphabetically.
> >
> > I think of these buckets as working at a logarithmic scale. The FULL,
> > FREEZE, VERBOSE, and ANALYZE options are multiple orders of magnitude
> > more important than most of the other options, and maybe one order of
> > magnitude more important than the PARALLEL, TRUNCATE, and
> > INDEX_CLEANUP options. With differences that big, you have a structure
> > that generalizes across all users quite well. This doesn't seem
> > particularly subjective.
>
> I actually favor query/command order followed by alphabetical order for
> most of the commands David included in his patch.
>
> Of course the parameter argument types, like boolean and integer, should
> be grouped together separate from the main parameters. David fit this
> into the alphabetical paradigm by doing uppercase alphabetical followed
> by lowercase alphabetical. There are some specific cases where I think
> this isn't working quite as intended in his patch. I've called those out
> in my command-by-command code review below.
>
> I actually think we should consider having a single location which
> defines all argument types for all SQL command parameters. Then we
> wouldn't need to define them for each command. We could simply link to
> the definition from the synopsis. That would clean up these lists quite
> a bit. Perhaps there is some variation from command to command in the
> actual definitions, though (I haven't checked). I would be happy to try
> and write this patch if folks are interested in the idea.

I looked into this and it isn't a good idea. Out of the 183 SQL
commands, really only ANALYZE, VACUUM, COPY, CLUSTER, EXPLAIN, and
REINDEX have parameter argument types that are context-independent. And
out of those, boolean is the only type shared by all. VACUUM is the only
one with more than one parameter argument "type". So, it is basically
just a bad idea. Oh well...

- Melanie