From adc9eb7433763d09051acdb3c41cad708beed82f Mon Sep 17 00:00:00 2001 From: Peter Smith Date: Thu, 13 Mar 2025 12:50:57 +1100 Subject: [PATCH v2] Synopsis improvements for server applications --- doc/src/sgml/docguide.sgml | 27 ++++++++++++++++++++ doc/src/sgml/ref/initdb.sgml | 12 +++------ doc/src/sgml/ref/pg_checksums.sgml | 8 +----- doc/src/sgml/ref/pg_controldata.sgml | 10 ++------ doc/src/sgml/ref/pg_createsubscriber.sgml | 42 +++++++++++-------------------- doc/src/sgml/ref/pg_resetwal.sgml | 18 +++---------- doc/src/sgml/ref/pg_rewind.sgml | 20 ++++++--------- doc/src/sgml/ref/pg_waldump.sgml | 4 +-- doc/src/sgml/ref/pg_walsummary.sgml | 14 +++++++++-- doc/src/sgml/ref/pgupgrade.sgml | 9 +++---- 10 files changed, 74 insertions(+), 90 deletions(-) diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index db4bcce..ce7c231 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -516,6 +516,33 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN that is done below. Instead, list the major components of the command line, such as where input and output files go. + + + Below are some addtional recommendations for an application synopsis: + + + + Options sometimes have short/long name variations. When there is a + self-descriptive argument show only the short option name, otherwise + show only the long option name. + + + + + Options with arguments that can be obtained from enviromnent + variables should be shown as optional. + For example, [-D datadir] + + + + + Options that are common across multiple applications should also + have consistent argument names. For example, + datadir and filename. + + + + diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 0026318..09fd08f 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -23,13 +23,7 @@ PostgreSQL documentation initdb option - - - - - - directory - + datadir @@ -190,8 +184,8 @@ PostgreSQL documentation - - + + This option specifies the directory where the database cluster diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml index 95043aa..60e9552 100644 --- a/doc/src/sgml/ref/pg_checksums.sgml +++ b/doc/src/sgml/ref/pg_checksums.sgml @@ -23,13 +23,7 @@ PostgreSQL documentation pg_checksums option - - - - - - datadir - + datadir diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml index b47fdca..9a0f1d1 100644 --- a/doc/src/sgml/ref/pg_controldata.sgml +++ b/doc/src/sgml/ref/pg_controldata.sgml @@ -22,14 +22,8 @@ PostgreSQL documentation pg_controldata - option - - - - - - datadir - + option + datadir diff --git a/doc/src/sgml/ref/pg_createsubscriber.sgml b/doc/src/sgml/ref/pg_createsubscriber.sgml index b4b9962..430c04e 100644 --- a/doc/src/sgml/ref/pg_createsubscriber.sgml +++ b/doc/src/sgml/ref/pg_createsubscriber.sgml @@ -23,23 +23,9 @@ PostgreSQL documentation pg_createsubscriber option - - - - - - dbname - - - - - datadir - - - - - connstr - + datadir + dbname + connstr @@ -88,6 +74,17 @@ PostgreSQL documentation + + + + + The target directory that contains a cluster directory from a physical + replica. + + + + + @@ -103,17 +100,6 @@ PostgreSQL documentation - - - - - The target directory that contains a cluster directory from a physical - replica. - - - - - diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml index dd011d2..7acb00d 100644 --- a/doc/src/sgml/ref/pg_resetwal.sgml +++ b/doc/src/sgml/ref/pg_resetwal.sgml @@ -22,22 +22,10 @@ PostgreSQL documentation pg_resetwal - - - - - - - - + + option - - - - - - datadir - + datadir diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index dc039d8..231f0f0 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -23,16 +23,10 @@ PostgreSQL documentation pg_rewind option - - - - - - directory - - - - + datadir + + + @@ -142,8 +136,8 @@ PostgreSQL documentation - - + + This option specifies the target data directory that is synchronized @@ -154,7 +148,7 @@ PostgreSQL documentation - + Specifies the file system path to the data directory of the source diff --git a/doc/src/sgml/ref/pg_waldump.sgml b/doc/src/sgml/ref/pg_waldump.sgml index ce23add..d1715ff 100644 --- a/doc/src/sgml/ref/pg_waldump.sgml +++ b/doc/src/sgml/ref/pg_waldump.sgml @@ -22,8 +22,8 @@ PostgreSQL documentation pg_waldump - - + option + startsegendseg diff --git a/doc/src/sgml/ref/pg_walsummary.sgml b/doc/src/sgml/ref/pg_walsummary.sgml index 57b2d24..9bc1b7a 100644 --- a/doc/src/sgml/ref/pg_walsummary.sgml +++ b/doc/src/sgml/ref/pg_walsummary.sgml @@ -23,7 +23,7 @@ PostgreSQL documentation pg_walsummary option - file + filename @@ -31,7 +31,7 @@ PostgreSQL documentation Description pg_walsummary is used to print the contents of - WAL summary files. These binary files are found with the + WAL summary files. These binary files are found in the pg_wal/summaries subdirectory of the data directory, and can be converted to text using this tool. This is not ordinarily necessary, since WAL summary files primarily exist to support @@ -57,6 +57,16 @@ PostgreSQL documentation + filename + + + A binary WAL summary file, found in the pg_wal/summaries + subdirectory of the data directory. + + + + + diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 9ef7a84..92d3294 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -22,13 +22,10 @@ PostgreSQL documentation pg_upgrade - - oldbindir + oldbindir newbindir - - oldconfigdir - - newconfigdir + oldconfigdir + newconfigdir option -- 1.8.3.1