Horton

Thread

Commits

  1. doc: Alphabetize long options for pg_dump[all].

  1. alphabetize long options in pg_dump[all] docs

    Nathan Bossart <nathandbossart@gmail.com> — 2025-04-29T21:16:38Z

    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

  2. Re: alphabetize long options in pg_dump[all] docs

    Álvaro Herrera <alvherre@kurilemu.de> — 2025-04-29T21:45:11Z

    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)

  3. Re: alphabetize long options in pg_dump[all] docs

    Nathan Bossart <nathandbossart@gmail.com> — 2025-04-29T21:54:38Z

    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

  4. Re: alphabetize long options in pg_dump[all] docs

    Peter Eisentraut <peter@eisentraut.org> — 2025-04-30T11:58:19Z

    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.

  5. Re: alphabetize long options in pg_dump[all] docs

    Álvaro Herrera <alvherre@kurilemu.de> — 2025-04-30T14:46:37Z

    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)

  6. Re: alphabetize long options in pg_dump[all] docs

    Nathan Bossart <nathandbossart@gmail.com> — 2025-04-30T18:09:09Z

    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