MIME-Version: 1.0
References: <CAH2-WzmcG1V14d=F7YF0gwEYh0xQE0BVvsO7SwDB9sgx2pBAYA@mail.gmail.com>
 <20230419084747.suskrykkzm2ity5e@alvherre.pgsql>
In-Reply-To: <20230419084747.suskrykkzm2ity5e@alvherre.pgsql>
From: David Rowley <dgrowleyml@gmail.com>
Date: Fri, 21 Apr 2023 00:40:48 +1200
Message-ID: <CAApHDvp6FijJyoDfSOALPPN6Y2Ycv6tGoo_QqEVLyyPqDekNnw@mail.gmail.com>
Subject: Re: Should we put command options in alphabetical order in the doc?
To: Alvaro Herrera <alvherre@alvh.no-ip.org>
Cc: Peter Geoghegan <pg@bowt.ie>, PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Content-Type: text/plain; charset="UTF-8"
Archived-At: <https://www.postgresql.org/message-id/CAApHDvp6FijJyoDfSOALPPN6Y2Ycv6tGoo_QqEVLyyPqDekNnw%40mail.gmail.com>
Precedence: bulk

On Wed, 19 Apr 2023 at 22:04, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
>
> On 2023-Apr-18, Peter Geoghegan 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.

If these "buckets" were subcategories, then it might be ok. I see "man
grep" categorises the command line options and then sorts
alphabetically within the category. If we could come up with a way of
categorising the options then this would satisfy what Melanie
mentioned about having the argument types listed separately. However,
I'm really not sure which categories we could have.  I really don't
have any concrete ideas here, but I'll attempt to at least start
something:

Behavioral:
ANALYZE
DISABLE_PAGE_SKIPPING
FREEZE
FULL
INDEX_CLEANUP
ONLY_DATABASE_STATS
PROCESS_MAIN
PROCESS_TOAST
SKIP_DATABASE_STATS
SKIP_LOCKED
TRUNCATE

Resource Usage:
BUFFER_USAGE_LIMIT
PARALLEL

Informational:
VERBOSE

Option Parameters:
boolean
column_name
integer
size
table_name

I'm just not sure if we have enough options to have a need to
categorise them.  Also, going by the categories I attempted to come up
with, it just feels like "Behavioral" contains too many and
"Informational" is likely only ever going to contain VERBOSE. So I'm
not very happy with them.

I'm not really feeling excited enough about this to even come up with
a draft patch. I thought I'd send out this anyway to see if anyone can
think of anything better.

FWIW, vacuumdb --help has its options in alphabetical order using the
abbreviated form of the option.

David