Skip to content

Commit 953c64e

Browse files
bmomjianbmomjian
committed
doc: add commas after 'i.e.' and 'e.g.'
This follows the American format, https://jakubmarian.com/comma-after-i-e-and-e-g/. There is no intention of requiring this format for future text, but making existing text consistent every few years makes sense. Discussion: https://postgr.es/m/20200825183619.GA22369@momjian.us Backpatch-through: 9.5
1 parent 50ed605 commit 953c64e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+103
-103
lines changed

‎doc/src/sgml/bki.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -459,7 +459,7 @@
459459
Use of symbolic references is enabled in a particular catalog column
460460
by attaching <literal>BKI_LOOKUP(<replaceable>lookuprule</replaceable>)</literal>
461461
to the column's definition, where <replaceable>lookuprule</replaceable>
462-
is the name of the referenced catalog, e.g. <literal>pg_proc</literal>.
462+
is the name of the referenced catalog, e.g., <literal>pg_proc</literal>.
463463
<literal>BKI_LOOKUP</literal> can be attached to columns of
464464
type <type>Oid</type>, <type>regproc</type>, <type>oidvector</type>,
465465
or <type>Oid[]</type>; in the latter two cases it implies performing a

‎doc/src/sgml/config.sgml

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -424,7 +424,7 @@ include_dir 'directory'
424424
start with the <literal>.</literal> character are also ignored, to
425425
prevent mistakes since such files are hidden on some platforms. Multiple
426426
files within an include directory are processed in file name order
427-
(according to C locale rules, i.e. numbers before letters, and
427+
(according to C locale rules, i.e., numbers before letters, and
428428
uppercase letters before lowercase ones).
429429
</para>
430430

@@ -1085,7 +1085,7 @@ include_dir 'conf.d'
10851085
<para>
10861086
With this parameter enabled, you can still create ordinary global
10871087
users. Simply append <literal>@</literal> when specifying the user
1088-
name in the client, e.g. <literal>joe@</literal>. The <literal>@</literal>
1088+
name in the client, e.g., <literal>joe@</literal>. The <literal>@</literal>
10891089
will be stripped off before the user name is looked up by the
10901090
server.
10911091
</para>
@@ -3319,7 +3319,7 @@ include_dir 'conf.d'
33193319
disabled, but the server continues to accumulate WAL segment files in
33203320
the expectation that a command will soon be provided. Setting
33213321
<varname>archive_command</varname> to a command that does nothing but
3322-
return true, e.g. <literal>/bin/true</literal> (<literal>REM</literal> on
3322+
return true, e.g., <literal>/bin/true</literal> (<literal>REM</literal> on
33233323
Windows), effectively disables
33243324
archiving, but also breaks the chain of WAL files needed for
33253325
archive recovery, so it should only be used in unusual circumstances.
@@ -3564,7 +3564,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
35643564
<listitem>
35653565
<para>
35663566
This parameter specifies that recovery should end as soon as a
3567-
consistent state is reached, i.e. as early as possible. When restoring
3567+
consistent state is reached, i.e., as early as possible. When restoring
35683568
from an online backup, this means the point where taking the backup
35693569
ended.
35703570
</para>
@@ -3610,7 +3610,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
36103610
<xref linkend="guc-timezone-abbreviations"/> variable has been set
36113611
earlier in the configuration file). Preferred style is to use a
36123612
numeric offset from UTC, or you can write a full time zone name,
3613-
e.g. <literal>Europe/Helsinki</literal> not <literal>EEST</literal>.
3613+
e.g., <literal>Europe/Helsinki</literal> not <literal>EEST</literal>.
36143614
</para>
36153615
</listitem>
36163616
</varlistentry>
@@ -4992,7 +4992,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
49924992
if your data is likely to be completely in cache, such as when
49934993
the database is smaller than the total server memory, decreasing
49944994
random_page_cost can be appropriate. Storage that has a low random
4995-
read cost relative to sequential, e.g. solid-state drives, might
4995+
read cost relative to sequential, e.g., solid-state drives, might
49964996
also be better modeled with a lower value for random_page_cost,
49974997
e.g., <literal>1.1</literal>.
49984998
</para>
@@ -9084,7 +9084,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
90849084
rows that can be locked; that value is unlimited. The default,
90859085
64, has historically proven sufficient, but you might need to
90869086
raise this value if you have queries that touch many different
9087-
tables in a single transaction, e.g. query of a parent table with
9087+
tables in a single transaction, e.g., query of a parent table with
90889088
many children. This parameter can only be set at server start.
90899089
</para>
90909090

@@ -9580,7 +9580,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
95809580
with assertions enabled. That is the case if the
95819581
macro <symbol>USE_ASSERT_CHECKING</symbol> is defined
95829582
when <productname>PostgreSQL</productname> is built (accomplished
9583-
e.g. by the <command>configure</command> option
9583+
e.g., by the <command>configure</command> option
95849584
<option>--enable-cassert</option>). By
95859585
default <productname>PostgreSQL</productname> is built without
95869586
assertions.

‎doc/src/sgml/datatype.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -520,7 +520,7 @@
520520
very large number of digits. It is especially recommended for
521521
storing monetary amounts and other quantities where exactness is
522522
required. Calculations with <type>numeric</type> values yield exact
523-
results where possible, e.g. addition, subtraction, multiplication.
523+
results where possible, e.g., addition, subtraction, multiplication.
524524
However, calculations on <type>numeric</type> values are very slow
525525
compared to the integer types, or to the floating-point types
526526
described in the next section.
@@ -5105,7 +5105,7 @@ SELECT * FROM pg_attribute
51055105

51065106
<row>
51075107
<entry><type>unknown</type></entry>
5108-
<entry>Identifies a not-yet-resolved type, e.g. of an undecorated
5108+
<entry>Identifies a not-yet-resolved type, e.g., of an undecorated
51095109
string literal.</entry>
51105110
</row>
51115111
</tbody>

‎doc/src/sgml/ddl.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1338,7 +1338,7 @@ ALTER TABLE products ADD COLUMN description text;
13381338
</para>
13391339

13401340
<para>
1341-
However, if the default value is volatile (e.g.
1341+
However, if the default value is volatile (e.g.,
13421342
<function>clock_timestamp()</function>)
13431343
each row will need to be updated with the value calculated at the time
13441344
<command>ALTER TABLE</command> is executed. To avoid a potentially
@@ -1833,7 +1833,7 @@ REVOKE ALL ON accounts FROM PUBLIC;
18331833
schema (assuming that the objects' own privilege requirements are
18341834
also met). Essentially this allows the grantee to <quote>look up</quote>
18351835
objects within the schema. Without this permission, it is still
1836-
possible to see the object names, e.g. by querying system catalogs.
1836+
possible to see the object names, e.g., by querying system catalogs.
18371837
Also, after revoking this permission, existing sessions might have
18381838
statements that have previously performed this lookup, so this is not
18391839
a completely secure way to prevent object access.

‎doc/src/sgml/ecpg.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3689,7 +3689,7 @@ EXEC SQL DEALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
36893689
EXEC SQL FETCH NEXT FROM mycursor INTO SQL DESCRIPTOR mydesc;
36903690
</programlisting>
36913691
If the result set is empty, the Descriptor Area will still contain
3692-
the metadata from the query, i.e. the field names.
3692+
the metadata from the query, i.e., the field names.
36933693
</para>
36943694

36953695
<para>
@@ -4106,7 +4106,7 @@ typedef struct sqlvar_struct sqlvar_t;
41064106
<term><literal>sqllen</literal></term>
41074107
<listitem>
41084108
<para>
4109-
Contains the binary length of the field. e.g. 4 bytes for <type>ECPGt_int</type>.
4109+
Contains the binary length of the field. e.g., 4 bytes for <type>ECPGt_int</type>.
41104110
</para>
41114111
</listitem>
41124112
</varlistentry>
@@ -8062,7 +8062,7 @@ EXEC SQL CLOSE DATABASE;
80628062
<term><literal>FREE cursor_name</literal></term>
80638063
<listitem>
80648064
<para>
8065-
Due to the differences how ECPG works compared to Informix's ESQL/C (i.e. which steps
8065+
Due to the differences how ECPG works compared to Informix's ESQL/C (i.e., which steps
80668066
are purely grammar transformations and which steps rely on the underlying run-time library)
80678067
there is no <literal>FREE cursor_name</literal> statement in ECPG. This is because in ECPG,
80688068
<literal>DECLARE CURSOR</literal> doesn't translate to a function call into

‎doc/src/sgml/extend.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -756,7 +756,7 @@ RETURNS anycompatible AS ...
756756
<para>
757757
An extension is <firstterm>relocatable</firstterm> if it is possible to move
758758
its contained objects into a different schema after initial creation
759-
of the extension. The default is <literal>false</literal>, i.e. the
759+
of the extension. The default is <literal>false</literal>, i.e., the
760760
extension is not relocatable.
761761
See <xref linkend="extend-extensions-relocation"/> for more information.
762762
</para>
@@ -1645,7 +1645,7 @@ include $(PGXS)
16451645
<term><varname>NO_INSTALLCHECK</varname></term>
16461646
<listitem>
16471647
<para>
1648-
don't define an <literal>installcheck</literal> target, useful e.g. if tests require special configuration, or don't use <application>pg_regress</application>
1648+
don't define an <literal>installcheck</literal> target, useful e.g., if tests require special configuration, or don't use <application>pg_regress</application>
16491649
</para>
16501650
</listitem>
16511651
</varlistentry>

‎doc/src/sgml/func.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7642,9 +7642,9 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
76427642
<listitem>
76437643
<para>
76447644
In <function>to_timestamp</function> and <function>to_date</function>,
7645-
if the year format specification is less than four digits, e.g.
7645+
if the year format specification is less than four digits, e.g.,
76467646
<literal>YYY</literal>, and the supplied year is less than four digits,
7647-
the year will be adjusted to be nearest to the year 2020, e.g.
7647+
the year will be adjusted to be nearest to the year 2020, e.g.,
76487648
<literal>95</literal> becomes 1995.
76497649
</para>
76507650
</listitem>
@@ -26386,7 +26386,7 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
2638626386
<row>
2638726387
<entry><literal>objsubid</literal></entry>
2638826388
<entry><type>integer</type></entry>
26389-
<entry>Sub-object ID (e.g. attribute number for a column)</entry>
26389+
<entry>Sub-object ID (e.g., attribute number for a column)</entry>
2639026390
</row>
2639126391
<row>
2639226392
<entry><literal>command_tag</literal></entry>
@@ -26476,7 +26476,7 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger();
2647626476
<row>
2647726477
<entry><literal>objsubid</literal></entry>
2647826478
<entry><type>integer</type></entry>
26479-
<entry>Sub-object ID (e.g. attribute number for a column)</entry>
26479+
<entry>Sub-object ID (e.g., attribute number for a column)</entry>
2648026480
</row>
2648126481
<row>
2648226482
<entry><literal>original</literal></entry>

‎doc/src/sgml/glossary.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -708,7 +708,7 @@
708708
<glossdef>
709709
<para>
710710
Contains the values of <glossterm linkend="glossary-tuple">row</glossterm>
711-
attributes (i.e. the data) for a
711+
attributes (i.e., the data) for a
712712
<glossterm linkend="glossary-relation">relation</glossterm>.
713713
The heap is realized within one or more
714714
<glossterm linkend="glossary-file-segment">file segments</glossterm>

‎doc/src/sgml/high-availability.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ protocol to make nodes agree on a serializable transactional order.
219219
this is unacceptable, either the middleware or the application
220220
must query such values from a single server and then use those
221221
values in write queries. Another option is to use this replication
222-
option with a traditional primary-standby setup, i.e. data modification
222+
option with a traditional primary-standby setup, i.e., data modification
223223
queries are sent only to the primary and are propagated to the
224224
standby servers via primary-standby replication, not by the replication
225225
middleware. Care must also be taken that all
@@ -662,7 +662,7 @@ protocol to make nodes agree on a serializable transactional order.
662662
Set up continuous archiving on the primary to an archive directory
663663
accessible from the standby, as described
664664
in <xref linkend="continuous-archiving"/>. The archive location should be
665-
accessible from the standby even when the primary is down, i.e. it should
665+
accessible from the standby even when the primary is down, i.e., it should
666666
reside on the standby server itself or another trusted server, not on
667667
the primary server.
668668
</para>
@@ -2232,7 +2232,7 @@ LOG: database system is ready to accept read only connections
22322232
<itemizedlist>
22332233
<listitem>
22342234
<para>
2235-
Data Definition Language (DDL): e.g. <command>CREATE INDEX</command>
2235+
Data Definition Language (DDL): e.g., <command>CREATE INDEX</command>
22362236
</para>
22372237
</listitem>
22382238
<listitem>
@@ -2298,7 +2298,7 @@ LOG: database system is ready to accept read only connections
22982298

22992299
<para>
23002300
WAL file control commands will not work during recovery,
2301-
e.g. <function>pg_start_backup</function>, <function>pg_switch_wal</function> etc.
2301+
e.g., <function>pg_start_backup</function>, <function>pg_switch_wal</function> etc.
23022302
</para>
23032303

23042304
<para>

‎doc/src/sgml/indexam.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -386,7 +386,7 @@ amcanreturn (Relation indexRelation, int attno);
386386
linkend="indexes-index-only-scans"><firstterm>index-only scans</firstterm></link> on
387387
the given column, by returning the indexed column values for an index entry
388388
in the form of an <structname>IndexTuple</structname>. The attribute number
389-
is 1-based, i.e. the first column's attno is 1. Returns true if supported,
389+
is 1-based, i.e., the first column's attno is 1. Returns true if supported,
390390
else false. If the access method does not support index-only scans at all,
391391
the <structfield>amcanreturn</structfield> field in its <structname>IndexAmRoutine</structname>
392392
struct can be set to NULL.

‎doc/src/sgml/install-windows.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@
117117
same purpose.
118118
From the <application>Visual Studio Command Prompt</application>, you can
119119
change the targeted CPU architecture, build type, and target OS by using the
120-
<command>vcvarsall.bat</command> command, e.g.
120+
<command>vcvarsall.bat</command> command, e.g.,
121121
<command>vcvarsall.bat x64 10.0.10240.0</command> to target Windows 10
122122
with a 64-bit release build. See <command>-help</command> for the other
123123
options of <command>vcvarsall.bat</command>. All commands should be run from
@@ -250,7 +250,7 @@ $ENV{MSBFLAGS}="/m";
250250
installations <filename>C:\Program Files\GnuWin32</filename>.
251251
Consider installing into <filename>C:\GnuWin32</filename> or use the
252252
NTFS short name path to GnuWin32 in your PATH environment setting
253-
(e.g. <filename>C:\PROGRA~1\GnuWin32</filename>).
253+
(e.g., <filename>C:\PROGRA~1\GnuWin32</filename>).
254254
</para>
255255
</note>
256256

‎doc/src/sgml/libpq.sgml

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -355,7 +355,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
355355
Conversely, if <function>PQconnectPoll(conn)</function> last returned
356356
<symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
357357
to write, then call <function>PQconnectPoll(conn)</function> again.
358-
On the first iteration, i.e. if you have yet to call
358+
On the first iteration, i.e., if you have yet to call
359359
<function>PQconnectPoll</function>, behave as if it last returned
360360
<symbol>PGRES_POLLING_WRITING</symbol>. Continue this loop until
361361
<function>PQconnectPoll(conn)</function> returns
@@ -994,7 +994,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
994994
<literal>hostaddr</literal>, and <literal>port</literal> options accept a comma-separated
995995
list of values. The same number of elements must be given in each
996996
option that is specified, such
997-
that e.g. the first <literal>hostaddr</literal> corresponds to the first host name,
997+
that e.g., the first <literal>hostaddr</literal> corresponds to the first host name,
998998
the second <literal>hostaddr</literal> corresponds to the second host name, and so
999999
forth. As an exception, if only one <literal>port</literal> is specified, it
10001000
applies to all the hosts.
@@ -1022,7 +1022,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
10221022
<para>
10231023
If a password file is used, you can have different passwords for
10241024
different hosts. All the other connection options are the same for every
1025-
host in the list; it is not possible to e.g. specify different
1025+
host in the list; it is not possible to e.g., specify different
10261026
usernames for different hosts.
10271027
</para>
10281028
</sect3>
@@ -1227,7 +1227,7 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
12271227
<listitem>
12281228
<para>
12291229
Maximum wait for connection, in seconds (write as a decimal integer,
1230-
e.g. <literal>10</literal>). Zero, negative, or not specified means
1230+
e.g., <literal>10</literal>). Zero, negative, or not specified means
12311231
wait indefinitely. The minimum allowed timeout is 2 seconds, therefore
12321232
a value of <literal>1</literal> is interpreted as <literal>2</literal>.
12331233
This timeout applies separately to each host name or IP address.
@@ -2426,7 +2426,7 @@ const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
24262426
<term><literal>cipher</literal></term>
24272427
<listitem>
24282428
<para>
2429-
A short name of the ciphersuite used, e.g.
2429+
A short name of the ciphersuite used, e.g.,
24302430
<literal>"DHE-RSA-DES-CBC3-SHA"</literal>. The names are specific
24312431
to each SSL implementation.
24322432
</para>
@@ -4821,7 +4821,7 @@ int PQflush(PGconn *conn);
48214821
<xref linkend="libpq-PQflush"/> again. Repeat until
48224822
<xref linkend="libpq-PQflush"/> returns 0. (It is necessary to check for
48234823
read-ready and drain the input with <xref linkend="libpq-PQconsumeInput"/>,
4824-
because the server can block trying to send us data, e.g. NOTICE
4824+
because the server can block trying to send us data, e.g., NOTICE
48254825
messages, and won't read our data until we read its.) Once
48264826
<xref linkend="libpq-PQflush"/> returns 0, wait for the socket to be
48274827
read-ready and then read the response as described above.
@@ -7737,7 +7737,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
77377737
For a connection to be known SSL-secured, SSL usage must be configured
77387738
on <emphasis>both the client and the server</emphasis> before the connection
77397739
is made. If it is only configured on the server, the client may end up
7740-
sending sensitive information (e.g. passwords) before
7740+
sending sensitive information (e.g., passwords) before
77417741
it knows that the server requires high security. In libpq, secure
77427742
connections can be ensured
77437743
by setting the <literal>sslmode</literal> parameter to <literal>verify-full</literal> or

‎doc/src/sgml/logicaldecoding.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -882,7 +882,7 @@ OutputPluginWrite(ctx, true);
882882
<title>Streaming of Large Transactions for Logical Decoding</title>
883883

884884
<para>
885-
The basic output plugin callbacks (e.g. <function>begin_cb</function>,
885+
The basic output plugin callbacks (e.g., <function>begin_cb</function>,
886886
<function>change_cb</function>, <function>commit_cb</function> and
887887
<function>message_cb</function>) are only invoked when the transaction
888888
actually commits. The changes are still decoded from the transaction
@@ -958,7 +958,7 @@ stream_commit_cb(...); &lt;-- commit of the streamed transaction
958958
currently used for decoded changes) is selected and streamed. However, in
959959
some cases we still have to spill to the disk even if streaming is enabled
960960
because if we cross the memory limit but we still have not decoded the
961-
complete tuple e.g. only decoded toast table insert but not the main table
961+
complete tuple e.g., only decoded toast table insert but not the main table
962962
insert.
963963
</para>
964964

‎doc/src/sgml/monitoring.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
206206
When the server shuts down cleanly, a permanent copy of the statistics
207207
data is stored in the <filename>pg_stat</filename> subdirectory, so that
208208
statistics can be retained across server restarts. When recovery is
209-
performed at server start (e.g. after immediate shutdown, server crash,
209+
performed at server start (e.g., after immediate shutdown, server crash,
210210
and point-in-time recovery), all statistics counters are reset.
211211
</para>
212212

0 commit comments

Comments
 (0)