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
Attachments:
v1-0001-Alphabetize-long-options-in-pg_dump-all-docs.patchtext/plain; charset=us-asciiDownload
From 47b974f8ecbd44c26c4d9d8e1a8354e28f43549d Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Tue, 29 Apr 2025 16:14:35 -0500
Subject: [PATCH v1 1/1] Alphabetize long options in pg_dump[all] docs.
---
doc/src/sgml/ref/pg_dump.sgml | 83 ++++++++++++++++----------------
doc/src/sgml/ref/pg_dumpall.sgml | 74 ++++++++++++++--------------
2 files changed, 78 insertions(+), 79 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index b757d27ebd0..c10bca63e55 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -655,17 +655,6 @@ PostgreSQL documentation
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--statistics-only</option></term>
- <listitem>
- <para>
- Dump only the statistics, not the schema (data definitions) or data.
- Statistics for tables, materialized views, and indexes are dumped.
- </para>
-
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-Z <replaceable class="parameter">level</replaceable></option></term>
<term><option>-Z <replaceable class="parameter">method</replaceable></option>[:<replaceable>detail</replaceable>]</term>
@@ -1124,19 +1113,19 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>--no-security-labels</option></term>
+ <term><option>--no-schema</option></term>
<listitem>
<para>
- Do not dump security labels.
+ Do not dump schema (data definitions).
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>--no-schema</option></term>
+ <term><option>--no-security-labels</option></term>
<listitem>
<para>
- Do not dump schema (data definitions).
+ Do not dump security labels.
</para>
</listitem>
</varlistentry>
@@ -1232,33 +1221,6 @@ PostgreSQL documentation
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--with-data</option></term>
- <listitem>
- <para>
- Dump data. This is the default.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-schema</option></term>
- <listitem>
- <para>
- Dump schema (data definitions). This is the default.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-statistics</option></term>
- <listitem>
- <para>
- Dump statistics. This is the default.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--on-conflict-do-nothing</option></term>
<listitem>
@@ -1392,6 +1354,16 @@ PostgreSQL documentation
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--statistics-only</option></term>
+ <listitem>
+ <para>
+ Dump only the statistics, not the schema (data definitions) or data.
+ Statistics for tables, materialized views, and indexes are dumped.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--strict-names</option></term>
<listitem>
@@ -1467,6 +1439,33 @@ PostgreSQL documentation
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--with-data</option></term>
+ <listitem>
+ <para>
+ Dump data. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--with-schema</option></term>
+ <listitem>
+ <para>
+ Dump schema (data definitions). This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--with-statistics</option></term>
+ <listitem>
+ <para>
+ Dump statistics. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>-?</option></term>
<term><option>--help</option></term>
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 43fdab2d77e..de6a4e28f0c 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -345,16 +345,6 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--statistics-only</option></term>
- <listitem>
- <para>
- Dump only the statistics, not the schema (data definitions) or data.
- Statistics for tables, materialized views, and indexes are dumped.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--binary-upgrade</option></term>
<listitem>
@@ -640,33 +630,6 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--with-data</option></term>
- <listitem>
- <para>
- Dump data. This is the default.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-schema</option></term>
- <listitem>
- <para>
- Dump schema (data definitions). This is the default.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--with-statistics</option></term>
- <listitem>
- <para>
- Dump statistics. This is the default.
- </para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>--no-unlogged-table-data</option></term>
<listitem>
@@ -722,6 +685,16 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--statistics-only</option></term>
+ <listitem>
+ <para>
+ Dump only the statistics, not the schema (data definitions) or data.
+ Statistics for tables, materialized views, and indexes are dumped.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--use-set-session-authorization</option></term>
<listitem>
@@ -735,6 +708,33 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--with-data</option></term>
+ <listitem>
+ <para>
+ Dump data. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--with-schema</option></term>
+ <listitem>
+ <para>
+ Dump schema (data definitions). This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--with-statistics</option></term>
+ <listitem>
+ <para>
+ Dump statistics. This is the default.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>-?</option></term>
<term><option>--help</option></term>
--
2.39.5 (Apple Git-154)
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