Thread: 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
Attachment
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)