DOCS: Make the Server Application docs synopses more consistent
Hi,
While reviewing the synopsis for pg_createsubscriber I compared it
with all the other synopses of the various Server Applications. In
doing so I found some minor differences between them all. The
differences are more apparent when you list everything together, like
below:
[1]: initdb - https://www.postgresql.org/docs/devel/app-initdb.html
[2]: pg_archivecleanup - https://www.postgresql.org/docs/devel/pgarchivecleanup.html
[3]: pg_checksums - https://www.postgresql.org/docs/devel/app-pgchecksums.html
[4]: pg_controldata - https://www.postgresql.org/docs/devel/app-pgcontroldata.html
[5]: pg_createsubscriber - https://www.postgresql.org/docs/devel/app-pgcreatesubscriber.html
--pgdata }datadir { -P | --publisher-server }connstr
[6]: pg_ctl - https://www.postgresql.org/docs/devel/app-pg-ctl.html
alternatives, it would be too much...)
[7]: pg_resetwal - https://www.postgresql.org/docs/devel/app-pgresetwal.html
--pgdata ]datadir
[8]: pg_rewind - https://www.postgresql.org/docs/devel/app-pgrewind.html
--source-pgdata=directory | --source-server=connstr }
[9]: pg_test_fsync - https://www.postgresql.org/docs/devel/pgtestfsync.html
[10]: pg_test_timing - https://www.postgresql.org/docs/devel/pgtesttiming.html
[11]: pg_upgrade - https://www.postgresql.org/docs/devel/pgupgrade.html
newconfigdir [option...]
[12]: pg_waldump - https://www.postgresql.org/docs/devel/pgwaldump.html
[13]: pg_walsummary - https://www.postgresql.org/docs/devel/app-pgwalsummary.html
~~
e.g. The following inconsistencies are noted:
* When both long}short options are provided sometimes those are
ordered long|short and sometimes they are short|long.
* Mostly the pgdata directory is called 'datadir' but sometimes just
'directory'.
* Mostly the optarg is squished against the option switch (no
spacing). It is an artifact of the way these synopses are constructed.
* Sometimes the rendering looks different (eg 'options' versus
'replaceable' style).
* Sometimes the replaceable optargs named in the synopsis are not
given in the options list, or they are there but with different names.
//////////
So, here are a few modifications to make everything more uniform:
[1]: initdb - https://www.postgresql.org/docs/devel/app-initdb.html
- changed 'directory' to (more common) 'datadir' in the synopsis
- changed same in the options list
- changed order "[--pgdata | -D]" to be (more commonly used) "[-D | --pgdata]"
- removed the space in from of the optarg. (most others synopses don't do this)
[5]: pg_createsubscriber - https://www.postgresql.org/docs/devel/app-pgcreatesubscriber.html
- in the options list 'directory' should be called 'datadir' to match
the synopsis
[8]: pg_rewind - https://www.postgresql.org/docs/devel/app-pgrewind.html
- remove spaces in the synopsis (most others synopses don't do this)
- change 'directory' to 'datadir' in the synopsis (for
--target-pgdata, and for --source-pgdata)
- change 'directory' to 'datadir' in the options (for --target-pgdata,
and for --source-pgdata)
[11]: pg_upgrade - https://www.postgresql.org/docs/devel/pgupgrade.html
- change 'bindir' to 'oldbindir' and 'newbindir' in the options list
(to match the synopsis)
- change 'configdir' to 'oldconfigdir' and 'newconfigdir' in the
options list (to match the synopsis)
[12]: pg_waldump - https://www.postgresql.org/docs/devel/pgwaldump.html
- This was using some different markup to the others (eg <option>
instead of <replaceable>) so the rendering did not appear the same.
[13]: pg_walsummary - https://www.postgresql.org/docs/devel/app-pgwalsummary.html
- Fixed a typo "found with" -> "found in"
- Change 'file' to 'filename' in the synopsis
- Add the missing entry in the options list to describe the
replaceable 'filename'.
~~~
Patch v1 is attached.
Thoughts?
======
[1]: initdb - https://www.postgresql.org/docs/devel/app-initdb.html
[2]: pg_archivecleanup - https://www.postgresql.org/docs/devel/pgarchivecleanup.html
https://www.postgresql.org/docs/devel/pgarchivecleanup.html
[3]: pg_checksums - https://www.postgresql.org/docs/devel/app-pgchecksums.html
[4]: pg_controldata - https://www.postgresql.org/docs/devel/app-pgcontroldata.html
https://www.postgresql.org/docs/devel/app-pgcontroldata.html
[5]: pg_createsubscriber - https://www.postgresql.org/docs/devel/app-pgcreatesubscriber.html
https://www.postgresql.org/docs/devel/app-pgcreatesubscriber.html
[6]: pg_ctl - https://www.postgresql.org/docs/devel/app-pg-ctl.html
[7]: pg_resetwal - https://www.postgresql.org/docs/devel/app-pgresetwal.html
[8]: pg_rewind - https://www.postgresql.org/docs/devel/app-pgrewind.html
[9]: pg_test_fsync - https://www.postgresql.org/docs/devel/pgtestfsync.html
[10]: pg_test_timing - https://www.postgresql.org/docs/devel/pgtesttiming.html
[11]: pg_upgrade - https://www.postgresql.org/docs/devel/pgupgrade.html
[12]: pg_waldump - https://www.postgresql.org/docs/devel/pgwaldump.html
[13]: pg_walsummary - https://www.postgresql.org/docs/devel/app-pgwalsummary.html
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v1-0001-DOCS-Make-the-Server-Application-docs-synopses-mo.patchapplication/octet-stream; name=v1-0001-DOCS-Make-the-Server-Application-docs-synopses-mo.patchDownload
From 0ad830a8b5fd4be92df9af5c0189c95f9d4ab629 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Fri, 13 Dec 2024 14:14:34 +1100
Subject: [PATCH v1] DOCS: Make the Server Application docs synopses more
consistent.
---
doc/src/sgml/ref/initdb.sgml | 8 ++++----
doc/src/sgml/ref/pg_createsubscriber.sgml | 4 ++--
doc/src/sgml/ref/pg_rewind.sgml | 10 +++++-----
doc/src/sgml/ref/pg_waldump.sgml | 4 ++--
doc/src/sgml/ref/pg_walsummary.sgml | 14 ++++++++++++--
doc/src/sgml/ref/pgupgrade.sgml | 16 ++++++++--------
6 files changed, 33 insertions(+), 23 deletions(-)
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 0c32114..adcbe0b 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -25,10 +25,10 @@ PostgreSQL documentation
<arg rep="repeat"><replaceable>option</replaceable></arg>
<group choice="plain">
<group choice="opt">
- <arg choice="plain"><option>--pgdata</option></arg>
<arg choice="plain"><option>-D</option></arg>
+ <arg choice="plain"><option>--pgdata</option></arg>
</group>
- <replaceable> directory</replaceable>
+ <replaceable>datadir</replaceable>
</group>
</cmdsynopsis>
</refsynopsisdiv>
@@ -190,8 +190,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry id="app-initdb-option-pgdata">
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
This option specifies the directory where the database cluster
diff --git a/doc/src/sgml/ref/pg_createsubscriber.sgml b/doc/src/sgml/ref/pg_createsubscriber.sgml
index df1a92b..61a5d0b 100644
--- a/doc/src/sgml/ref/pg_createsubscriber.sgml
+++ b/doc/src/sgml/ref/pg_createsubscriber.sgml
@@ -96,8 +96,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
The target directory that contains a cluster directory from a physical
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index dc039d8..817f85b 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -28,9 +28,9 @@ PostgreSQL documentation
<arg choice="plain"><option>-D</option></arg>
<arg choice="plain"><option>--target-pgdata</option></arg>
</group>
- <replaceable> directory</replaceable>
+ <replaceable>datadir</replaceable>
<group choice="req">
- <arg choice="plain"><option>--source-pgdata=<replaceable>directory</replaceable></option></arg>
+ <arg choice="plain"><option>--source-pgdata=<replaceable>datadir</replaceable></option></arg>
<arg choice="plain"><option>--source-server=<replaceable>connstr</replaceable></option></arg>
</group>
</group>
@@ -142,8 +142,8 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--target-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--target-pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
This option specifies the target data directory that is synchronized
@@ -154,7 +154,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>--source-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>--source-pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
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
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_waldump</command>
- <arg rep="repeat" choice="opt"><option>option</option></arg>
- <arg choice="opt"><option>startseg</option><arg choice="opt"><option>endseg</option></arg></arg>
+ <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
+ <arg choice="opt"><replaceable>startseg</replaceable><arg choice="opt"><replaceable>endseg</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
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
<cmdsynopsis>
<command>pg_walsummary</command>
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
- <arg rep="repeat"><replaceable>file</replaceable></arg>
+ <arg rep="repeat"><replaceable>filename</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -31,7 +31,7 @@ PostgreSQL documentation
<title>Description</title>
<para>
<application>pg_walsummary</application> 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
<literal>pg_wal/summaries</literal> 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
<para>
<variablelist>
<varlistentry>
+ <term><replaceable class="parameter">filename</replaceable></term>
+ <listitem>
+ <para>
+ A binary WAL summary file, found in the <literal>pg_wal/summaries</literal>
+ subdirectory of the data directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-i</option></term>
<term><option>--individual</option></term>
<listitem>
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 4777381..be48ded 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -81,15 +81,15 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term><option>-b</option> <replaceable>bindir</replaceable></term>
- <term><option>--old-bindir=</option><replaceable>bindir</replaceable></term>
+ <term><option>-b</option> <replaceable>oldbindir</replaceable></term>
+ <term><option>--old-bindir=</option><replaceable>oldbindir</replaceable></term>
<listitem><para>the old PostgreSQL executable directory;
environment variable <envar>PGBINOLD</envar></para></listitem>
</varlistentry>
<varlistentry>
- <term><option>-B</option> <replaceable>bindir</replaceable></term>
- <term><option>--new-bindir=</option><replaceable>bindir</replaceable></term>
+ <term><option>-B</option> <replaceable>newbindir</replaceable></term>
+ <term><option>--new-bindir=</option><replaceable>newbindir</replaceable></term>
<listitem><para>the new PostgreSQL executable directory;
default is the directory where <application>pg_upgrade</application> resides;
environment variable <envar>PGBINNEW</envar></para></listitem>
@@ -102,15 +102,15 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>-d</option> <replaceable>configdir</replaceable></term>
- <term><option>--old-datadir=</option><replaceable>configdir</replaceable></term>
+ <term><option>-d</option> <replaceable>oldconfigdir</replaceable></term>
+ <term><option>--old-datadir=</option><replaceable>oldconfigdir</replaceable></term>
<listitem><para>the old database cluster configuration directory; environment
variable <envar>PGDATAOLD</envar></para></listitem>
</varlistentry>
<varlistentry>
- <term><option>-D</option> <replaceable>configdir</replaceable></term>
- <term><option>--new-datadir=</option><replaceable>configdir</replaceable></term>
+ <term><option>-D</option> <replaceable>newconfigdir</replaceable></term>
+ <term><option>--new-datadir=</option><replaceable>newconfigdir</replaceable></term>
<listitem><para>the new database cluster configuration directory; environment
variable <envar>PGDATANEW</envar></para></listitem>
</varlistentry>
--
1.8.3.1
On Thu, Dec 12, 2024 at 8:25 PM Peter Smith <smithpb2250@gmail.com> wrote:
[1] initdb [option...] [ --pgdata | -D ] directory
[2] pg_archivecleanup [option...] archivelocation oldestkeptwalfile
[3] pg_checksums [option...] [[ -D | --pgdata ]datadir]
[4] pg_controldata [option] [[ -D | --pgdata ]datadir]
[5] pg_createsubscriber [option...] { -d | --database }dbname { -D |
--pgdata }datadir { -P | --publisher-server }connstr
[6] pg_ctl (the many synopses here don't give all the switch
alternatives, it would be too much...)
[7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
--pgdata ]datadir
[8] pg_rewind [option...] { -D | --target-pgdata } directory {
--source-pgdata=directory | --source-server=connstr }
[9] pg_test_fsync [option...]
[10] pg_test_timing [option...]
[11] pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
newconfigdir [option...]
[12] pg_waldump [option...] [startseg [endseg]]
[13] pg_walsummary [option...] [file...]
Here are some guidelines we should add to [1]https://www.postgresql.org/docs/current/docguide-style.html#DOCGUIDE-STYLE-REF-PAGES.
I don't feel listing both short and long form args is a good use of space -
and the { | } impairs readability. The short form combined with, usually,
a decent replaceable name, shows the reader the common interactive usage
and they can find the long forms in the Options section. Maybe use long
forms for value-less options since those don't get the argname hint.
The non-space between option and its value reduces readability. IIUC a
space in between doesn't impact correctness so I say go for readability.
This becomes more pronounced with the first items since it is only
marginally readable now because there is always a } or ] before the
replaceable. Though this may involve fighting the markup a bit...I haven't
experimented yet (pg_rewind managed it...).
The first listed command should probably only include mandatory options.
When there are multiple combinations of mandatory options show multiple
commands, one for each variant. Use examples to showcase idiomatic usage
patterns with descriptions. There is room to argue exceptions to be listed
also in Synopsis.
Establish the convention of datadir as the replaceable name. Possibly do
the same for other common items.
We should have a reference page (near [1]https://www.postgresql.org/docs/current/docguide-style.html#DOCGUIDE-STYLE-REF-PAGES listing DocBook elements and our
guidelines for how/where to use them.
In any case, details aside, modifying [1]https://www.postgresql.org/docs/current/docguide-style.html#DOCGUIDE-STYLE-REF-PAGES with whatever is agreed to (and
making changes to conform) is something I agree should happen.
David J.
[1]: https://www.postgresql.org/docs/current/docguide-style.html#DOCGUIDE-STYLE-REF-PAGES
https://www.postgresql.org/docs/current/docguide-style.html#DOCGUIDE-STYLE-REF-PAGES
On Wed, Mar 12, 2025 at 3:18 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
On Thu, Dec 12, 2024 at 8:25 PM Peter Smith <smithpb2250@gmail.com> wrote:
[1] initdb [option...] [ --pgdata | -D ] directory
[2] pg_archivecleanup [option...] archivelocation oldestkeptwalfile
[3] pg_checksums [option...] [[ -D | --pgdata ]datadir]
[4] pg_controldata [option] [[ -D | --pgdata ]datadir]
[5] pg_createsubscriber [option...] { -d | --database }dbname { -D |
--pgdata }datadir { -P | --publisher-server }connstr
[6] pg_ctl (the many synopses here don't give all the switch
alternatives, it would be too much...)
[7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
--pgdata ]datadir
[8] pg_rewind [option...] { -D | --target-pgdata } directory {
--source-pgdata=directory | --source-server=connstr }
[9] pg_test_fsync [option...]
[10] pg_test_timing [option...]
[11] pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
newconfigdir [option...]
[12] pg_waldump [option...] [startseg [endseg]]
[13] pg_walsummary [option...] [file...]Here are some guidelines we should add to [1].
I don't feel listing both short and long form args is a good use of space - and the { | } impairs readability. The short form combined with, usually, a decent replaceable name, shows the reader the common interactive usage and they can find the long forms in the Options section. Maybe use long forms for value-less options since those don't get the argname hint.
The non-space between option and its value reduces readability. IIUC a space in between doesn't impact correctness so I say go for readability. This becomes more pronounced with the first items since it is only marginally readable now because there is always a } or ] before the replaceable. Though this may involve fighting the markup a bit...I haven't experimented yet (pg_rewind managed it...).
The first listed command should probably only include mandatory options. When there are multiple combinations of mandatory options show multiple commands, one for each variant. Use examples to showcase idiomatic usage patterns with descriptions. There is room to argue exceptions to be listed also in Synopsis.
Establish the convention of datadir as the replaceable name. Possibly do the same for other common items.
We should have a reference page (near [1] listing DocBook elements and our guidelines for how/where to use them.
In any case, details aside, modifying [1] with whatever is agreed to (and making changes to conform) is something I agree should happen.
Hi David.
Thanks for taking an interest in this thread.
I've made some updates and attached the v2 patch.
======
CHANGE SUMMARY
There are some discussion points among these changes as well as other
TODO items to check I haven't broken anything.
[1]: initdb [option...] [ --pgdata | -D ] directory - removed the short/long option variations - cleanup the tags - changed replaceable 'directory' to 'datadir' in the synopsis and in the options list - TODO. Need to confirm if changing to "[-D datadir]" is correct, or should that be "[[-D] datadir]"
- removed the short/long option variations
- cleanup the tags
- changed replaceable 'directory' to 'datadir' in the synopsis and in
the options list
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]"
[2]: pg_archivecleanup [option...] archivelocation oldestkeptwalfile - no changes
- no changes
[3]: pg_checksums [option...] [[ -D | --pgdata ]datadir] - removed the short/long option variations - cleanup the tags - TODO. Need to confirm if changing to "[-D datadir]" is correct, or should that be "[[-D] datadir]" (see also initdb etc)
- removed the short/long option variations
- cleanup the tags
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]" (see also initdb etc)
[4]: pg_controldata [option] [[ -D | --pgdata ]datadir] - removed the short/long option variations - cleanup the tags - some <option> should be <replaceable> - the "[option]" should be "[option...]" - TODO. Need to confirm if changing to "[-D datadir]" is correct, or should that be "[[-D] datadir]" (see also initdb etc) - TODO. The page structure looks strange. There should be an "Options" section to describe -D, -V, and -?
- removed the short/long option variations
- cleanup the tags
- some <option> should be <replaceable>
- the "[option]" should be "[option...]"
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]" (see also initdb etc)
- TODO. The page structure looks strange. There should be an "Options"
section to describe -D, -V, and -?
[5]: pg_createsubscriber [option...] { -d | --database }dbname { -D | --pgdata }datadir { -P | --publisher-server }connstr - removed the short/long option variations - cleanup the tags - rearranged so -D comes first (same as most other commands) - make the "-D datadir" optional "[-D datadir]" - change 'directory' to 'datadir' in the options list so it matches the synopsis - change the order of the options list to match - TODO. Need to confirm if changing to "[-D datadir]" is correct, or should that be "[[-D] datadir]" (see also initdb etc)
--pgdata }datadir { -P | --publisher-server }connstr
- removed the short/long option variations
- cleanup the tags
- rearranged so -D comes first (same as most other commands)
- make the "-D datadir" optional "[-D datadir]"
- change 'directory' to 'datadir' in the options list so it matches the synopsis
- change the order of the options list to match
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]" (see also initdb etc)
[6]: pg_ctl (the many synopses here don't give all the switch alternatives, it would be too much...) - no changes
alternatives, it would be too much...)
- no changes
[7]: pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D | --pgdata ]datadir - removed the short/long option variations - cleanup the tags - TODO. Looks a bit strange with "[options...]" not shown first.
--pgdata ]datadir
- removed the short/long option variations
- cleanup the tags
- TODO. Looks a bit strange with "[options...]" not shown first.
[8]: pg_rewind [option...] { -D | --target-pgdata } directory { --source-pgdata=directory | --source-server=connstr } - removed the short/long option variations - cleanup the tags - make the "{-D datadir}" to be optional "[-D datadir]" - change 'directory' to 'datadir' in the synopsis and in the options list (for --D and for --source-pgdata) - TODO. Was it OK to make the "[-D datadir]" optional like all others? The page does not mention PGDATA. - TODO. Need to confirm if changing to "[-D datadir]" is correct, or should that be "[[-D] datadir]" (see also initdb etc)
--source-pgdata=directory | --source-server=connstr }
- removed the short/long option variations
- cleanup the tags
- make the "{-D datadir}" to be optional "[-D datadir]"
- change 'directory' to 'datadir' in the synopsis and in the options
list (for --D and for --source-pgdata)
- TODO. Was it OK to make the "[-D datadir]" optional like all others?
The page does not mention PGDATA.
- TODO. Need to confirm if changing to "[-D datadir]" is correct, or
should that be "[[-D] datadir]" (see also initdb etc)
[9]: pg_test_fsync [option...] - no changes
- no changes
[10]: pg_test_timing [option...] - no changes
- no changes
[11]: pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D newconfigdir [option...] - removed the short/long option variations - cleanup the tags - made all the option to be optional because the page says they can all use environment variable defaults. - TODO. Looks a bit strange with "[options...]" not shown first.
newconfigdir [option...]
- removed the short/long option variations
- cleanup the tags
- made all the option to be optional because the page says they can
all use environment variable defaults.
- TODO. Looks a bit strange with "[options...]" not shown first.
[12]: pg_waldump [option...] [startseg [endseg]] - change the <option> tags to be <replaceable>
- change the <option> tags to be <replaceable>
[13]: pg_walsummary [option...] [file...] - Fixed a typo "found with" -> "found in" - Change 'file' to 'filename' in the synopsis - Add the missing entry in the options list to describe the 'filename'.
- Fixed a typo "found with" -> "found in"
- Change 'file' to 'filename' in the synopsis
- Add the missing entry in the options list to describe the 'filename'.
~~~
I've modified the DOCS guidelines as suggested by adding a few recommendations.
~~~
OTHER QUESTIONS
- Should we use class="parameter" for all the <replaceable> tags?
Currently, some do, but most do not.
~~~
BTW, the scope of this thread is originally only the *server*
application pages, but all the *client* applications might be impacted
if we applied the same rules there.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v2-0001-Synopsis-improvements-for-server-applications.patchapplication/octet-stream; name=v2-0001-Synopsis-improvements-for-server-applications.patchDownload
From adc9eb7433763d09051acdb3c41cad708beed82f Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
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.
</para>
+
+ <para>
+ Below are some addtional recommendations for an application synopsis:
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Options with arguments that can be obtained from enviromnent
+ variables should be shown as optional.
+ For example, <literal>[-D datadir]</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Options that are common across multiple applications should also
+ have consistent argument names. For example,
+ <replaceable>datadir</replaceable> and <replaceable>filename</replaceable>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
</listitem>
</varlistentry>
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
<cmdsynopsis>
<command>initdb</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
- <group choice="plain">
- <group choice="opt">
- <arg choice="plain"><option>--pgdata</option></arg>
- <arg choice="plain"><option>-D</option></arg>
- </group>
- <replaceable> directory</replaceable>
- </group>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -190,8 +184,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry id="app-initdb-option-pgdata">
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
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
<cmdsynopsis>
<command>pg_checksums</command>
<arg rep="repeat" choice="opt"><replaceable class="parameter">option</replaceable></arg>
- <group choice="opt">
- <group choice="opt">
- <arg choice="plain"><option>-D</option></arg>
- <arg choice="plain"><option>--pgdata</option></arg>
- </group>
- <replaceable class="parameter">datadir</replaceable>
- </group>
+ <arg choice="opt"><option>-D</option> <replaceable class="parameter">datadir</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
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
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_controldata</command>
- <arg choice="opt"><replaceable class="parameter">option</replaceable></arg>
- <group choice="opt">
- <group choice="opt">
- <arg choice="plain"><option>-D</option></arg>
- <arg choice="plain"><option>--pgdata</option></arg>
- </group>
- <replaceable class="parameter">datadir</replaceable>
- </group>
+ <arg rep="repeat" choice="opt"><replaceable class="parameter">option</replaceable></arg>
+ <arg choice="opt"><option>-D</option> <replaceable class="parameter">datadir</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
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
<cmdsynopsis>
<command>pg_createsubscriber</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
- <group choice="plain">
- <group choice="req">
- <arg choice="plain"><option>-d</option></arg>
- <arg choice="plain"><option>--database</option></arg>
- </group>
- <replaceable>dbname</replaceable>
- <group choice="req">
- <arg choice="plain"><option>-D</option> </arg>
- <arg choice="plain"><option>--pgdata</option></arg>
- </group>
- <replaceable>datadir</replaceable>
- <group choice="req">
- <arg choice="plain"><option>-P</option></arg>
- <arg choice="plain"><option>--publisher-server</option></arg>
- </group>
- <replaceable>connstr</replaceable>
- </group>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+ <arg choice="req"><option>-d</option> <replaceable>dbname</replaceable></arg>
+ <arg choice="req"><option>-P</option> <replaceable>connstr</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -88,6 +74,17 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
+ <listitem>
+ <para>
+ The target directory that contains a cluster directory from a physical
+ replica.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-d <replaceable class="parameter">dbname</replaceable></option></term>
<term><option>--database=<replaceable class="parameter">dbname</replaceable></option></term>
<listitem>
@@ -103,17 +100,6 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
- <listitem>
- <para>
- The target directory that contains a cluster directory from a physical
- replica.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>-n</option></term>
<term><option>--dry-run</option></term>
<listitem>
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
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_resetwal</command>
- <group choice="opt">
- <arg choice="plain"><option>-f</option></arg>
- <arg choice="plain"><option>--force</option></arg>
- </group>
- <group choice="opt">
- <arg choice="plain"><option>-n</option></arg>
- <arg choice="plain"><option>--dry-run</option></arg>
- </group>
+ <arg choice="opt"><option>--force</option></arg>
+ <arg choice="opt"><option>--dry-run</option></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
- <group choice="plain">
- <group choice="opt">
- <arg choice="plain"><option>-D</option></arg>
- <arg choice="plain"><option>--pgdata</option></arg>
- </group>
- <replaceable class="parameter">datadir</replaceable>
- </group>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
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
<cmdsynopsis>
<command>pg_rewind</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
- <group choice="plain">
- <group choice="req">
- <arg choice="plain"><option>-D</option></arg>
- <arg choice="plain"><option>--target-pgdata</option></arg>
- </group>
- <replaceable> directory</replaceable>
- <group choice="req">
- <arg choice="plain"><option>--source-pgdata=<replaceable>directory</replaceable></option></arg>
- <arg choice="plain"><option>--source-server=<replaceable>connstr</replaceable></option></arg>
- </group>
+ <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
+ <group choice="req">
+ <arg choice="plain"><option>--source-pgdata=<replaceable>datadir</replaceable></option></arg>
+ <arg choice="plain"><option>--source-server=<replaceable>connstr</replaceable></option></arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
@@ -142,8 +136,8 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--target-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--target-pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
This option specifies the target data directory that is synchronized
@@ -154,7 +148,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>--source-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>--source-pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
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
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_waldump</command>
- <arg rep="repeat" choice="opt"><option>option</option></arg>
- <arg choice="opt"><option>startseg</option><arg choice="opt"><option>endseg</option></arg></arg>
+ <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
+ <arg choice="opt"><replaceable>startseg</replaceable><arg choice="opt"><replaceable>endseg</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
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
<cmdsynopsis>
<command>pg_walsummary</command>
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
- <arg rep="repeat"><replaceable>file</replaceable></arg>
+ <arg rep="repeat"><replaceable>filename</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -31,7 +31,7 @@ PostgreSQL documentation
<title>Description</title>
<para>
<application>pg_walsummary</application> 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
<literal>pg_wal/summaries</literal> 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
<para>
<variablelist>
<varlistentry>
+ <term><replaceable class="parameter">filename</replaceable></term>
+ <listitem>
+ <para>
+ A binary WAL summary file, found in the <literal>pg_wal/summaries</literal>
+ subdirectory of the data directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-i</option></term>
<term><option>--individual</option></term>
<listitem>
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
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_upgrade</command>
- <arg choice="plain"><option>-b</option></arg>
- <arg choice="plain"><replaceable>oldbindir</replaceable></arg>
+ <arg choice="opt"><option>-b</option> <replaceable>oldbindir</replaceable></arg>
<arg choice="opt"><option>-B</option> <replaceable>newbindir</replaceable></arg>
- <arg choice="plain"><option>-d</option></arg>
- <arg choice="plain"><replaceable>oldconfigdir</replaceable></arg>
- <arg choice="plain"><option>-D</option></arg>
- <arg choice="plain"><replaceable>newconfigdir</replaceable></arg>
+ <arg choice="opt"><option>-d</option> <replaceable>oldconfigdir</replaceable></arg>
+ <arg choice="opt"><option>-D</option> <replaceable>newconfigdir</replaceable></arg>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
--
1.8.3.1
On Wednesday, March 12, 2025, Peter Smith <smithpb2250@gmail.com> wrote:
I've made some updates and attached the v2 patch.
Thanks. Full review later.
Pg_controldata
- TODO. The page structure looks strange. There should be an "Options"
section to describe -D, -V, and -?
Agreed.
[7] pg_resetwal [ -f | --force ] [ -n | --dry-run ] [option...] [ -D |
- TODO. Looks a bit strange with "[options...]" not shown first.
Yeah, need to fix that.
[8] pg_rewind [option...] { -D | --target-pgdata } directory
- TODO. Was it OK to make the "[-D datadir]" optional like all others?
The page does not mention PGDATA.
My take on this is that the presence of environment variables doesn’t
impact whether a given CLI option is shown optional or mandatory. We are,
in effect, communicating that “datadir” must be specified for this
command. And then choosing one of the ways of specifying it. The reader
can use the indicated short-form -D, the long-form —pgdata if it exists, or
the DATADIR environment variable (this applies to any option, not just
datadir) as they desire. In short, most/all of these should show “-D
datadir” without [ ].
[11]: pg_upgrade -b oldbindir [-B newbindir] -d oldconfigdir -D
newconfigdir [option...]
- made all the option to be optional because the page says they can
all use environment variable defaults.
See note above regarding environment variables.
- TODO. Looks a bit strange with "[options...]" not shown first.
Should be moved.
OTHER QUESTIONS
- Should we use class="parameter" for all the <replaceable> tags?
Currently, some do, but most do not.
I’d probably document that they should have that class but leave the bulk
cleanup of existing content for a separate patch.
~~~
BTW, the scope of this thread is originally only the *server*
application pages, but all the *client* applications might be impacted
if we applied the same rules there.
Yeah, noticed that yesterday. I don’t see a reason why the same policy
shouldn’t apply to both subsets. I wouldn’t require everything has to be
changed right now though. Perfectly happy to ask for people specifically
familiar with these applications to modify the pages under the new policy
and try to divvy up the work. Then pickup what doesn’t get done.
David J.
On Wednesday, March 12, 2025, David G. Johnston <david.g.johnston@gmail.com>
wrote:
My take on this is that the presence of environment variables doesn’t
impact whether a given CLI option is shown optional or mandatory. We are,
in effect, communicating that “datadir” must be specified for this
command. And then choosing one of the ways of specifying it. The reader
can use the indicated short-form -D, the long-form —pgdata if it exists, or
the DATADIR environment variable (this applies to any option, not just
datadir) as they desire. In short, most/all of these should show “-D
datadir” without [ ].
Expanding on this a bit. Write the synopsis as if no environment variables
are set.
Generally, if the application itself defines the default value do not list
the option in the primary synopsis entry at all. If the application takes
an option’s default value from the OS environment by a means other than an
optional environment variable then show the option in the primary synopsis
entry but mark it as optional.
Connection options can have their own rules; which means we don’t need to
be specifying -U and -d everywhere when we deal with client applications.
Though maybe we should?
David J.
My previous v2 patch needed a rebase anyway, so I've taken this
opportunity also to restructure everything. Although it would be
easier to post a single patch, some of the changes are still
debatable. For this reason, now I've split the previous v2 patch into
multiple parts, hoping that it will help all the uncontroversial
changes to be easily committed up-front, so that we can focus any
debate on whatever remains.
Please find the v3 patches attached:
v3-0001 - Refer consistently to the --pgdata directory as 'datadir'
(most commands already do this, but not all).
v3-0002 - pg_walsummary. Fix typo. "with" should be "within"
v3-0003 - pg_walsummary. Change 'file' to 'filename' and add the
missing option description for it.
v3-0004 - pg_waldump. Some <option> tags are wrong; they should be <replaceable>
v3-0005 - [option] should be [option...] and make it always first,
like 95% of all commands already do.
v3-0006 - pg_controldata should have an "Options" section with
descriptions for -D and -V, and -? options.
v3-0007 - docguide. Added some new style guidelines for the reference
page synopsis
There are still several previously discussed (earlier in this thread)
changes that are not in this v3* patch set. They haven't been
forgotten; I'll revisit those later after the above (simpler) changes
are dealt with.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
Attachments:
v3-0004-DOCS-pg_waldump.-Some-option-tags-are-wrong-shoul.patchapplication/octet-stream; name=v3-0004-DOCS-pg_waldump.-Some-option-tags-are-wrong-shoul.patchDownload
From d65d4af3f5644699f4fa83eb157e023d1f865ee4 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 22 Apr 2025 13:39:51 +1000
Subject: [PATCH v3] DOCS - pg_waldump. Some <option> tags are wrong; should be
<replaceable>
---
doc/src/sgml/ref/pg_waldump.sgml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
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
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_waldump</command>
- <arg rep="repeat" choice="opt"><option>option</option></arg>
- <arg choice="opt"><option>startseg</option><arg choice="opt"><option>endseg</option></arg></arg>
+ <arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
+ <arg choice="opt"><replaceable>startseg</replaceable><arg choice="opt"><replaceable>endseg</replaceable></arg></arg>
</cmdsynopsis>
</refsynopsisdiv>
--
1.8.3.1
v3-0003-DOCS-pg_walsummary.-Change-file-to-filename-and-a.patchapplication/octet-stream; name=v3-0003-DOCS-pg_walsummary.-Change-file-to-filename-and-a.patchDownload
From 614ab58e2636111ff4a93c5ef1ef3654c7dc5fef Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 22 Apr 2025 13:39:05 +1000
Subject: [PATCH v3] DOCS - pg_walsummary. Change 'file' to 'filename' and add
the missing option description for it.
---
doc/src/sgml/ref/pg_walsummary.sgml | 12 +++++++++++-
1 file changed, 11 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/ref/pg_walsummary.sgml b/doc/src/sgml/ref/pg_walsummary.sgml
index 5ffe07d..0fd9dbf 100644
--- a/doc/src/sgml/ref/pg_walsummary.sgml
+++ b/doc/src/sgml/ref/pg_walsummary.sgml
@@ -23,7 +23,7 @@ PostgreSQL documentation
<cmdsynopsis>
<command>pg_walsummary</command>
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
- <arg rep="repeat"><replaceable>file</replaceable></arg>
+ <arg rep="repeat"><replaceable>filename</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -57,6 +57,16 @@ PostgreSQL documentation
<para>
<variablelist>
<varlistentry>
+ <term><replaceable class="parameter">filename</replaceable></term>
+ <listitem>
+ <para>
+ A binary WAL summary file, found within the <literal>pg_wal/summaries</literal>
+ subdirectory of the data directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-i</option></term>
<term><option>--individual</option></term>
<listitem>
--
1.8.3.1
v3-0001-DOCS-synopsis.-Refer-consistently-to-the-pgdata-d.patchapplication/octet-stream; name=v3-0001-DOCS-synopsis.-Refer-consistently-to-the-pgdata-d.patchDownload
From 1dc3e6c3f8d2ff9b35b7f49fd086c9425b310d3b Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 22 Apr 2025 13:37:08 +1000
Subject: [PATCH v3] DOCS - synopsis. Refer consistently to the --pgdata
directory as 'datadir'
---
doc/src/sgml/ref/initdb.sgml | 6 +++---
doc/src/sgml/ref/pg_checksums.sgml | 4 ++--
doc/src/sgml/ref/pg_createsubscriber.sgml | 4 ++--
doc/src/sgml/ref/pg_rewind.sgml | 10 +++++-----
4 files changed, 12 insertions(+), 12 deletions(-)
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 7613174..bd0dbff 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -28,7 +28,7 @@ PostgreSQL documentation
<arg choice="plain"><option>--pgdata</option></arg>
<arg choice="plain"><option>-D</option></arg>
</group>
- <replaceable> directory</replaceable>
+ <replaceable> datadir</replaceable>
</group>
</cmdsynopsis>
</refsynopsisdiv>
@@ -190,8 +190,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry id="app-initdb-option-pgdata">
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
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..9aabe96 100644
--- a/doc/src/sgml/ref/pg_checksums.sgml
+++ b/doc/src/sgml/ref/pg_checksums.sgml
@@ -61,8 +61,8 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term><option>-D <replaceable>directory</replaceable></option></term>
- <term><option>--pgdata=<replaceable>directory</replaceable></option></term>
+ <term><option>-D <replaceable>datadir</replaceable></option></term>
+ <term><option>--pgdata=<replaceable>datadir</replaceable></option></term>
<listitem>
<para>
Specifies the directory where the database cluster is stored.
diff --git a/doc/src/sgml/ref/pg_createsubscriber.sgml b/doc/src/sgml/ref/pg_createsubscriber.sgml
index 4b1d08d..a952800 100644
--- a/doc/src/sgml/ref/pg_createsubscriber.sgml
+++ b/doc/src/sgml/ref/pg_createsubscriber.sgml
@@ -126,8 +126,8 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
The target directory that contains a cluster directory from a physical
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index 5485033..eceff9d 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -28,9 +28,9 @@ PostgreSQL documentation
<arg choice="plain"><option>-D</option></arg>
<arg choice="plain"><option>--target-pgdata</option></arg>
</group>
- <replaceable> directory</replaceable>
+ <replaceable> datadir</replaceable>
<group choice="req">
- <arg choice="plain"><option>--source-pgdata=<replaceable>directory</replaceable></option></arg>
+ <arg choice="plain"><option>--source-pgdata=<replaceable>datadir</replaceable></option></arg>
<arg choice="plain"><option>--source-server=<replaceable>connstr</replaceable></option></arg>
</group>
</group>
@@ -142,8 +142,8 @@ PostgreSQL documentation
<variablelist>
<varlistentry>
- <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
- <term><option>--target-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
+ <term><option>--target-pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
This option specifies the target data directory that is synchronized
@@ -154,7 +154,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>--source-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
+ <term><option>--source-pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
<listitem>
<para>
Specifies the file system path to the data directory of the source
--
1.8.3.1
v3-0002-DOCS-pg_walsummary.-Fix-typo.-with-should-be-with.patchapplication/octet-stream; name=v3-0002-DOCS-pg_walsummary.-Fix-typo.-with-should-be-with.patchDownload
From 5ffb55b72c523d5dda462ffb7a11be97dbc3b712 Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 22 Apr 2025 13:38:24 +1000
Subject: [PATCH v3] DOCS - pg_walsummary. Fix typo. "with" should be "within"
---
doc/src/sgml/ref/pg_walsummary.sgml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/doc/src/sgml/ref/pg_walsummary.sgml b/doc/src/sgml/ref/pg_walsummary.sgml
index 57b2d24..5ffe07d 100644
--- a/doc/src/sgml/ref/pg_walsummary.sgml
+++ b/doc/src/sgml/ref/pg_walsummary.sgml
@@ -31,7 +31,7 @@ PostgreSQL documentation
<title>Description</title>
<para>
<application>pg_walsummary</application> 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 within the
<literal>pg_wal/summaries</literal> 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
--
1.8.3.1
v3-0005-DOCS-option-should-be-option.-and-make-it-always-.patchapplication/octet-stream; name=v3-0005-DOCS-option-should-be-option.-and-make-it-always-.patchDownload
From 1f43bfb88879e47c44fca73242a4076e5c2a9fff Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 22 Apr 2025 13:40:18 +1000
Subject: [PATCH v3] DOCS - [option] should be [option...] and make it always
first.
---
doc/src/sgml/ref/pg_controldata.sgml | 2 +-
doc/src/sgml/ref/pg_resetwal.sgml | 2 +-
doc/src/sgml/ref/pgupgrade.sgml | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml
index b47fdca..0eb0abc 100644
--- a/doc/src/sgml/ref/pg_controldata.sgml
+++ b/doc/src/sgml/ref/pg_controldata.sgml
@@ -22,7 +22,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_controldata</command>
- <arg choice="opt"><replaceable class="parameter">option</replaceable></arg>
+ <arg rep="repeat" choice="opt"><replaceable class="parameter">option</replaceable></arg>
<group choice="opt">
<group choice="opt">
<arg choice="plain"><option>-D</option></arg>
diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml
index dd011d2..cd465e4 100644
--- a/doc/src/sgml/ref/pg_resetwal.sgml
+++ b/doc/src/sgml/ref/pg_resetwal.sgml
@@ -22,6 +22,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_resetwal</command>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<group choice="opt">
<arg choice="plain"><option>-f</option></arg>
<arg choice="plain"><option>--force</option></arg>
@@ -30,7 +31,6 @@ PostgreSQL documentation
<arg choice="plain"><option>-n</option></arg>
<arg choice="plain"><option>--dry-run</option></arg>
</group>
- <arg rep="repeat"><replaceable>option</replaceable></arg>
<group choice="plain">
<group choice="opt">
<arg choice="plain"><option>-D</option></arg>
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index df13365..0a777ef 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -22,6 +22,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_upgrade</command>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
<arg choice="plain"><option>-b</option></arg>
<arg choice="plain"><replaceable>oldbindir</replaceable></arg>
<arg choice="opt"><option>-B</option> <replaceable>newbindir</replaceable></arg>
@@ -29,7 +30,6 @@ PostgreSQL documentation
<arg choice="plain"><replaceable>oldconfigdir</replaceable></arg>
<arg choice="plain"><option>-D</option></arg>
<arg choice="plain"><replaceable>newconfigdir</replaceable></arg>
- <arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
--
1.8.3.1
v3-0007-DOCS-docguide.-Added-some-new-style-guidelines-fo.patchapplication/octet-stream; name=v3-0007-DOCS-docguide.-Added-some-new-style-guidelines-fo.patchDownload
From dd0179c37b6dd1496a86c8fdbaa77415f6f95fac Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 22 Apr 2025 13:41:32 +1000
Subject: [PATCH v3] DOCS - docguide. Added some new style guidelines for the
reference pages
---
doc/src/sgml/docguide.sgml | 13 +++++++++++++
1 file changed, 13 insertions(+)
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index db4bcce..e27e58d 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -516,6 +516,19 @@ 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.
</para>
+
+ <para>
+ Below are some addtional recommendations for an application synopsis:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Options that are common across multiple applications should also
+ have consistent argument names. For example,
+ <replaceable>datadir</replaceable> and <replaceable>filename</replaceable>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
</listitem>
</varlistentry>
--
1.8.3.1
v3-0006-DOCS-pg_controldata-should-have-Option-section-wi.patchapplication/octet-stream; name=v3-0006-DOCS-pg_controldata-should-have-Option-section-wi.patchDownload
From 9f385445473405b875938951dee82d458534530e Mon Sep 17 00:00:00 2001
From: Peter Smith <peter.b.smith@fujitsu.com>
Date: Tue, 22 Apr 2025 13:40:56 +1000
Subject: [PATCH v3] DOCS - pg_controldata should have Option section with
descriptions for -D and -V and -? options.
---
doc/src/sgml/ref/pg_controldata.sgml | 47 ++++++++++++++++++++++++++++++++----
1 file changed, 42 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml
index 0eb0abc..e890967 100644
--- a/doc/src/sgml/ref/pg_controldata.sgml
+++ b/doc/src/sgml/ref/pg_controldata.sgml
@@ -47,15 +47,52 @@ PostgreSQL documentation
This utility can only be run by the user who initialized the cluster because
it requires read access to the data directory.
You can specify the data directory on the command line, or use
- the environment variable <envar>PGDATA</envar>. This utility supports the options
- <option>-V</option> and <option>--version</option>, which print the
- <application>pg_controldata</application> version and exit. It also
- supports options <option>-?</option> and <option>--help</option>, which output the
- supported arguments.
+ the environment variable <envar>PGDATA</envar>.
</para>
</refsect1>
<refsect1>
+ <title>Options</title>
+
+ <para>
+ The following command-line options are available:
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-D <replaceable>datadir</replaceable></option></term>
+ <term><option>--pgdata=<replaceable>datadir</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the location of the database directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-V</option></term>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>
+ Print the <application>pg_controldata</application> version and exit.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-?</option></term>
+ <term><option>--help</option></term>
+ <listitem>
+ <para>
+ Show help about <application>pg_controldata</application> command line
+ arguments, and exit.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1>
<title>Environment</title>
<variablelist>
--
1.8.3.1