"an SQL" vs. "a SQL"
I thought it might be worth having this conversation before we branch for v15.
It seems we have no standard as to if we say "a SQL" or "an SQL".
Personally, I pronounce the language as es-que-ell, so I'd write "an
SQL". If you say "sequel", then you'll think differently. The reason
I do this is that the language was only briefly named sequel but was
renamed to SQL. For me calling it sequel seems wrong or out-dated. End
of personal opinion.
Let this thread not become the place where you tell me why I'm wrong.
Let's just get some consensus on something, make a change then move
on.
Overall we seem to mostly write "a SQL".
~/pg_src$ git grep -E "\s(a|A)\sSQL\s" | wc -l
855
~/pg_src$ git grep -E "\s(an|An)\sSQL\s" | wc -l
295
However, we mostly use "an SQL" in the docs.
~/pg_src$ cd doc/
~/pg_src/doc$ git grep -E "\s(a|A)\sSQL\s" | wc -l
55
~/pg_src/doc$ git grep -E "\s(an|An)\sSQL\s" | wc -l
94
I think we should change all 55 instances of "a SQL" in the docs to
use "an SQL" and leave the 800 other instances of "a SQL" alone.
Changing those does not seem worthwhile as it could cause
back-patching pain.
I mostly think that because of the fact that my personal opinion
agrees with the majority of instances in the docs. Makes more sense to
change 55 places than 94 places.
Interesting reading:
http://patorjk.com/blog/2012/01/26/pronouncing-sql-s-q-l-or-sequel/
Further, there might be a few more in the docs that we might want to
consider changing:
git grep -E "\sa\s(A|E|F|H|I|L|M|N|O|S|X)[A-Z]{2,5}\s"
I see "a FSM", "a FIFO", "a SSPI", "a SASL", "a MCV", "a SHA", "a SQLDA"
My regex foo is not strong enough to think how I might find multiline instances.
David
On 10.06.21 09:26, David Rowley wrote:
It seems we have no standard as to if we say "a SQL" or "an SQL".
The SQL standard uses "an SQL-something".
However, we mostly use "an SQL" in the docs.
~/pg_src$ cd doc/
~/pg_src/doc$ git grep -E "\s(a|A)\sSQL\s" | wc -l
55
~/pg_src/doc$ git grep -E "\s(an|An)\sSQL\s" | wc -l
94I think we should change all 55 instances of "a SQL" in the docs to
use "an SQL" and leave the 800 other instances of "a SQL" alone.
Changing those does not seem worthwhile as it could cause
back-patching pain.
agreed
Further, there might be a few more in the docs that we might want to
consider changing:git grep -E "\sa\s(A|E|F|H|I|L|M|N|O|S|X)[A-Z]{2,5}\s"
I see "a FSM", "a FIFO", "a SSPI", "a SASL", "a MCV", "a SHA", "a SQLDA"
My regex foo is not strong enough to think how I might find multiline instances.
Um, of those, I pronounce FIFO, SASL, and SHA as words, with an "a" article.
On Thu, Jun 10, 2021 at 9:31 AM Peter Eisentraut <
peter.eisentraut@enterprisedb.com> wrote:
On 10.06.21 09:26, David Rowley wrote:
It seems we have no standard as to if we say "a SQL" or "an SQL".
The SQL standard uses "an SQL-something".
I use both commonly, but the argument for "an S-Q-L ..." is strong I think
- and I definitely think consistency is good.
However, we mostly use "an SQL" in the docs.
~/pg_src$ cd doc/
~/pg_src/doc$ git grep -E "\s(a|A)\sSQL\s" | wc -l
55
~/pg_src/doc$ git grep -E "\s(an|An)\sSQL\s" | wc -l
94I think we should change all 55 instances of "a SQL" in the docs to
use "an SQL" and leave the 800 other instances of "a SQL" alone.
Changing those does not seem worthwhile as it could cause
back-patching pain.agreed
+1 in general, though I would perhaps suggest extending to any user-visible
messages in the code. I don't think there's any point in messing with
comments etc. I'm not sure what that would do to the numbers though.
Further, there might be a few more in the docs that we might want to
consider changing:git grep -E "\sa\s(A|E|F|H|I|L|M|N|O|S|X)[A-Z]{2,5}\s"
I see "a FSM", "a FIFO", "a SSPI", "a SASL", "a MCV", "a SHA", "a SQLDA"
My regex foo is not strong enough to think how I might find multiline
instances.
Um, of those, I pronounce FIFO, SASL, and SHA as words, with an "a"
article.
Same here. I've never heard anyone try to pronounce SSPI, so I would expect
that to be "an SSPI ...". The other remaining ones (FSM, MCV & SQLDA) I
would also argue aren't pronounceable, so should use the "an" article.
--
Dave Page
Blog: https://pgsnake.blogspot.com
Twitter: @pgsnake
On 10 Jun 2021, at 10:54, Dave Page <dpage@pgadmin.org> wrote:
.. I would perhaps suggest extending to any user-visible messages in the code.
I agree, consistent language between docs and user-facing messages is
important.
--
Daniel Gustafsson https://vmware.com/
On Thu, 10 Jun 2021 at 20:58, Daniel Gustafsson <daniel@yesql.se> wrote:
On 10 Jun 2021, at 10:54, Dave Page <dpage@pgadmin.org> wrote:
.. I would perhaps suggest extending to any user-visible messages in the code.
I agree, consistent language between docs and user-facing messages is
important.
Yeah, agreed.
I came up with the attached patch.
The only additional abbreviation that I found to be incorrect that I'd
previously not mentioned was "SRF". I changed that to use "an".
I only found 4 error messages that needed to be updated. There's some
incorrect stuff remaining in a few README files which I couldn't
decide if I should update or not.
Most of the offenders away from the docs are the translator hint
comments and within the .po files themselves.
$ git grep -E "translator:.*(a|A)\sSQL" | wc -l
690
Only 816 instances of "a SQL" remain, so only 126 are not related to
translator hints or .po files.
Does anyone have any thoughts if the READMEs should be fixed up?
David
Attachments:
use_correct_article_with_vowel_sounding_abbreviations.patchapplication/octet-stream; name=use_correct_article_with_vowel_sounding_abbreviations.patchDownload
diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 951af49e9a..02f0489112 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -1462,7 +1462,7 @@ omicron bryanh guest1
<listitem>
<para>
Allows for mapping between system and database user names. See
- <xref linkend="auth-username-maps"/> for details. For a SSPI/Kerberos
+ <xref linkend="auth-username-maps"/> for details. For an SSPI/Kerberos
principal, such as <literal>username@EXAMPLE.COM</literal> (or, less
commonly, <literal>username/hostbased@EXAMPLE.COM</literal>), the
user name used for mapping is
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index d8c0fd3315..aa3e178240 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -51,7 +51,7 @@
In general, enclose the value in single quotes, doubling any single
quotes within the value. Quotes can usually be omitted if the value
is a simple number or identifier, however.
- (Values that match a SQL keyword require quoting in some contexts.)
+ (Values that match an SQL keyword require quoting in some contexts.)
</para>
</listitem>
@@ -222,7 +222,7 @@ shared_buffers = 128MB
<productname>PostgreSQL</productname> provides three SQL
commands to establish configuration defaults.
The already-mentioned <command>ALTER SYSTEM</command> command
- provides a SQL-accessible means of changing global defaults; it is
+ provides an SQL-accessible means of changing global defaults; it is
functionally equivalent to editing <filename>postgresql.conf</filename>.
In addition, there are two commands that allow setting of defaults
on a per-database or per-role basis:
@@ -9625,7 +9625,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
<literal>\'</literal>. However, use of <literal>\'</literal> creates security risks
because in some client character set encodings, there are multibyte
characters in which the last byte is numerically equivalent to ASCII
- <literal>\</literal>. If client-side code does escaping incorrectly then a
+ <literal>\</literal>. If client-side code does escaping incorrectly then an
SQL-injection attack is possible. This risk can be prevented by
making the server reject queries in which a quote mark appears to be
escaped by a backslash.
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 0e8ef958a9..de561cded1 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1538,7 +1538,7 @@ SELECT '\xDEADBEEF';
<para>
The reason that single quotes must be doubled, as shown
in <xref linkend="datatype-binary-sqlesc"/>, is that this
- is true for any string literal in a SQL command. The generic
+ is true for any string literal in an SQL command. The generic
string-literal parser consumes the outermost single quotes
and reduces any pair of single quotes to one data character.
What the <type>bytea</type> input function sees is just one
diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml
index bcf623117c..4ab38bcc99 100644
--- a/doc/src/sgml/dblink.sgml
+++ b/doc/src/sgml/dblink.sgml
@@ -1482,14 +1482,14 @@ dblink_get_result(text connname [, bool fail_on_error]) returns setof record
<title>Return Value</title>
<para>
- For an async query (that is, a SQL statement returning rows),
+ For an async query (that is, an SQL statement returning rows),
the function returns the row(s) produced by the query. To use this
function, you will need to specify the expected set of columns,
as previously discussed for <function>dblink</function>.
</para>
<para>
- For an async command (that is, a SQL statement not returning rows),
+ For an async command (that is, an SQL statement not returning rows),
the function returns a single row with a single text column containing
the command's status string. It is still necessary to specify that
the result will have a single text column in the calling <literal>FROM</literal>
@@ -1777,7 +1777,7 @@ dblink_build_sql_insert(text relname,
<para>
<function>dblink_build_sql_insert</function> can be useful in doing selective
replication of a local table to a remote database. It selects a row
- from the local table based on primary key, and then builds a SQL
+ from the local table based on primary key, and then builds an SQL
<command>INSERT</command> command that will duplicate that row, but with
the primary key values replaced by the values in the last argument.
(To make an exact copy of the row, just specify the same values for
@@ -1909,7 +1909,7 @@ dblink_build_sql_delete(text relname,
<para>
<function>dblink_build_sql_delete</function> can be useful in doing selective
- replication of a local table to a remote database. It builds a SQL
+ replication of a local table to a remote database. It builds an SQL
<command>DELETE</command> command that will delete the row with the given
primary key values.
</para>
@@ -2029,7 +2029,7 @@ dblink_build_sql_update(text relname,
<para>
<function>dblink_build_sql_update</function> can be useful in doing selective
replication of a local table to a remote database. It selects a row
- from the local table based on primary key, and then builds a SQL
+ from the local table based on primary key, and then builds an SQL
<command>UPDATE</command> command that will duplicate that row, but with
the primary key values replaced by the values in the last argument.
(To make an exact copy of the row, just specify the same values for
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index 86c078e17d..9d5505cb84 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -354,13 +354,13 @@ current=testdb1 (should be testdb1)
</para>
<para>
- The third option is to declare a SQL identifier linked to
+ The third option is to declare an SQL identifier linked to
the connection, for example:
<programlisting>
EXEC SQL AT <replaceable>connection-name</replaceable> DECLARE <replaceable>statement-name</replaceable> STATEMENT;
EXEC SQL PREPARE <replaceable>statement-name</replaceable> FROM :<replaceable>dyn-string</replaceable>;
</programlisting>
- Once you link a SQL identifier to a connection, you execute dynamic SQL
+ Once you link an SQL identifier to a connection, you execute dynamic SQL
without an AT clause. Note that this option behaves like preprocessor
directives, therefore the link is enabled only in the file.
</para>
@@ -1542,7 +1542,7 @@ EXEC SQL END DECLARE SECTION;
variables and vice-versa. However, when creating a statement ecpg does
not know the types of the columns, so that it cannot check if a C array
is input into a corresponding SQL-level array. When processing the
- output of a SQL statement, ecpg has the necessary information and thus
+ output of an SQL statement, ecpg has the necessary information and thus
checks if both are arrays.
</para>
@@ -4348,7 +4348,7 @@ switch (v.sqltype)
parameters to a prepared query are:
</para>
<step><simpara>Create a prepared query (prepared statement)</simpara></step>
- <step><simpara>Declare a sqlda_t structure as an input SQLDA.</simpara></step>
+ <step><simpara>Declare an sqlda_t structure as an input SQLDA.</simpara></step>
<step><simpara>Allocate memory area (as sqlda_t structure) for the input SQLDA.</simpara></step>
<step><simpara>Set (copy) input values in the allocated memory.</simpara></step>
<step><simpara>Open a cursor with specifying the input SQLDA.</simpara></step>
@@ -4630,7 +4630,7 @@ main(void)
EXEC SQL PREPARE stmt1 FROM :query;
EXEC SQL DECLARE cur1 CURSOR FOR stmt1;
- /* Create a SQLDA structure for an input parameter */
+ /* Create an SQLDA structure for an input parameter */
sqlda2 = (sqlda_t *)malloc(sizeof(sqlda_t) + sizeof(sqlvar_t));
memset(sqlda2, 0, sizeof(sqlda_t) + sizeof(sqlvar_t));
sqlda2->sqln = 2; /* a number of input variables */
@@ -6911,7 +6911,7 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
<title>Description</title>
<para>
- <command>DECLARE STATEMENT</command> declares a SQL statement identifier.
+ <command>DECLARE STATEMENT</command> declares an SQL statement identifier.
SQL statement identifier can be associated with the connection.
When the identifier is used by dynamic SQL statements, the statements
are executed using the associated connection.
@@ -6945,7 +6945,7 @@ EXEC SQL [ AT <replaceable class="parameter">connection_name</replaceable> ] DEC
<term><replaceable class="parameter">statement_name</replaceable></term>
<listitem>
<para>
- The name of a SQL statement identifier, either as an SQL identifier or a host variable.
+ The name of an SQL statement identifier, either as an SQL identifier or a host variable.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index dae5737574..e928894726 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -1441,7 +1441,7 @@ include $(PGXS)
and include the global <acronym>PGXS</acronym> makefile.
Here is an example that builds an extension module named
<literal>isbn_issn</literal>, consisting of a shared library containing
- some C code, an extension control file, a SQL script, an include file
+ some C code, an extension control file, an SQL script, an include file
(only needed if other modules might need to access the extension functions
without going via SQL), and a documentation text file:
<programlisting>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 08b07f561e..fbc80c1403 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -15196,7 +15196,7 @@ table2-mapping
<returnvalue>json</returnvalue>
</para>
<para>
- Converts a SQL array to a JSON array. The behavior is the same
+ Converts an SQL array to a JSON array. The behavior is the same
as <function>to_json</function> except that line feeds will be added
between top-level array elements if the optional boolean parameter is
true.
@@ -15216,7 +15216,7 @@ table2-mapping
<returnvalue>json</returnvalue>
</para>
<para>
- Converts a SQL composite value to a JSON object. The behavior is the
+ Converts an SQL composite value to a JSON object. The behavior is the
same as <function>to_json</function> except that line feeds will be
added between top-level elements if the optional boolean parameter is
true.
@@ -15629,7 +15629,7 @@ table2-mapping
<itemizedlist spacing="compact">
<listitem>
<para>
- A JSON null value is converted to a SQL null in all cases.
+ A JSON null value is converted to an SQL null in all cases.
</para>
</listitem>
<listitem>
@@ -16152,7 +16152,7 @@ table2-mapping
<literal>string</literal>, <literal>number</literal>,
<literal>boolean</literal>, and <literal>null</literal>.
(The <literal>null</literal> result should not be confused
- with a SQL NULL; see the examples.)
+ with an SQL NULL; see the examples.)
</para>
<para>
<literal>json_typeof('-123.4')</literal>
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index c072110ba6..22af7dbf51 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -2194,7 +2194,7 @@ HINT: You can then restart the server after making the necessary configuration
Currently, temporary table creation is not allowed during read only
transactions, so in some cases existing scripts will not run correctly.
This restriction might be relaxed in a later release. This is
- both a SQL Standard compliance issue and a technical issue.
+ both an SQL Standard compliance issue and a technical issue.
</para>
<para>
diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 29fa3b7933..b2326b72e3 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -338,7 +338,7 @@ aminsert (Relation indexRelation,
<para>
If the index AM wishes to cache data across successive index insertions
- within a SQL statement, it can allocate space
+ within an SQL statement, it can allocate space
in <literal>indexInfo->ii_Context</literal> and store a pointer to the
data in <literal>indexInfo->ii_AmCache</literal> (which will be NULL
initially).
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index ca905b80a6..9e6e085385 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -3468,7 +3468,7 @@ char *PQresultErrorField(const PGresult *res, int fieldcode);
<listitem>
<para>
The text of a failed internally-generated command. This could
- be, for example, a SQL query issued by a PL/pgSQL function.
+ be, for example, an SQL query issued by a PL/pgSQL function.
</para>
</listitem>
</varlistentry>
@@ -5468,7 +5468,7 @@ UPDATE mytable SET x = x + 1 WHERE id = 42;
</indexterm>
<para>
- Ordinarily, <application>libpq</application> collects a SQL command's
+ Ordinarily, <application>libpq</application> collects an SQL command's
entire result and returns it to the application as a single
<structname>PGresult</structname>. This can be unworkable for commands
that return a large number of rows. For such cases, applications can use
diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml
index 06a983c075..436be76bfa 100644
--- a/doc/src/sgml/ltree.sgml
+++ b/doc/src/sgml/ltree.sgml
@@ -804,7 +804,7 @@ ltreetest=> SELECT subpath(path,0,2)||'Space'||subpath(path,2) FROM test WHER
</para>
<para>
- We could simplify this by creating a SQL function that inserts a label
+ We could simplify this by creating an SQL function that inserts a label
at a specified position in a path:
<screen>
CREATE FUNCTION ins_label(ltree, int, text) RETURNS ltree
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 6cb9c63161..d358bbe4a6 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -703,7 +703,7 @@ ERROR: could not serialize access due to read/write dependencies among transact
transactions might do, or it will not successfully commit. It is
important that an environment which uses this technique have a
generalized way of handling serialization failures (which always return
- with a SQLSTATE value of '40001'), because it will be very hard to
+ with an SQLSTATE value of '40001'), because it will be very hard to
predict exactly which transactions might contribute to the read/write
dependencies and need to be rolled back to prevent serialization
anomalies. The monitoring of read/write dependencies has a cost, as does
diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml
index 59620faec0..24b5e463ed 100644
--- a/doc/src/sgml/pageinspect.sgml
+++ b/doc/src/sgml/pageinspect.sgml
@@ -136,7 +136,7 @@ test=# SELECT page_checksum(get_raw_page('pg_class', 0), 0);
<listitem>
<para>
<function>fsm_page_contents</function> shows the internal node structure
- of a FSM page. For example:
+ of an FSM page. For example:
<screen>
test=# SELECT fsm_page_contents(get_raw_page('pg_class', 'fsm', 0));
</screen>
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index c97344ff92..1c9d3842da 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1095,7 +1095,7 @@ PERFORM <replaceable>query</replaceable>;
One might expect that writing <command>SELECT</command> directly
would accomplish this result, but at
present the only accepted way to do it is
- <command>PERFORM</command>. A SQL command that can return rows,
+ <command>PERFORM</command>. An SQL command that can return rows,
such as <command>SELECT</command>, will be rejected as an error
unless it has an <literal>INTO</literal> clause as discussed in the
next section.
@@ -1124,7 +1124,7 @@ PERFORM create_mv('cs_session_page_requests_mv', my_query);
</indexterm>
<para>
- The result of a SQL command yielding a single row (possibly of multiple
+ The result of an SQL command yielding a single row (possibly of multiple
columns) can be assigned to a record variable, row-type variable, or list
of scalar variables. This is done by writing the base SQL command and
adding an <literal>INTO</literal> clause. For example,
@@ -1313,7 +1313,7 @@ EXECUTE <replaceable class="command">command-string</replaceable> <optional> INT
<para>
The <literal>INTO</literal> clause specifies where the results of
- a SQL command returning rows should be assigned. If a row variable
+ an SQL command returning rows should be assigned. If a row variable
or variable list is provided, it must exactly match the structure
of the command's results; if a
record variable is provided, it will configure itself to match the
@@ -2652,7 +2652,7 @@ END LOOP <optional> <replaceable>label</replaceable> </optional>;
<para>
The <literal>FOREACH</literal> loop is much like a <literal>FOR</literal> loop,
- but instead of iterating through the rows returned by a SQL query,
+ but instead of iterating through the rows returned by an SQL query,
it iterates through the elements of an array value.
(In general, <literal>FOREACH</literal> is meant for looping through
components of a composite-valued expression; variants for looping
@@ -4719,7 +4719,7 @@ INSERT INTO foo (foo) VALUES (foo(foo));
<para>
Another way to understand this is that variable substitution can only
- insert data values into a SQL command; it cannot dynamically change which
+ insert data values into an SQL command; it cannot dynamically change which
database objects are referenced by the command. (If you want to do
that, you must build a command string dynamically, as explained in
<xref linkend="plpgsql-statements-executing-dyn"/>.)
@@ -4741,7 +4741,7 @@ INSERT INTO dest (col) SELECT foo + bar FROM src;
<para>
By default, <application>PL/pgSQL</application> will report an error if a name
- in a SQL statement could refer to either a variable or a table column.
+ in an SQL statement could refer to either a variable or a table column.
You can fix such a problem by renaming the variable or column,
or by qualifying the ambiguous reference, or by telling
<application>PL/pgSQL</application> which interpretation to prefer.
@@ -5377,7 +5377,7 @@ HINT: Make sure the query returns the exact list of columns.
<itemizedlist>
<listitem>
<para>
- If a name used in a SQL command could be either a column name of a
+ If a name used in an SQL command could be either a column name of a
table used in the command or a reference to a variable of the function,
<application>PL/SQL</application> treats it as a column name.
By default, <application>PL/pgSQL</application> will throw an error
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index c1651000a3..c2540b8ec9 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -577,7 +577,7 @@ AS $$
$$ LANGUAGE plpythonu;
</programlisting>
- To return a SQL null for any column, insert <symbol>None</symbol> at
+ To return an SQL null for any column, insert <symbol>None</symbol> at
the corresponding position.
</para>
<para>
@@ -605,7 +605,7 @@ $$ LANGUAGE plpythonu;
Any extra dictionary key/value pairs are ignored. Missing keys are
treated as errors.
- To return a SQL null value for any column, insert
+ To return an SQL null value for any column, insert
<symbol>None</symbol> with the corresponding column name as the key.
</para>
</listitem>
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 032e0b3a6b..1759fc4498 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -475,7 +475,7 @@ $$ LANGUAGE pltcl;
<listitem>
<para>
The Tcl script contained in <replaceable>command</replaceable> is
- executed within a SQL subtransaction. If the script returns an
+ executed within an SQL subtransaction. If the script returns an
error, that entire subtransaction is rolled back before returning the
error out to the surrounding Tcl code.
See <xref linkend="pltcl-subtransactions"/> for more details and an
@@ -854,7 +854,7 @@ CREATE EVENT TRIGGER tcl_a_snitch ON ddl_command_start EXECUTE FUNCTION tclsnitc
PL/Tcl's <function>elog</function> command. Such errors can be caught
within Tcl using the Tcl <function>catch</function> command. If an
error is not caught but is allowed to propagate out to the top level of
- execution of the PL/Tcl function, it is reported as a SQL error in the
+ execution of the PL/Tcl function, it is reported as an SQL error in the
function's calling query.
</para>
@@ -867,7 +867,7 @@ CREATE EVENT TRIGGER tcl_a_snitch ON ddl_command_start EXECUTE FUNCTION tclsnitc
subtransaction, which is rolled back on error, so that any
partially-completed operation is automatically cleaned up.)
Again, if an error propagates out to the top level without being caught,
- it turns back into a SQL error.
+ it turns back into an SQL error.
</para>
<para>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 2f4dde3beb..e8ee8a4bf4 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -349,7 +349,7 @@
<term>AuthenticationSSPI</term>
<listitem>
<para>
- The frontend must now initiate a SSPI negotiation. The frontend
+ The frontend must now initiate an SSPI negotiation. The frontend
will send a GSSResponse with the first part of the SSPI
data stream in response to this. If further messages are needed,
the server will respond with AuthenticationGSSContinue.
@@ -6226,7 +6226,7 @@ message.
<listitem>
<para>
Internal query: the text of a failed internally-generated command.
- This could be, for example, a SQL query issued by a PL/pgSQL function.
+ This could be, for example, an SQL query issued by a PL/pgSQL function.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml
index b3b5d61a85..b2e5b9b72e 100644
--- a/doc/src/sgml/ref/alter_opfamily.sgml
+++ b/doc/src/sgml/ref/alter_opfamily.sgml
@@ -269,7 +269,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="
</para>
<para>
- The operators should not be defined by SQL functions. A SQL function
+ The operators should not be defined by SQL functions. An SQL function
is likely to be inlined into the calling query, which will prevent
the optimizer from recognizing that the query matches an index.
</para>
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index e43705d069..180e5f5c1f 100644
--- a/doc/src/sgml/ref/create_function.sgml
+++ b/doc/src/sgml/ref/create_function.sgml
@@ -701,7 +701,7 @@ CREATE FUNCTION foo(int, int default 42) ...
<title>Examples</title>
<para>
- Add two integers using a SQL function:
+ Add two integers using an SQL function:
<programlisting>
CREATE FUNCTION add(integer, integer) RETURNS integer
AS 'select $1 + $2;'
diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml
index 4f1bfae822..f1d6a4cbbe 100644
--- a/doc/src/sgml/ref/create_opclass.sgml
+++ b/doc/src/sgml/ref/create_opclass.sgml
@@ -265,7 +265,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL
</para>
<para>
- The operators should not be defined by SQL functions. A SQL function
+ The operators should not be defined by SQL functions. An SQL function
is likely to be inlined into the calling query, which will prevent
the optimizer from recognizing that the query matches an index.
</para>
diff --git a/doc/src/sgml/ref/create_statistics.sgml b/doc/src/sgml/ref/create_statistics.sgml
index 988f4c573f..9a8c904c08 100644
--- a/doc/src/sgml/ref/create_statistics.sgml
+++ b/doc/src/sgml/ref/create_statistics.sgml
@@ -208,7 +208,7 @@ EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0);
<para>
Create table <structname>t2</structname> with two perfectly correlated columns
- (containing identical data), and a MCV list on those columns:
+ (containing identical data), and an MCV list on those columns:
<programlisting>
CREATE TABLE t2 (
diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml
index 561af989a4..3f4b5acc7b 100644
--- a/doc/src/sgml/ref/create_trigger.sgml
+++ b/doc/src/sgml/ref/create_trigger.sgml
@@ -515,7 +515,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</
as <literal>ON UPDATE CASCADE</literal> or <literal>ON DELETE SET NULL</literal>, are
treated as part of the SQL command that caused them (note that such
actions are never deferred). Relevant triggers on the affected table will
- be fired, so that this provides another way in which a SQL command might
+ be fired, so that this provides another way in which an SQL command might
fire triggers not directly matching its type. In simple cases, triggers
that request transition relations will see all changes caused in their
table by a single original SQL command as a single transition relation.
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 5ddadc11f2..a6c0788592 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1413,7 +1413,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<title>Examples</title>
<para>
- To dump a database called <literal>mydb</literal> into a SQL-script file:
+ To dump a database called <literal>mydb</literal> into an SQL-script file:
<screen>
<prompt>$</prompt> <userinput>pg_dump mydb > db.sql</userinput>
</screen>
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index 8eb4f538d5..0c60077e1f 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -1012,7 +1012,7 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
Before <productname>PostgreSQL</productname> 9.6, SQL commands in script files
were terminated by newlines, and so they could not be continued across
lines. Now a semicolon is <emphasis>required</emphasis> to separate consecutive
- SQL commands (though a SQL command does not need one if it is followed
+ SQL commands (though an SQL command does not need one if it is followed
by a meta command). If you need to create a script file that works with
both old and new versions of <application>pgbench</application>, be sure to write
each SQL command on a single line ending with a semicolon.
@@ -1030,7 +1030,7 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
<xref linkend="pgbench-automatic-variables"/>. A value specified for these
variables using <option>-D</option> takes precedence over the automatic presets.
Once set, a variable's
- value can be inserted into a SQL command by writing
+ value can be inserted into an SQL command by writing
<literal>:</literal><replaceable>variablename</replaceable>. When running more than
one client session, each session has its own set of variables.
<application>pgbench</application> supports up to 255 variable uses in one
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index dd36830a2d..a8dfc41e40 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1044,7 +1044,7 @@ testdb=>
For <literal>\copy ... from stdin</literal>, data rows are read from the same
source that issued the command, continuing until <literal>\.</literal>
is read or the stream reaches <acronym>EOF</acronym>. This option is useful
- for populating tables in-line within a SQL script file.
+ for populating tables in-line within an SQL script file.
For <literal>\copy ... to stdout</literal>, output is sent to the same place
as <application>psql</application> command output, and
the <literal>COPY <replaceable>count</replaceable></literal> command status is
@@ -2243,7 +2243,7 @@ Tue Oct 26 21:40:57 CEST 1999
<listitem>
<para>
Sends the current query buffer to the server, then treats
- each column of each row of the query's output (if any) as a SQL
+ each column of each row of the query's output (if any) as an SQL
statement to be executed. For example, to create an index on each
column of <structname>my_table</structname>:
<programlisting>
@@ -3510,7 +3510,7 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput>
</para>
<para>
- Normally, <application>psql</application> will dispatch a SQL command to the
+ Normally, <application>psql</application> will dispatch an SQL command to the
server as soon as it reaches the command-ending semicolon, even if
more input remains on the current line. Thus for example entering
<programlisting>
diff --git a/doc/src/sgml/tablefunc.sgml b/doc/src/sgml/tablefunc.sgml
index 356e2b0f00..808162b89b 100644
--- a/doc/src/sgml/tablefunc.sgml
+++ b/doc/src/sgml/tablefunc.sgml
@@ -198,13 +198,13 @@ row1 val11 val12 val13 ...
row2 val21 val22 val23 ...
...
</programlisting>
- The <function>crosstab</function> function takes a text parameter that is a SQL
+ The <function>crosstab</function> function takes a text parameter that is an SQL
query producing raw data formatted in the first way, and produces a table
formatted in the second way.
</para>
<para>
- The <parameter>sql</parameter> parameter is a SQL statement that produces
+ The <parameter>sql</parameter> parameter is an SQL statement that produces
the source set of data. This statement must return one
<structfield>row_name</structfield> column, one
<structfield>category</structfield> column, and one
@@ -459,7 +459,7 @@ crosstab(text source_sql, text category_sql)
</para>
<para>
- <parameter>source_sql</parameter> is a SQL statement that produces the
+ <parameter>source_sql</parameter> is an SQL statement that produces the
source set of data. This statement must return one
<structfield>row_name</structfield> column, one
<structfield>category</structfield> column, and one
@@ -493,7 +493,7 @@ SELECT row_name, extra_col, cat, value FROM foo ORDER BY 1;
</para>
<para>
- <parameter>category_sql</parameter> is a SQL statement that produces
+ <parameter>category_sql</parameter> is an SQL statement that produces
the set of categories. This statement must return only one column.
It must produce at least one row, or an error will be generated.
Also, it must not produce duplicate values, or an error will be
diff --git a/doc/src/sgml/tablesample-method.sgml b/doc/src/sgml/tablesample-method.sgml
index 1c9f1bf44b..c821941b71 100644
--- a/doc/src/sgml/tablesample-method.sgml
+++ b/doc/src/sgml/tablesample-method.sgml
@@ -28,7 +28,7 @@ method_name(internal) RETURNS tsm_handler
The name of the function is the same method name appearing in the
<literal>TABLESAMPLE</literal> clause. The <type>internal</type> argument is a dummy
(always having value zero) that simply serves to prevent this function from
- being called directly from a SQL command.
+ being called directly from an SQL command.
The result of the function must be a palloc'd struct of
type <type>TsmRoutine</type>, which contains pointers to support functions for
the sampling method. These support functions are plain C functions and
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index 168d84f06b..20db7b7afe 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -1790,7 +1790,7 @@ SELECT ts_rewrite('a & b'::tsquery, 'a'::tsquery, 'c'::tsquery);
<listitem>
<para>
This form of <function>ts_rewrite</function> accepts a starting
- <replaceable>query</replaceable> and a SQL <replaceable>select</replaceable> command, which
+ <replaceable>query</replaceable> and an SQL <replaceable>select</replaceable> command, which
is given as a text string. The <replaceable>select</replaceable> must yield two
columns of <type>tsquery</type> type. For each row of the
<replaceable>select</replaceable> result, occurrences of the first column value
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 4a0e74652f..f1a845f756 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -411,7 +411,7 @@
trigger <emphasis>will</emphasis> see the effects of data
changes for rows previously processed in the same outer
command. This requires caution, since the ordering of these
- change events is not in general predictable; a SQL command that
+ change events is not in general predictable; an SQL command that
affects multiple rows can visit the rows in any order.
</para>
</listitem>
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index 103e4c5d99..2874874248 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -1222,7 +1222,7 @@ section consider all of their inputs in one resolution step.
<para>
The rules given in the preceding sections will result in assignment
-of non-<type>unknown</type> data types to all expressions in a SQL query,
+of non-<type>unknown</type> data types to all expressions in an SQL query,
except for unspecified-type literals that appear as simple output
columns of a <command>SELECT</command> command. For example, in
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 41bcc5b79d..8ea680860d 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -194,7 +194,7 @@
must be a <command>SELECT</command> or have a <literal>RETURNING</literal>
clause that returns whatever is
specified as the function's return type. Alternatively, if you
- want to define a SQL function that performs actions but has no
+ want to define an SQL function that performs actions but has no
useful value to return, you can define it as returning <type>void</type>.
For example, this function removes rows with negative salaries from
the <literal>emp</literal> table:
@@ -234,8 +234,8 @@ CALL clean_emp();
<note>
<para>
- The entire body of a SQL function is parsed before any of it is
- executed. While a SQL function can contain commands that alter
+ The entire body of an SQL function is parsed before any of it is
+ executed. While an SQL function can contain commands that alter
the system catalogs (e.g., <command>CREATE TABLE</command>), the effects
of such commands will not be visible during parse analysis of
later commands in the function. Thus, for example,
@@ -243,7 +243,7 @@ CALL clean_emp();
will not work as desired if packaged up into a single SQL function,
since <structname>foo</structname> won't exist yet when the <command>INSERT</command>
command is parsed. It's recommended to use <application>PL/pgSQL</application>
- instead of a SQL function in this type of situation.
+ instead of an SQL function in this type of situation.
</para>
</note>
@@ -267,7 +267,7 @@ CALL clean_emp();
</indexterm>
<para>
- Arguments of a SQL function can be referenced in the function
+ Arguments of an SQL function can be referenced in the function
body using either names or numbers. Examples of both methods appear
below.
</para>
@@ -1473,7 +1473,7 @@ SELECT concat_values('|', 1, 4, 2);
</indexterm>
<para>
- When a SQL function has one or more parameters of collatable data types,
+ When an SQL function has one or more parameters of collatable data types,
a collation is identified for each function call depending on the
collations assigned to the actual arguments, as described in <xref
linkend="collation"/>. If a collation is successfully identified
@@ -1508,7 +1508,7 @@ $$ LANGUAGE SQL;
<para>
If no common collation can be identified among the actual arguments,
- then a SQL function treats its parameters as having their data types'
+ then an SQL function treats its parameters as having their data types'
default collation (which is usually the database's default collation,
but could be different for parameters of domain types).
</para>
@@ -2952,7 +2952,7 @@ HeapTupleGetDatum(HeapTuple tuple)
save enough state across calls to remember what it was doing and
return the correct next item on each call.
In the other method, called <firstterm>Materialize</firstterm> mode,
- a SRF fills and returns a tuplestore object containing its
+ an SRF fills and returns a tuplestore object containing its
entire result; then only one call occurs for the whole result, and
no inter-call state is needed.
</para>
@@ -3375,7 +3375,7 @@ CREATE FUNCTION make_array(anyelement) RETURNS anyarray
There is a variant of polymorphism that is only available to C-language
functions: they can be declared to take parameters of type
<literal>"any"</literal>. (Note that this type name must be double-quoted,
- since it's also a SQL reserved word.) This works like
+ since it's also an SQL reserved word.) This works like
<type>anyelement</type> except that it does not constrain different
<literal>"any"</literal> arguments to be the same type, nor do they help
determine the function's result type. A C-language function can also
@@ -3544,7 +3544,7 @@ if (!ptr)
<para>
It is also possible to attach a <firstterm>planner support
- function</firstterm> to a SQL-callable function (called
+ function</firstterm> to an SQL-callable function (called
its <firstterm>target function</firstterm>), and thereby provide
knowledge about the target function that is too complex to be
represented declaratively. Planner support functions have to be
diff --git a/src/backend/executor/functions.c b/src/backend/executor/functions.c
index 39580f7d57..3cfeff87fc 100644
--- a/src/backend/executor/functions.c
+++ b/src/backend/executor/functions.c
@@ -512,13 +512,13 @@ init_execution_state(List *queryTree_list,
((CopyStmt *) stmt->utilityStmt)->filename == NULL)
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
- errmsg("cannot COPY to/from client in a SQL function")));
+ errmsg("cannot COPY to/from client in an SQL function")));
if (IsA(stmt->utilityStmt, TransactionStmt))
ereport(ERROR,
(errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
/* translator: %s is a SQL statement name */
- errmsg("%s is not allowed in a SQL function",
+ errmsg("%s is not allowed in an SQL function",
CreateCommandName(stmt->utilityStmt))));
}
diff --git a/src/bin/pgbench/pgbench.c b/src/bin/pgbench/pgbench.c
index dc84b7b9b7..d7479925cb 100644
--- a/src/bin/pgbench/pgbench.c
+++ b/src/bin/pgbench/pgbench.c
@@ -5149,7 +5149,7 @@ ParseScript(const char *script, const char *desc, int weight)
if (index == 0)
syntax_error(desc, lineno, NULL, NULL,
- "\\gset must follow a SQL command",
+ "\\gset must follow an SQL command",
NULL, -1);
cmd = ps.commands[index - 1];
@@ -5157,7 +5157,7 @@ ParseScript(const char *script, const char *desc, int weight)
if (cmd->type != SQL_COMMAND ||
cmd->varprefix != NULL)
syntax_error(desc, lineno, NULL, NULL,
- "\\gset must follow a SQL command",
+ "\\gset must follow an SQL command",
cmd->first_line, -1);
/* get variable prefix */
On Thu, Jun 10, 2021 at 1:27 AM David Rowley <dgrowleyml@gmail.com> wrote:
I think we should change all 55 instances of "a SQL" in the docs to
use "an SQL" and leave the 800 other instances of "a SQL" alone.
+1
Consistency is good.
Roberto
On 2021-Jun-10, David Rowley wrote:
I thought it might be worth having this conversation before we branch for v15.
It seems we have no standard as to if we say "a SQL" or "an SQL".
I was just reading the standard a couple of days ago and happened to
notice that the standard itself in some places uses "a SQL" and in other
places "an SQL". I didn't stop to make an analysis of that, so I don't
know how prevalent each form is -- I just giggled and moved on.
My regex foo is not strong enough to think how I might find multiline instances.
This catches some of these:
ag "\sa[\s*]*\n[\s*]*(A|E|F|H|I|L|M|N|O|S|X)[A-Z]{2,5}\s"
You get a bunch of "a NULL" or "a NOT" and so on, but here's a few valid ones:
contrib/tablefunc/tablefunc.c:316: * crosstab - create a crosstab of rowids and values columns from a
contrib/tablefunc/tablefunc.c:317: * SQL statement returning one rowid column, one category column,
contrib/tablefunc/tablefunc.c:607: * crosstab - create a crosstab of rowids and values columns from a
contrib/tablefunc/tablefunc.c:608: * SQL statement returning one rowid column, one category column,
doc/src/sgml/plpgsql.sgml
1127: The result of a
1128: SQL command yielding a single row (possibly of multiple
src/backend/catalog/pg_subscription.c:438: * translator: first %s is a SQL ALTER command and second %s is a
src/backend/catalog/pg_subscription.c:439: * SQL DROP command
src/backend/replication/logical/logical.c:126: * 1) We need to be able to correctly and quickly identify the timeline a
src/backend/replication/logical/logical.c:127: * LSN belongs to
src/backend/libpq/auth.c:847: * has. If it's an MD5 hash, we must do MD5 authentication, and if it's a
src/backend/libpq/auth.c:848: * SCRAM secret, we must do SCRAM authentication.
--
�lvaro Herrera Valdivia, Chile
On Fri, 11 Jun 2021 at 02:04, David Rowley <dgrowleyml@gmail.com> wrote:
I came up with the attached patch.
Further searching using:
git grep -E "\s(an|An)\s(F|H|L|M|N|S|X)[A-Z]{2,5}"
(i.e vowel sounding, but not actually starting with a vowel then
manually looking for pronounceable ones.)
- by a response from client in an SASLResponse message. The particulars of
+ by a response from client in a SASLResponse message. The particulars of- An SHA1 hash of the random prefix and data is appended.
+ A SHA1 hash of the random prefix and data is appended.- requires an MIT Kerberos installation and opens TCP/IP listen sockets.
+ requires a MIT Kerberos installation and opens TCP/IP listen sockets.I think all of these should use "a" rather than "an".
David
On Thu, 10 Jun 2021 at 10:43, David Rowley <dgrowleyml@gmail.com> wrote:
- requires an MIT Kerberos installation and opens TCP/IP listen sockets. + requires a MIT Kerberos installation and opens TCP/IP listen sockets.I think all of these should use "a" rather than "an".
“A MIT …”? As far as I know it is pronounced M - I - T, which would imply
that it should use “an”. The following page seems believable and is pretty
unequivocal on the issue:
On Fri, 11 Jun 2021 at 02:35, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:
On 2021-Jun-10, David Rowley wrote:
My regex foo is not strong enough to think how I might find multiline instances.
This catches some of these:
ag "\sa[\s*]*\n[\s*]*(A|E|F|H|I|L|M|N|O|S|X)[A-Z]{2,5}\s"
Thanks. I ended up using -C 1 and manually checking the previous line.
You get a bunch of "a NULL" or "a NOT" and so on, but here's a few valid ones:
contrib/tablefunc/tablefunc.c:316: * crosstab - create a crosstab of rowids and values columns from a
contrib/tablefunc/tablefunc.c:317: * SQL statement returning one rowid column, one category column,contrib/tablefunc/tablefunc.c:607: * crosstab - create a crosstab of rowids and values columns from a
contrib/tablefunc/tablefunc.c:608: * SQL statement returning one rowid column, one category column,doc/src/sgml/plpgsql.sgml
1127: The result of a
1128: SQL command yielding a single row (possibly of multiplesrc/backend/catalog/pg_subscription.c:438: * translator: first %s is a SQL ALTER command and second %s is a
src/backend/catalog/pg_subscription.c:439: * SQL DROP commandsrc/backend/replication/logical/logical.c:126: * 1) We need to be able to correctly and quickly identify the timeline a
src/backend/replication/logical/logical.c:127: * LSN belongs tosrc/backend/libpq/auth.c:847: * has. If it's an MD5 hash, we must do MD5 authentication, and if it's a
src/backend/libpq/auth.c:848: * SCRAM secret, we must do SCRAM authentication.
Thanks. I've left all the .c file comments alone for no and looks like
I got the doc/src/sgml/plpgsql.sgml one already.
David
Alvaro Herrera <alvherre@alvh.no-ip.org> writes:
On 2021-Jun-10, David Rowley wrote:
It seems we have no standard as to if we say "a SQL" or "an SQL".
I was just reading the standard a couple of days ago and happened to
notice that the standard itself in some places uses "a SQL" and in other
places "an SQL". I didn't stop to make an analysis of that, so I don't
know how prevalent each form is -- I just giggled and moved on.
Indeed. I think this is entirely pointless; there's zero hope that
any consistency you might establish right now will persist very long.
The largest effect of this proposed patch will be to create
back-patching headaches.
regards, tom lane
On Fri, 11 Jun 2021 at 02:53, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Indeed. I think this is entirely pointless; there's zero hope that
any consistency you might establish right now will persist very long.
The largest effect of this proposed patch will be to create
back-patching headaches.
hmm. Yet we do have other standards which we do manage to maintain.
I did limit the scope to just the docs and error messages. My thoughts
were that someone fudging a backpatch on the docs seems less likely to
cause a nuclear meltdown than someone doing the same in .c code.
David
David Rowley <dgrowleyml@gmail.com> writes:
On Fri, 11 Jun 2021 at 02:53, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Indeed. I think this is entirely pointless; there's zero hope that
any consistency you might establish right now will persist very long.
hmm. Yet we do have other standards which we do manage to maintain.
If there were some semblance of an overall consensus on the spelling,
I'd be fine with weeding out the stragglers. But when the existing
usages are only about 2-to-1 in one direction or the other, I feel
quite confident in predicting that incoming patches are often going
to get this wrong. Especially so if the convention you want to
establish in the docs is contrary to the majority usage in the code
comments --- how is that not going to confuse people?
regards, tom lane
On Fri, 11 Jun 2021 at 03:24, Tom Lane <tgl@sss.pgh.pa.us> wrote:
If there were some semblance of an overall consensus on the spelling,
I'd be fine with weeding out the stragglers. But when the existing
usages are only about 2-to-1 in one direction or the other, I feel
quite confident in predicting that incoming patches are often going
to get this wrong.
I'm pretty sure you're right and we will get some inconsistencies
creeping back in. I'm not really sure why you think that will be hard
to fix though. If we catch them soon enough then we won't need to
worry about causing future backpatching pain.
Especially so if the convention you want to
establish in the docs is contrary to the majority usage in the code
comments --- how is that not going to confuse people?
Why would someone go and gawk at code comments to clear up their
confusion about what they should write in the docs? I think any sane
person that's looking for inspiration would look at the docs first.
I really think it's worth the trouble here to be consistent in our
public-facing documents. When I read [1]http://patorjk.com/blog/2012/01/26/pronouncing-sql-s-q-l-or-sequel/ earlier and the blog started
talking about Oracle documentation using sequel consistently before
going on to talk about MySQL's documentation, I started to get a bit
worried that the author might mention something about our lack of
consistency. I was glad to see they missed us out of that. However,
maybe that's because we are inconsistent.
If you really feel that strongly about not changing this then I can
drop this. However, I'll likely growl every time I see "a SQL" in the
docs from now on.
David
[1]: http://patorjk.com/blog/2012/01/26/pronouncing-sql-s-q-l-or-sequel/
David Rowley <dgrowleyml@gmail.com> writes:
If you really feel that strongly about not changing this then I can
drop this. However, I'll likely growl every time I see "a SQL" in the
docs from now on.
[ shrug... ] I'm not going to stand in your way. However, I'm also
unlikely to worry about this point when copy-editing docs.
regards, tom lane
On 11/06/21 2:48 am, Isaac Morland wrote:
On Thu, 10 Jun 2021 at 10:43, David Rowley <dgrowleyml@gmail.com
<mailto:dgrowleyml@gmail.com>> wrote:- requires an MIT Kerberos installation and opens TCP/IP listen sockets. + requires a MIT Kerberos installation and opens TCP/IP listen sockets.I think all of these should use "a" rather than "an".
“A MIT …”? As far as I know it is pronounced M - I - T, which would
imply that it should use “an”. The following page seems believable and
is pretty unequivocal on the issue:https://mitadmissions.org/blogs/entry/como_se_dice/
<https://mitadmissions.org/blogs/entry/como_se_dice/>
The rule is, in English, is that if the word sounds like it starts with
a vowel then use 'an' rather than 'a'. Though some people think that
the rule only applies to words beginning with a vowel, which is a
misunderstanding.
So 'an SQL' and 'an MIT' are correct. IMHO
Cheers,
Gavin
On Thu, 10 Jun 2021 at 16:11, Gavin Flower <GavinFlower@archidevsys.co.nz>
wrote:
On 11/06/21 2:48 am, Isaac Morland wrote:
“A MIT …”? As far as I know it is pronounced M - I - T, which would
imply that it should use “an”. The following page seems believable and
is pretty unequivocal on the issue:https://mitadmissions.org/blogs/entry/como_se_dice/
<https://mitadmissions.org/blogs/entry/como_se_dice/>The rule is, in English, is that if the word sounds like it starts with
a vowel then use 'an' rather than 'a'. Though some people think that
the rule only applies to words beginning with a vowel, which is a
misunderstanding.So 'an SQL' and 'an MIT' are correct. IMHO
Right, spelling is irrelevant, it's about whether the word begins with a
vowel *sound*. Or so I've always understood and I'm pretty sure if you
listen to what people actually say that's what you'll generally hear. So "A
uranium mine" not "An uranium mine" since "uranium" begins with a "y-"
sound just like "yesterday". The fact that "u" is a vowel is irrelevant.
But then there is "an historic occasion" so go figure.
On 11/06/21 8:17 am, Isaac Morland wrote:
On Thu, 10 Jun 2021 at 16:11, Gavin Flower
<GavinFlower@archidevsys.co.nz <mailto:GavinFlower@archidevsys.co.nz>>
wrote:On 11/06/21 2:48 am, Isaac Morland wrote:
“A MIT …”? As far as I know it is pronounced M - I - T, which would
imply that it should use “an”. The following page seemsbelievable and
is pretty unequivocal on the issue:
<https://mitadmissions.org/blogs/entry/como_se_dice/>
<https://mitadmissions.org/blogs/entry/como_se_dice/>>
The rule is, in English, is that if the word sounds like it starts
with
a vowel then use 'an' rather than 'a'. Though some people think that
the rule only applies to words beginning with a vowel, which is a
misunderstanding.So 'an SQL' and 'an MIT' are correct. IMHO
Right, spelling is irrelevant, it's about whether the word begins with
a vowel *sound*. Or so I've always understood and I'm pretty sure if
you listen to what people actually say that's what you'll generally
hear. So "A uranium mine" not "An uranium mine" since "uranium" begins
with a "y-" sound just like "yesterday". The fact that "u" is a vowel
is irrelevant. But then there is "an historic occasion" so go figure.
The 'h' in 'historic' is silent, at least it used to be -- I think now
it is almost silent. So using 'an historic occasion' is correct.
Gavin Flower <GavinFlower@archidevsys.co.nz> writes:
On 11/06/21 8:17 am, Isaac Morland wrote:
... But then there is "an historic occasion" so go figure.
The 'h' in 'historic' is silent, at least it used to be -- I think now
it is almost silent. So using 'an historic occasion' is correct.
It's silent according to the Brits, I believe. In America, the
pronunciation varies.
regards, tom lane
On 6/10/21 5:32 PM, Tom Lane wrote:
Gavin Flower <GavinFlower@archidevsys.co.nz> writes:
On 11/06/21 8:17 am, Isaac Morland wrote:
... But then there is "an historic occasion" so go figure.
The 'h' in 'historic' is silent, at least it used to be -- I think now
it is almost silent. So using 'an historic occasion' is correct.It's silent according to the Brits, I believe. In America, the
pronunciation varies.
I suspect "an historic" is bordering on archaic even in the UK these days.
cheers
andrew
--
Andrew Dunstan
EDB: https://www.enterprisedb.com
On Fri, 11 Jun 2021 at 02:48, Isaac Morland <isaac.morland@gmail.com> wrote:
On Thu, 10 Jun 2021 at 10:43, David Rowley <dgrowleyml@gmail.com> wrote:
- requires an MIT Kerberos installation and opens TCP/IP listen sockets. + requires a MIT Kerberos installation and opens TCP/IP listen sockets.I think all of these should use "a" rather than "an".
“A MIT …”? As far as I know it is pronounced M - I - T, which would imply that it should use “an”. The following page seems believable and is pretty unequivocal on the issue:
Opps. I'm not sure what I was thinking there. I'd just been listening
to something in German, so maybe I'd had the German word in mind
instead.
David
On Fri, 11 Jun 2021 at 09:39, Andrew Dunstan <andrew@dunslane.net> wrote:
I suspect "an historic" is bordering on archaic even in the UK these days.
Yeah, that's a weird one. Maybe
https://en.wikipedia.org/wiki/H-dropping is to blame.
David
On Fri, 11 Jun 2021 at 04:04, Tom Lane <tgl@sss.pgh.pa.us> wrote:
However, I'm also
unlikely to worry about this point when copy-editing docs.
I'm sorry to hear that. Maybe keeping this consistent will be one of
those endless jobs like keeping the source code pgindented. We still
try to keep that in order despite the audience for the source code
being much smaller than the audience for our documents.
Anyway, I'll set an alarm for this time next year so I can check on
how many inconsistencies have crept back in over the development
cycle.
In the meantime, I've pushed the fixes to master.
David
On Thu, Jun 10, 2021 at 05:39:00PM -0400, Andrew Dunstan wrote:
I suspect "an historic" is bordering on archaic even in the UK these days.
Don't trigger me on the difference between "historic" and "historical"! ;-)
(Hey, not every day I get to trim quoted text to one line --- see recent
pgsql-general discussion of the topic.)
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
On Thu, 10 Jun 2021, 15:35 Alvaro Herrera, <alvherre@alvh.no-ip.org> wrote:
src/backend/libpq/auth.c:847: * has. If it's an MD5 hash, we must do
MD5 authentication, and if it's a
src/backend/libpq/auth.c:848: * SCRAM secret, we must do SCRAM
authentication.
Not sure whether you were just listing examples and you weren't suggesting
this should be changed, but surely "SCRAM" is pronounced "scram" and is
thus "a SCRAM"?
Geoff
On Sun, Jun 13, 2021 at 07:36:54AM +0100, Geoff Winkless wrote:
On Thu, 10 Jun 2021, 15:35 Alvaro Herrera, <alvherre@alvh.no-ip.org> wrote:
src/backend/libpq/auth.c:847: * has. If it's an MD5 hash, we must do
MD5 authentication, and if it's a
src/backend/libpq/auth.c:848: * SCRAM secret, we must do SCRAM
authentication.Not sure whether you were just listing examples and you weren't suggesting
this should be changed, but surely "SCRAM" is pronounced "scram" and is
thus "a SCRAM"?
RFC 5802 uses "a SCRAM something" commonly, but "a SCRAM" alone does
not make sense:
https://datatracker.ietf.org/doc/html/rfc5802
The sentences quoted above look fine to me.
--
Michael
On 6/13/21 7:13 AM, Michael Paquier wrote:
On Sun, Jun 13, 2021 at 07:36:54AM +0100, Geoff Winkless wrote:
On Thu, 10 Jun 2021, 15:35 Alvaro Herrera, <alvherre@alvh.no-ip.org> wrote:
src/backend/libpq/auth.c:847: * has. If it's an MD5 hash, we must do
MD5 authentication, and if it's a
src/backend/libpq/auth.c:848: * SCRAM secret, we must do SCRAM
authentication.Not sure whether you were just listing examples and you weren't suggesting
this should be changed, but surely "SCRAM" is pronounced "scram" and is
thus "a SCRAM"?RFC 5802 uses "a SCRAM something" commonly, but "a SCRAM" alone does
not make sense:
https://datatracker.ietf.org/doc/html/rfc5802The sentences quoted above look fine to me.
I don't think anyone was suggesting SCRAM should be used as a noun
rather than as an adjective. But adjectives can be preceded by an
indefinite article just as nouns can. The discussion simply left out the
implied following noun.
cheers
andrew
--
Andrew Dunstan
EDB: https://www.enterprisedb.com
On Fri, 11 Jun 2021 at 13:44, David Rowley <dgrowleyml@gmail.com> wrote:
Anyway, I'll set an alarm for this time next year so I can check on
how many inconsistencies have crept back in over the development
cycle.
That alarm went off today.
There seem to be only 3 "a SQL"s in the docs to change to "an SQL".
This is a pretty old thread, so here's a link [1]/messages/by-id/CAApHDvpML27UqFXnrYO1MJddsKVMQoiZisPvsAGhKE_tsKXquw@mail.gmail.com to the discussion.
David
[1]: /messages/by-id/CAApHDvpML27UqFXnrYO1MJddsKVMQoiZisPvsAGhKE_tsKXquw@mail.gmail.com
Attachments:
a_SQL_to_an_SQL.patchapplication/octet-stream; name=a_SQL_to_an_SQL.patchDownload
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index a76cf3538f..f52165165d 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -1506,7 +1506,7 @@ EXEC SQL TYPE serial_t IS long;
</para>
<para>
- Any word you declare as a typedef cannot be used as a SQL keyword
+ Any word you declare as a typedef cannot be used as an SQL keyword
in <literal>EXEC SQL</literal> commands later in the same program.
For example, this won't work:
<programlisting>
@@ -1518,7 +1518,7 @@ EXEC SQL START TRANSACTION;
</programlisting>
ECPG will report a syntax error for <literal>START
TRANSACTION</literal>, because it no longer
- recognizes <literal>START</literal> as a SQL keyword,
+ recognizes <literal>START</literal> as an SQL keyword,
only as a typedef.
(If you have such a conflict, and renaming the typedef
seems impractical, you could write the SQL command
@@ -1530,7 +1530,7 @@ EXEC SQL START TRANSACTION;
In <productname>PostgreSQL</productname> releases before v16, use
of SQL keywords as typedef names was likely to result in syntax
errors associated with use of the typedef itself, rather than use
- of the name as a SQL keyword. The new behavior is less likely to
+ of the name as an SQL keyword. The new behavior is less likely to
cause problems when an existing ECPG application is recompiled in
a new <productname>PostgreSQL</productname> release with new
keywords.
On Tue, Apr 11, 2023 at 05:43:04PM +1200, David Rowley wrote:
That alarm went off today.
There seem to be only 3 "a SQL"s in the docs to change to "an SQL".
This is a pretty old thread, so here's a link [1] to the discussion.
Good catches!
--
Michael
On Tue, 11 Apr 2023 at 17:43, David Rowley <dgrowleyml@gmail.com> wrote:
On Fri, 11 Jun 2021 at 13:44, David Rowley <dgrowleyml@gmail.com> wrote:
Anyway, I'll set an alarm for this time next year so I can check on
how many inconsistencies have crept back in over the development
cycle.That alarm went off today.
There seem to be only 3 "a SQL"s in the docs to change to "an SQL".
This is a pretty old thread, so here's a link [1] to the discussion.
[1] /messages/by-id/CAApHDvpML27UqFXnrYO1MJddsKVMQoiZisPvsAGhKE_tsKXquw@mail.gmail.com
Link to the old thread above.
There's just 1 instance of "a SQL" that crept into PG16 after
d866f0374. This probably means I'd be better off doing this in June a
few weeks before branching...
Patch attached.
David
Attachments:
use_an_SQL_not_a_SQL.patchtext/plain; charset=US-ASCII; name=use_an_SQL_not_a_SQL.patchDownload
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 8ff9a520ca..2aa25f62f5 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -5479,7 +5479,7 @@ CREATE FUNCTION get_color_note (rainbow) RETURNS text AS
</para>
<para>
- On the other hand, for a SQL-language function or procedure whose body
+ On the other hand, for an SQL-language function or procedure whose body
is written in SQL-standard style, the body is parsed at function
definition time and all dependencies recognized by the parser are
stored. Thus, if we write the function above as