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

From: David Rowley <[email-masked]>
Date: Tue, 18 Apr 2023 17:44:39 +1200

Over on [1], Peter mentions that we might want to consider putting the
VACUUM options into some order that's better than the apparent random
order that they're currently in.

VACUUM is certainly one command that's grown a fairly good number of
options over the years and it appears we've not given much
consideration to what order to put those in in the documentation.

It's not just VACUUM that has this issue.  I see 6 commands using the
following text:

$ git grep "option</replaceable> can be one of"
src/sgml/ref/analyze.sgml: ...
src/sgml/ref/cluster.sgml: ...
src/sgml/ref/copy.sgml: ...
src/sgml/ref/explain.sgml: ...
src/sgml/ref/reindex.sgml: ...
src/sgml/ref/vacuum.sgml: ...

(maybe there's more we should consider adjusting?)

Likely if we do opt to put these options in a more well-defined order,
we should apply that to at least the 6 commands listed above.

For the case of reindex.sgml, I do see that the existing parameter
order lists INDEX | TABLE | SCHEMA | DATABASE | SYSTEM first which is
the target of the reindex. I wondered if that was worth keeping. I'm
just thinking that since all of these are under the "Parameters"
heading that we should class them all as equals and just make the
order alphabetical. I feel that if we don't do that then the order to
add any new parameters is just not going to be obvious and we'll end
up with things getting out of order again quite quickly.

I've attached a patch which makes the changes as I propose them.

David

[1] https://postgr.es/m/[email-masked]

---

From: Peter Geoghegan <[email-masked]>
Date: Mon, 17 Apr 2023 23:53:17 -0700

> up with things getting out of order again quite quickly.

I don't think that alphabetical order makes much sense. Surely some
parameters are more important than others. Surely there is some kind
of natural grouping that makes somewhat more sense than alphabetical
order.

Take the VACUUM command. Right now FULL, FREEZE, and VERBOSE all come
first. Those options are approximately the most important options --
especially VERBOSE. But your patch places VERBOSE dead last.

-- 
Peter Geoghegan

---

From: David Rowley <[email-masked]>
Date: Wed, 19 Apr 2023 11:17:52 +1200

> especially VERBOSE. But your patch places VERBOSE dead last.

hmm, how can we verify that the options are kept in order of
importance? What guidance can we provide to developers adding options
about where they should slot in the new option to the docs?

"Importance order" just seems horribly subjective to me.  I'd be
interested to know if you could tell me if SKIP_LOCKED has more
importance than INDEX_CLEANUP, for example. If you can, it would seem
like trying to say apples are more important than oranges, or
vice-versa.

David

---

From: Peter Geoghegan <[email-masked]>
Date: Tue, 18 Apr 2023 16:30:06 -0700

On Tue, Apr 18, 2023 at 4:18 PM David Rowley <[email-masked]> wrote:
> "Importance order" just seems horribly subjective to me.

Alphabetical order seems objectively bad. At least to me.

> I'd be interested to know if you could tell me if SKIP_LOCKED has more

I don't accept your premise that the only thing that matters (or the
most important thing) is adherence to some unambiguous and consistent
order.

-- 
Peter Geoghegan

---

From: Peter Geoghegan <[email-masked]>
Date: Tue, 18 Apr 2023 18:05:15 -0700

> most important thing) is adherence to some unambiguous and consistent

In the case of VACUUM, the current devel order is:

FULL, FREEZE, VERBOSE, ANALYZE, DISABLE_PAGE_SKIPPING, SKIP_LOCKED,
INDEX_CLEANUP, PROCESS_MAIN, PROCESS_TOAST,
TRUNCATE, PARALLEL, SKIP_DATABASE_STATS, ONLY_DATABASE_STATS, BUFFER_USAGE_LIMIT

I think that this order is far superior to alphabetical order, which
is tantamount to random order. The first 4 items are indeed the really
important ones to users, in my experience.

I do have some minor quibbles beyond that, though. These are:

* PARALLEL deserves to be at the start, maybe 4th or 5th overall.

* DISABLE_PAGE_SKIPPING should be later, since it's really only a
testing option that probably never proved useful in production. In
particular, it has little business being before SKIP_LOCKED, which is
much more important and relevant.

* TRUNCATE and INDEX_CLEANUP are similar options, and ought to be side
by side. I would put PROCESS_MAIN and PROCESS_TOAST after those two
for the same reason.

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.

-- 
Peter Geoghegan

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 19 Apr 2023 10:47:47 +0200

> the same importance. All of the details beyond that don't matter to

I agree with you that roughly bucketing items is a good approach.
Within each bucket we can then sort alphabetically.

-- 
Álvaro Herrera        Breisgau, Deutschland  —  https://www.EnterpriseDB.com/
"If you have nothing to say, maybe you need just the right tool to help you
not say it."                   (New York Times, about Microsoft PowerPoint)

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 19 Apr 2023 10:52:06 +0200

> most important thing) is adherence to some unambiguous and consistent

My thinking is, if I want to look up FREEZE on the VACUUM man page, I 
would welcome some easily identifiable way of locating it.  At that 
point, I don't know whether FREEZE is important or what kind of option 
it is.  For reference material, easy lookup should be a priority.  For a 
narrative chapter on VACUUM, you can introduce the options in any other 
suitable order.

---

From: Daniel Gustafsson <[email-masked]>
Date: Wed, 19 Apr 2023 11:07:04 +0200

> On 19 Apr 2023, at 10:52, Peter Eisentraut <[email-masked]> wrote:

> For reference material, easy lookup should be a priority.

+1. Alphabetical ordering is consistent with POLA.

> For a narrative chapter on VACUUM, you can introduce the options in any other
> suitable order.

I would even phrase it such that in this case one *should* present the options
in the order most suitable to educate the reader.

--
Daniel Gustafsson

---

From: Peter Geoghegan <[email-masked]>
Date: Wed, 19 Apr 2023 11:38:48 -0700

> 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.

-- 
Peter Geoghegan