Re: [DOCS] "data" not "datums"

2017-08-07 Thread Peter Eisentraut
On 8/1/17 04:22, [email protected] wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/9.4/static/datatype-json.html
> Description:
> 
> In the section
> https://www.postgresql.org/docs/9.4/static/datatype-json.html
> 
> Sub-section: 
> 8.14.2. Designing JSON documents effectively
> 
> Original text:
> "but having a predictable structure makes it easier to write queries that
> usefully summarize a set of "documents" (datums) in a table."
> 
> Suggested text:
> "but having a predictable structure makes it easier to write queries that
> usefully summarize a set of "documents" (data) in a table."

"datum" means something specific in PostgreSQL, and several of those are
most usefully "datums".  "data" doesn't really convey the same meaning here.

-- 
Peter Eisentraut  http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


-- 
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs


Re: [DOCS] "data" not "datums"

2017-08-07 Thread Peter Geoghegan
On Mon, Aug 7, 2017 at 1:15 PM, Peter Eisentraut
 wrote:
> "datum" means something specific in PostgreSQL, and several of those are
> most usefully "datums".  "data" doesn't really convey the same meaning here.

We're not the first one to use "datums" like this. I think of it as
being like the use of "people" versus the use of "persons".

-- 
Peter Geoghegan


-- 
Sent via pgsql-docs mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs


Re: [DOCS] "data" not "datums"

2017-08-07 Thread David G. Johnston
On Mon, Aug 7, 2017 at 1:15 PM, Peter Eisentraut <
[email protected]> wrote:

> On 8/1/17 04:22, [email protected] wrote:
> > The following documentation comment has been logged on the website:
> >
> > Page: https://www.postgresql.org/docs/9.4/static/datatype-json.html
> > Description:
> >
> > In the section
> > https://www.postgresql.org/docs/9.4/static/datatype-json.html
> >
> > Sub-section:
> > 8.14.2. Designing JSON documents effectively
> >
> > Original text:
> > "but having a predictable structure makes it easier to write
> queries that
> > usefully summarize a set of "documents" (datums) in a
> table."
> >
> > Suggested text:
> > "but having a predictable structure makes it easier to write
> queries that
> > usefully summarize a set of "documents" (data) in a
> table."
>
> "datum" means something specific in PostgreSQL, and several of those are
> most usefully "datums".  "data" doesn't really convey the same meaning
> here.
>

Peter, ​While your point is accurate the fact is that this seems to be the
only place in the user-facing documentation, aside from "hacker targeted"
material, that the word "datum" in the PostgreSQL sense is used.  However,
changing it to "data" doesn't do it for me either.  Reading the entire
paragraph, including the first introduction of the term "JSON documents",
leads me to think that the best solution here is to remove the
double-quotes surrounding "documents" and remove the parenthetical
entirely.  I'm not seeing how it adds or clarifies anything here - the
reader has been told that an alias for "json value" is "document".
Introducing the concept of "datum" here is just going to prompt questions
such as this.

David J.


Re: [DOCS] Use of term Master/Slave

2017-08-07 Thread Peter Eisentraut
On 8/1/17 13:33, Andres Freund wrote:
> On 2017-07-31 21:13:48 +, [email protected] wrote:
>> The following documentation comment has been logged on the website:
>>
>> Page: https://www.postgresql.org/docs/9.6/static/release-9-6.html
>> Description:
>>
>> Wondering why PostgreSQL still uses the terms master and slave when there
>> are other terms like primary/secondary that can be used in the same manner. 
> 
> Yea, I think we should be more careful from now on. I think several
> people already try, but it's not been a concerted effort so far.

Here is a patch to remove remaining uses of "slave" in replication contexts.

Remaining uses are in the Tcl API, which we can't do anything about, and
in a plpgsql test, where it is used for foreign key relationships.  (I'm
not sure what the use in the dblink test that I patched was meant for,
so I just removed it.)  Old release notes are not touched.

-- 
Peter Eisentraut  http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
From 5cec779d62c9a4e3cf8ff6c5d7a825301ca03ada Mon Sep 17 00:00:00 2001
From: Peter Eisentraut 
Date: Mon, 7 Aug 2017 17:42:47 -0400
Subject: [PATCH] Remove uses of "slave" in replication contexts

