alphabetize long options in pg_dump[all] docs

I noticed some of the new pg_dump[all] long options (e.g., --with-data,
--statistics-only) are not listed in alphabetical order in the docs.
Attached is a patch to fix that.

--
nathan

On 2025-Apr-29, Nathan Bossart wrote:

> I noticed some of the new pg_dump[all] long options (e.g., --with-data,
> --statistics-only) are not listed in alphabetical order in the docs.
> Attached is a patch to fix that.

I think the concept here is that all short options go first in
alphabetical order, then the long options in their own alphabetical
order, and if one option has both, then the short option takes
precedence. If that's the idea, then --filter in pg_dumpall is in the
wrong place, and other than that it looks good.

I think that's what gives the shorter patch. But where would you look
for, say, --large-objects? I mean, how do you know that its short
version is -b? Maybe it would make more sense to sort on long options
first and put short options as the second-priority item for each option.

--
Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
"¿Qué importan los años? Lo que realmente importa es comprobar que
a fin de cuentas la mejor edad de la vida es estar vivo" (Mafalda)

On Tue, Apr 29, 2025 at 11:45:11PM +0200, Álvaro Herrera wrote:
> I think the concept here is that all short options go first in
> alphabetical order, then the long options in their own alphabetical
> order, and if one option has both, then the short option takes
> precedence.

That's what it looks like to me, too.

> If that's the idea, then --filter in pg_dumpall is in the
> wrong place, and other than that it looks good.

I missed that one, thanks.

> I think that's what gives the shorter patch. But where would you look
> for, say, --large-objects? I mean, how do you know that its short
> version is -b? Maybe it would make more sense to sort on long options
> first and put short options as the second-priority item for each option.

Fair point. We seem to be pivoting towards long options, anyway. If
there's support for this, I could go through all the client and server
application docs to ensure they match this style.

--
nathan

On 29.04.25 23:54, Nathan Bossart wrote:
> On Tue, Apr 29, 2025 at 11:45:11PM +0200, Álvaro Herrera wrote:
>> I think the concept here is that all short options go first in
>> alphabetical order, then the long options in their own alphabetical
>> order, and if one option has both, then the short option takes
>> precedence.
>
> That's what it looks like to me, too.
>
>> If that's the idea, then --filter in pg_dumpall is in the
>> wrong place, and other than that it looks good.
>
> I missed that one, thanks.
>
>> I think that's what gives the shorter patch. But where would you look
>> for, say, --large-objects? I mean, how do you know that its short
>> version is -b? Maybe it would make more sense to sort on long options
>> first and put short options as the second-priority item for each option.
>
> Fair point. We seem to be pivoting towards long options, anyway. If
> there's support for this, I could go through all the client and server
> application docs to ensure they match this style.

There are two styles currently in use: First, as described above, list
all short options first, then all long-only options. The second style
is that long-only options are listed alphabetically between short
options. I think both of these styles are used in --help output and man
pages, and I've long had a desire to unify under one style. Which would
also be helpful to offer guidance when new options are added.

However, I think this would require coordination across all --help
output and man pages (76 objects), so for the short term, let's just
move recently added options to the right place under the current
theory/theories, and leave a larger reshuffling for later.

On 2025-Apr-30, Peter Eisentraut wrote:

> On 29.04.25 23:54, Nathan Bossart wrote:

> > Fair point. We seem to be pivoting towards long options, anyway. If
> > there's support for this, I could go through all the client and server
> > application docs to ensure they match this style.
>
> However, I think this would require coordination across all --help output
> and man pages (76 objects), so for the short term, let's just move recently
> added options to the right place under the current theory/theories, and
> leave a larger reshuffling for later.

+1 WFM

--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
"Pero la cosa no es muy grave ..." (le petit Nicolas -- René Goscinny)

On Wed, Apr 30, 2025 at 04:46:37PM +0200, Álvaro Herrera wrote:
> On 2025-Apr-30, Peter Eisentraut wrote:
>> On 29.04.25 23:54, Nathan Bossart wrote:
>> > Fair point. We seem to be pivoting towards long options, anyway. If
>> > there's support for this, I could go through all the client and server
>> > application docs to ensure they match this style.
>>
>> However, I think this would require coordination across all --help output
>> and man pages (76 objects), so for the short term, let's just move recently
>> added options to the right place under the current theory/theories, and
>> leave a larger reshuffling for later.
>
> +1 WFM

Committed.

--
nathan