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/16845cb1-b228-e157-f293-5892bced9253@enterprisedb.com