This affects mostly code comments, some documentation, and tests.
Official APIs already used "standby".
---
 contrib/dblink/expected/dblink.out|  6 +-
 contrib/dblink/sql/dblink.sql |  6 +-
 doc/src/sgml/high-availability.sgml   |  2 +-
 doc/src/sgml/ref/pgupgrade.sgml   |  4 +-
 src/backend/access/transam/commit_ts.c|  2 +-
 src/backend/access/transam/multixact.c|  2 +-
 src/backend/access/transam/varsup.c   |  4 +-
 src/backend/catalog/namespace.c   |  4 +-
 src/backend/commands/variable.c   |  4 +-
 src/backend/executor/execMain.c   |  4 +-
 src/backend/replication/walsender.c   |  2 +-
 src/backend/storage/ipc/procarray.c   |  2 +-
 src/backend/tcop/utility.c|  2 +-
 src/bin/pg_dump/pg_dump.c |  2 +-
 src/bin/pg_rewind/RewindTest.pm   |  2 +-
 src/test/modules/commit_ts/t/002_standby.pl   |  4 +-
 src/test/modules/commit_ts/t/003_standby_2.pl |  2 +-
 src/test/recovery/t/002_archiving.pl  |  2 +-
 src/test/recovery/t/005_replay_delay.pl   |  2 +-
 src/test/recovery/t/009_twophase.pl   | 86 +--
 src/test/recovery/t/012_subtransactions.pl| 62 +--
 21 files changed, 103 insertions(+), 103 deletions(-)

diff --git a/contrib/dblink/expected/dblink.out 
b/contrib/dblink/expected/dblink.out
index 4b6d26e574..511691e57f 100644
--- a/contrib/dblink/expected/dblink.out
+++ b/contrib/dblink/expected/dblink.out
@@ -270,7 +270,7 @@ SELECT *
 FROM dblink('SELECT * FROM foo') AS t(a int, b text, c text[])
 WHERE t.a > 7;
 ERROR:  connection not available
--- put more data into our slave table, first using arbitrary connection syntax
+-- put more data into our table, first using arbitrary connection syntax
 -- but truncate the actual return value so we can use diff to check for success
 SELECT substr(dblink_exec(connection_parameters(),'INSERT INTO foo 
VALUES(10,''k'',''{"a10","b10","c10"}'')'),1,6);
  substr 
@@ -285,7 +285,7 @@ SELECT dblink_connect(connection_parameters());
  OK
 (1 row)
 
--- put more data into our slave table, using persistent connection syntax
+-- put more data into our table, using persistent connection syntax
 -- but truncate the actual return value so we can use diff to check for success
 SELECT substr(dblink_exec('INSERT INTO foo 
VALUES(11,''l'',''{"a11","b11","c11"}'')'),1,6);
  substr 
@@ -610,7 +610,7 @@ SELECT dblink_connect('myconn',connection_parameters());
  OK
 (1 row)
 
--- put more data into our slave table, using named persistent connection syntax
+-- put more data into our table, using named persistent connection syntax
 -- but truncate the actual return value so we can use diff to check for success
 SELECT substr(dblink_exec('myconn','INSERT INTO foo 
VALUES(11,''l'',''{"a11","b11","c11"}'')'),1,6);
  substr 
diff --git a/contrib/dblink/sql/dblink.sql b/contrib/dblink/sql/dblink.sql
index 681cf6a6e8..b093fa6722 100644
--- a/contrib/dblink/sql/dblink.sql
+++ b/contrib/dblink/sql/dblink.sql
@@ -160,14 +160,14 @@ CREATE FUNCTION connection_parameters() RETURNS text 
LANGUAGE SQL AS $f$
 FROM dblink('SELECT * FROM foo') AS t(a int, b text, c text[])
 WHERE t.a > 7;
 
--- put more data into our slave table, first using arbitrary connection syntax
+-- put more data into our table, first using arbitrary connection syntax
 -- but truncate the actual return value so we can use diff to check for success
 SELECT substr(dblink_exec(connection_parameters(),'INSERT INTO foo 
VALUES(10,''k'',''{"a10","b10","c10"}'')'),1,6);
 
 -- create a persistent connection
 SELECT dblink_connect(connection_parameters());
 
--- put more data into o