From e7b809ae758636833e1e8a248ac6a6834eb034a1 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 29 Mar 2026 13:53:17 -0400
Subject: [PATCH] Doc: clarify introductory description of pg_dumpall.

Add a sentence that describes the parts of a cluster's state that are
*not* included in the output.

Also swap two sentences in the introductory paragraph.  Without that,
it is not clear what the "it" at the beginning of the second sentence
is referring to.  Also add a reference to pg_restore, since not all
output formats are restored with pg_dump.

Also clarify the recently-added text about where different output
formats go, and relocate it above the ancillary text about having
to run as superuser.

Reported-by: Dimitre Radoulov <cichomitiko@gmail.com>
Author: Laurenz Albe <laurenz.albe@cybertec.at>
Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/CAGJBphSX2oMPPu=VM4U8NP4+qffFH_483tFQCJ_s-mOcN3DLDw@mail.gmail.com
---
 doc/src/sgml/ref/pg_dumpall.sgml | 36 +++++++++++++++++++-------------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 49e5c99b09e..51c70198091 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -36,14 +36,33 @@ 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 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
+   of a cluster into an SQL script file or an archive.  It does this by
    calling <xref linkend="app-pgdump"/> for each database in the cluster.
+   The output contains <acronym>SQL</acronym> commands that can be used
+   as input to <xref linkend="app-psql"/> or <xref linkend="app-pgrestore"/>
+   to restore the databases.
    <application>pg_dumpall</application> also dumps global objects
    that are common to all databases, namely database roles, tablespaces,
    and privilege grants for configuration parameters.
    (<application>pg_dump</application> does not save these objects.)
+   The only parts of a database cluster's state that
+   are <emphasis>not</emphasis> included in the default output
+   of <application>pg_dumpall</application> are the configuration files
+   and any database parameter setting changes made with
+   <xref linkend="sql-altersystem"/>.
+  </para>
+
+  <para>
+   If the output format is a
+   plain text SQL script, it will be written to the standard output.  Use the
+   <option>-f</option>/<option>--file</option> option or shell operators to
+   redirect it into a file.
+  </para>
+
+  <para>
+   If another output format is selected, the archive will be placed in a
+   directory named using the <option>-f</option>/<option>--file</option>
+   option, which is required in this case.
   </para>
 
   <para>
@@ -54,17 +73,6 @@ PostgreSQL documentation
    allowed to add roles and create databases.
   </para>
 
-  <para>
-   Plain text SQL scripts will be written to the standard output.  Use the
-   <option>-f</option>/<option>--file</option> option or shell operators to
-   redirect it into a file.
-  </para>
-
-  <para>
-   Archives in other formats will be placed in a directory named using the
-   <option>-f</option>/<option>--file</option>, which is required in this case.
-  </para>
-
   <para>
   <application>pg_dumpall</application> needs to connect several
   times to the <productname>PostgreSQL</productname> server (once per