Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 7bfd75c

Browse files
author
Commitfest Bot
committed
[CF 5647] v3 - DOCS: Make the Server Application docs synopses more consistent
This branch was automatically generated by a robot using patches from an email thread registered at: https://commitfest.postgresql.org/patch/5647 The branch will be overwritten each time a new patch version is posted to the thread, and also periodically to check for bitrot caused by changes on the master branch. Patch(es): https://www.postgresql.org/message-id/CAHut+Pv_hArN-xGu3tpw507=pZnYU2LktpD=C7vPkQxQ7Afs6w@mail.gmail.com Author(s): Peter Smith
2 parents 0d4dad2 + bf806a2 commit 7bfd75c

10 files changed

+84
-24
lines changed

‎doc/src/sgml/docguide.sgml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -516,6 +516,19 @@ LOGLEVEL=-Dorg.apache.commons.logging.simplelog.defaultlog=WARN
516516
that is done below. Instead, list the major components of the
517517
command line, such as where input and output files go.
518518
</para>
519+
520+
<para>
521+
Below are some addtional recommendations for an application synopsis:
522+
<itemizedlist>
523+
<listitem>
524+
<para>
525+
Options that are common across multiple applications should also
526+
have consistent argument names. For example,
527+
<replaceable>datadir</replaceable> and <replaceable>filename</replaceable>.
528+
</para>
529+
</listitem>
530+
</itemizedlist>
531+
</para>
519532
</listitem>
520533
</varlistentry>
521534

‎doc/src/sgml/ref/initdb.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ PostgreSQL documentation
2828
<arg choice="plain"><option>--pgdata</option></arg>
2929
<arg choice="plain"><option>-D</option></arg>
3030
</group>
31-
<replaceable> directory</replaceable>
31+
<replaceable> datadir</replaceable>
3232
</group>
3333
</cmdsynopsis>
3434
</refsynopsisdiv>
@@ -190,8 +190,8 @@ PostgreSQL documentation
190190
</varlistentry>
191191

192192
<varlistentry id="app-initdb-option-pgdata">
193-
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
194-
<term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
193+
<term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
194+
<term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
195195
<listitem>
196196
<para>
197197
This option specifies the directory where the database cluster

‎doc/src/sgml/ref/pg_checksums.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,8 @@ PostgreSQL documentation
6161

6262
<variablelist>
6363
<varlistentry>
64-
<term><option>-D <replaceable>directory</replaceable></option></term>
65-
<term><option>--pgdata=<replaceable>directory</replaceable></option></term>
64+
<term><option>-D <replaceable>datadir</replaceable></option></term>
65+
<term><option>--pgdata=<replaceable>datadir</replaceable></option></term>
6666
<listitem>
6767
<para>
6868
Specifies the directory where the database cluster is stored.

‎doc/src/sgml/ref/pg_controldata.sgml

Lines changed: 43 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<cmdsynopsis>
2424
<command>pg_controldata</command>
25-
<arg choice="opt"><replaceable class="parameter">option</replaceable></arg>
25+
<arg rep="repeat" choice="opt"><replaceable class="parameter">option</replaceable></arg>
2626
<group choice="opt">
2727
<group choice="opt">
2828
<arg choice="plain"><option>-D</option></arg>
@@ -47,14 +47,51 @@ PostgreSQL documentation
4747
This utility can only be run by the user who initialized the cluster because
4848
it requires read access to the data directory.
4949
You can specify the data directory on the command line, or use
50-
the environment variable <envar>PGDATA</envar>. This utility supports the options
51-
<option>-V</option> and <option>--version</option>, which print the
52-
<application>pg_controldata</application> version and exit. It also
53-
supports options <option>-?</option> and <option>--help</option>, which output the
54-
supported arguments.
50+
the environment variable <envar>PGDATA</envar>.
5551
</para>
5652
</refsect1>
5753

54+
<refsect1>
55+
<title>Options</title>
56+
57+
<para>
58+
The following command-line options are available:
59+
60+
<variablelist>
61+
<varlistentry>
62+
<term><option>-D <replaceable>datadir</replaceable></option></term>
63+
<term><option>--pgdata=<replaceable>datadir</replaceable></option></term>
64+
<listitem>
65+
<para>
66+
Specifies the location of the database directory.
67+
</para>
68+
</listitem>
69+
</varlistentry>
70+
71+
<varlistentry>
72+
<term><option>-V</option></term>
73+
<term><option>--version</option></term>
74+
<listitem>
75+
<para>
76+
Print the <application>pg_controldata</application> version and exit.
77+
</para>
78+
</listitem>
79+
</varlistentry>
80+
81+
<varlistentry>
82+
<term><option>-?</option></term>
83+
<term><option>--help</option></term>
84+
<listitem>
85+
<para>
86+
Show help about <application>pg_controldata</application> command line
87+
arguments, and exit.
88+
</para>
89+
</listitem>
90+
</varlistentry>
91+
</variablelist>
92+
</para>
93+
</refsect1>
94+
5895
<refsect1>
5996
<title>Environment</title>
6097

‎doc/src/sgml/ref/pg_createsubscriber.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -126,8 +126,8 @@ PostgreSQL documentation
126126
</varlistentry>
127127

128128
<varlistentry>
129-
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
130-
<term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
129+
<term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
130+
<term><option>--pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
131131
<listitem>
132132
<para>
133133
The target directory that contains a cluster directory from a physical

