On 10.06.25 08:59, Peter Eisentraut wrote:
The pg_dump and pg_dumpall help synopses could use some refinements.
Here is a concrete patch.
From 3e92c4ef2502e2664478423f2bcd1fbf59b8e7fd Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <pe...@eisentraut.org>
Date: Tue, 17 Jun 2025 09:39:17 +0200
Subject: [PATCH] Improve pg_dump/pg_dumpall help synopses and terminology
Increase consistency of --help and man page synopses between pg_dump
and pg_dumpall. These should now be very similar, as pg_dumpall can
now also produce non-text dump output. But actually, they have
drifted further apart.
- Use verb "export" consistently, instead of "dump" or "extract".
- Use "SQL script" instead of just "script" or "text file".
- Maintain consistent distinction between SQL script and other
formats/archives (which is relevant for pg_restore).
Discussion:
https://www.postgresql.org/message-id/flat/3f71d8a7-095b-4829-9b0b-fce09e9866b3%40eisentraut.org
---
doc/src/sgml/ref/pg_dump.sgml | 2 +-
doc/src/sgml/ref/pg_dumpall.sgml | 7 +++++--
doc/src/sgml/ref/pg_restore.sgml | 4 ++--
src/bin/pg_dump/pg_dump.c | 2 +-
src/bin/pg_dump/pg_dumpall.c | 2 +-
5 files changed, 10 insertions(+), 7 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index d7595a7e546..c95e3449367 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -18,7 +18,7 @@
<refname>pg_dump</refname>
<refpurpose>
- extract a <productname>PostgreSQL</productname> database into a script file
or other archive file
+ export a <productname>PostgreSQL</productname> database as an SQL script or
to other formats
</refpurpose>
</refnamediv>
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 723a466cfaa..7281301c808 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -16,7 +16,10 @@
<refnamediv>
<refname>pg_dumpall</refname>
- <refpurpose>extract a <productname>PostgreSQL</productname> database cluster
using a specified dump format</refpurpose>
+
+ <refpurpose>
+ export a <productname>PostgreSQL</productname> database cluster as an SQL
script or to other formats
+ </refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -33,7 +36,7 @@ <title>Description</title>
<para>
<application>pg_dumpall</application> is a utility for writing out
(<quote>dumping</quote>) all <productname>PostgreSQL</productname> databases
- of a cluster into an archive. The archive contains
+ of a cluster into an SQL script file or an archive. The output contains
<acronym>SQL</acronym> commands that can be used as input to <xref
linkend="app-psql"/> to restore the databases. It does this by
calling <xref linkend="app-pgdump"/> for each database in the cluster.
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 8c88b07dcc8..b649bd3a5ae 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -18,8 +18,8 @@
<refname>pg_restore</refname>
<refpurpose>
- restore a <productname>PostgreSQL</productname> database or cluster
- from an archive created by <application>pg_dump</application> or
+ restore <productname>PostgreSQL</productname> databases from archives
+ created by <application>pg_dump</application> or
<application>pg_dumpall</application>
</refpurpose>
</refnamediv>
diff --git a/src/bin/pg_dump/pg_dump.c b/src/bin/pg_dump/pg_dump.c
index 7bc0724cd30..11be05eab1c 100644
--- a/src/bin/pg_dump/pg_dump.c
+++ b/src/bin/pg_dump/pg_dump.c
@@ -1235,7 +1235,7 @@ main(int argc, char **argv)
static void
help(const char *progname)
{
- printf(_("%s dumps a database as a text file or to other
formats.\n\n"), progname);
+ printf(_("%s exports a PostgreSQL database as an SQL script or to other
formats.\n\n"), progname);
printf(_("Usage:\n"));
printf(_(" %s [OPTION]... [DBNAME]\n"), progname);
diff --git a/src/bin/pg_dump/pg_dumpall.c b/src/bin/pg_dump/pg_dumpall.c
index b1f388cb391..3cbcad65c5f 100644
--- a/src/bin/pg_dump/pg_dumpall.c
+++ b/src/bin/pg_dump/pg_dumpall.c
@@ -699,7 +699,7 @@ main(int argc, char *argv[])
static void
help(void)
{
- printf(_("%s extracts a PostgreSQL database cluster based on specified
dump format.\n\n"), progname);
+ printf(_("%s exports a PostgreSQL database cluster as an SQL script or
to other formats.\n\n"), progname);
printf(_("Usage:\n"));
printf(_(" %s [OPTION]...\n"), progname);
--
2.49.0
