Improve pg_dump/pg_dumpall help synopses and terminology

petere · petere · commit dec6643487bb · 2025-06-19T13:57:16.000+02:00
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 had 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). Reviewed-by: Robert Treat <rob@xzilla.net> Discussion: https://www.postgresql.org/message-id/flat/3f71d8a7-095b-4829-9b0b-fce09e9866b3%40eisentraut.org
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
@@ -18,7 +18,7 @@ PostgreSQL documentation
   <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
@@ -16,7 +16,10 @@ PostgreSQL documentation
 
  <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 @@ PostgreSQL documentation
   <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
@@ -18,8 +18,8 @@ PostgreSQL documentation
   <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
@@ -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
@@ -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);
 

Original file line number	Diff line number	Diff line change
`@@ -1235,7 +1235,7 @@ main(int argc, char **argv)`
`1235`	`1235`	`static void`
`1236`	`1236`	`help(const char *progname)`
`1237`	`1237`	`{`
`1238`		`- printf(_("%s dumps a database as a text file or to other formats.\n\n"), progname);`
	`1238`	`+ printf(_("%s exports a PostgreSQL database as an SQL script or to other formats.\n\n"), progname);`
`1239`	`1239`	`printf(_("Usage:\n"));`
`1240`	`1240`	`printf(_(" %s [OPTION]... [DBNAME]\n"), progname);`
`1241`	`1241`
Original file line number	Diff line number	Diff line change
`@@ -699,7 +699,7 @@ main(int argc, char *argv[])`
`699`	`699`	`static void`
`700`	`700`	`help(void)`
`701`	`701`	`{`
`702`		`- printf(_("%s extracts a PostgreSQL database cluster based on specified dump format.\n\n"), progname);`
	`702`	`+ printf(_("%s exports a PostgreSQL database cluster as an SQL script or to other formats.\n\n"), progname);`
`703`	`703`	`printf(_("Usage:\n"));`
`704`	`704`	`printf(_(" %s [OPTION]...\n"), progname);`
`705`	`705`