‎doc/src/sgml/ref/pg_resetwal.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<cmdsynopsis>
2424
<command>pg_resetwal</command>
25+
<arg rep="repeat"><replaceable>option</replaceable></arg>
2526
<group choice="opt">
2627
<arg choice="plain"><option>-f</option></arg>
2728
<arg choice="plain"><option>--force</option></arg>
@@ -30,7 +31,6 @@ PostgreSQL documentation
3031
<arg choice="plain"><option>-n</option></arg>
3132
<arg choice="plain"><option>--dry-run</option></arg>
3233
</group>
33-
<arg rep="repeat"><replaceable>option</replaceable></arg>
3434
<group choice="plain">
3535
<group choice="opt">
3636
<arg choice="plain"><option>-D</option></arg>

‎doc/src/sgml/ref/pg_rewind.sgml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,9 @@ PostgreSQL documentation
2828
<arg choice="plain"><option>-D</option></arg>
2929
<arg choice="plain"><option>--target-pgdata</option></arg>
3030
</group>
31-
<replaceable> directory</replaceable>
31+
<replaceable> datadir</replaceable>
3232
<group choice="req">
33-
<arg choice="plain"><option>--source-pgdata=<replaceable>directory</replaceable></option></arg>
33+
<arg choice="plain"><option>--source-pgdata=<replaceable>datadir</replaceable></option></arg>
3434
<arg choice="plain"><option>--source-server=<replaceable>connstr</replaceable></option></arg>
3535
</group>
3636
</group>
@@ -142,8 +142,8 @@ PostgreSQL documentation
142142

143143
<variablelist>
144144
<varlistentry>
145-
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
146-
<term><option>--target-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
145+
<term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
146+
<term><option>--target-pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
147147
<listitem>
148148
<para>
149149
This option specifies the target data directory that is synchronized
@@ -154,7 +154,7 @@ PostgreSQL documentation
154154
</varlistentry>
155155

156156
<varlistentry>
157-
<term><option>--source-pgdata=<replaceable class="parameter">directory</replaceable></option></term>
157+
<term><option>--source-pgdata=<replaceable class="parameter">datadir</replaceable></option></term>
158158
<listitem>
159159
<para>
160160
Specifies the file system path to the data directory of the source

‎doc/src/sgml/ref/pg_waldump.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<cmdsynopsis>
2424
<command>pg_waldump</command>
25-
<arg rep="repeat" choice="opt"><option>option</option></arg>
26-
<arg choice="opt"><option>startseg</option><arg choice="opt"><option>endseg</option></arg></arg>
25+
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
26+
<arg choice="opt"><replaceable>startseg</replaceable><arg choice="opt"><replaceable>endseg</replaceable></arg></arg>
2727
</cmdsynopsis>
2828
</refsynopsisdiv>
2929

‎doc/src/sgml/ref/pg_walsummary.sgml

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,15 @@ PostgreSQL documentation
2323
<cmdsynopsis>
2424
<command>pg_walsummary</command>
2525
<arg rep="repeat" choice="opt"><replaceable>option</replaceable></arg>
26-
<arg rep="repeat"><replaceable>file</replaceable></arg>
26+
<arg rep="repeat"><replaceable>filename</replaceable></arg>
2727
</cmdsynopsis>
2828
</refsynopsisdiv>
2929

3030
<refsect1>
3131
<title>Description</title>
3232
<para>
3333
<application>pg_walsummary</application> is used to print the contents of
34-
WAL summary files. These binary files are found with the
34+
WAL summary files. These binary files are found within the
3535
<literal>pg_wal/summaries</literal> subdirectory of the data directory,
3636
and can be converted to text using this tool. This is not ordinarily
3737
necessary, since WAL summary files primarily exist to support
@@ -56,6 +56,16 @@ PostgreSQL documentation
5656

5757
<para>
5858
<variablelist>
59+
<varlistentry>
60+
<term><replaceable class="parameter">filename</replaceable></term>
61+
<listitem>
62+
<para>
63+
A binary WAL summary file, found within the <literal>pg_wal/summaries</literal>
64+
subdirectory of the data directory.
65+
</para>
66+
</listitem>
67+
</varlistentry>
68+
5969
<varlistentry>
6070
<term><option>-i</option></term>
6171
<term><option>--individual</option></term>

‎doc/src/sgml/ref/pgupgrade.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,14 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<cmdsynopsis>
2424
<command>pg_upgrade</command>
25+
<arg rep="repeat"><replaceable>option</replaceable></arg>
2526
<arg choice="plain"><option>-b</option></arg>
2627
<arg choice="plain"><replaceable>oldbindir</replaceable></arg>
2728
<arg choice="opt"><option>-B</option> <replaceable>newbindir</replaceable></arg>
2829
<arg choice="plain"><option>-d</option></arg>
2930
<arg choice="plain"><replaceable>oldconfigdir</replaceable></arg>
3031
<arg choice="plain"><option>-D</option></arg>
3132
<arg choice="plain"><replaceable>newconfigdir</replaceable></arg>
32-
<arg rep="repeat"><replaceable>option</replaceable></arg>
3333
</cmdsynopsis>
3434
</refsynopsisdiv>
3535

0 commit comments

Comments
 (0)