Thread: Doc patch: replace 'salesmen' with 'salespeople'
Hi Hackers,
I just spotted an unnecessarily gendered example involving a 'salesmen'
table in the UPDATE docs. Here's a patch that changes that to
'salespeople'.
- ilmari
From fde378ccd44c15f827a3c22630265f477d70d748 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Thu, 24 Mar 2022 18:21:48 +0000
Subject: [PATCH] doc: replace 'salesmen' with 'salespeople'
---
doc/src/sgml/ref/update.sgml | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index 3a0285df79..a1fc4bbb4a 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -387,21 +387,21 @@
<para>
Update contact names in an accounts table to match the currently assigned
- salesmen:
+ salespeople:
<programlisting>
UPDATE accounts SET (contact_first_name, contact_last_name) =
- (SELECT first_name, last_name FROM salesmen
- WHERE salesmen.id = accounts.sales_id);
+ (SELECT first_name, last_name FROM salespeople
+ WHERE salespeople.id = accounts.sales_id);
</programlisting>
A similar result could be accomplished with a join:
<programlisting>
UPDATE accounts SET contact_first_name = first_name,
contact_last_name = last_name
- FROM salesmen WHERE salesmen.id = accounts.sales_id;
+ FROM salespeople WHERE salespeople.id = accounts.sales_id;
</programlisting>
However, the second query may give unexpected results
- if <structname>salesmen</structname>.<structfield>id</structfield> is not a unique key, whereas
- the first query is guaranteed to raise an error if there are multiple
+ if <structname>salespeople</structname>.<structfield>id</structfield> is not a unique key,
+ whereas the first query is guaranteed to raise an error if there are multiple
<structfield>id</structfield> matches. Also, if there is no match for a particular
<structname>accounts</structname>.<structfield>sales_id</structfield> entry, the first query
will set the corresponding name fields to NULL, whereas the second query
--
2.30.2
> On 24 Mar 2022, at 19:34, Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> wrote: > I just spotted an unnecessarily gendered example involving a 'salesmen' > table in the UPDATE docs. Here's a patch that changes that to > 'salespeople'. No objections to changing that, it's AFAICT the sole such usage in the docs. > Update contact names in an accounts table to match the currently assigned > - salesmen: > + salespeople: > <programlisting> > UPDATE accounts SET (contact_first_name, contact_last_name) = > - (SELECT first_name, last_name FROM salesmen > - WHERE salesmen.id = accounts.sales_id); > + (SELECT first_name, last_name FROM salespeople > + WHERE salespeople.id = accounts.sales_id); This example is a bit confusing to me, it's joining on accounts.sales_id to get the assigned salesperson, but in the example just above we are finding the salesperson by joining on accounts.sales_person. Shouldn't this be using the employees table to keep it consistent? (which also avoids the gendered issue raised here) The same goes for the second example. Or am I missing something? -- Daniel Gustafsson https://vmware.com/
Daniel Gustafsson <daniel@yesql.se> writes:
>> On 24 Mar 2022, at 19:34, Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> wrote:
>
>> I just spotted an unnecessarily gendered example involving a 'salesmen'
>> table in the UPDATE docs. Here's a patch that changes that to
>> 'salespeople'.
>
> No objections to changing that, it's AFAICT the sole such usage in the docs.
There's a mention of the travelling salesman problem in the GEQO docs
(and one in the code comments), but that's the established name for that
problem (although I do note the Wikipedia page says it's "also called
the travelling salesperson problem").
>> Update contact names in an accounts table to match the currently assigned
>> - salesmen:
>> + salespeople:
>> <programlisting>
>> UPDATE accounts SET (contact_first_name, contact_last_name) =
>> - (SELECT first_name, last_name FROM salesmen
>> - WHERE salesmen.id = accounts.sales_id);
>> + (SELECT first_name, last_name FROM salespeople
>> + WHERE salespeople.id = accounts.sales_id);
>
> This example is a bit confusing to me, it's joining on accounts.sales_id to get
> the assigned salesperson, but in the example just above we are finding the
> salesperson by joining on accounts.sales_person. Shouldn't this be using the
> employees table to keep it consistent? (which also avoids the gendered issue
> raised here) The same goes for the second example. Or am I missing something?
Yeah, you're right. The second section (added by Tom in commit
8f889b1083f) is inconsistent with the first half in both table and
column names. Here's a patch that makes it all consistent, eliminating
the salesmen references completely, rather than renaming them.
- ilmari
From 5dbbba776d6d53eb3abcbf028f6c94b4e4c0e75f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Fri, 25 Mar 2022 12:49:14 +0000
Subject: [PATCH] doc: make UPDATE FROM examples consistent
The original first half of the example used an employees table and an
accounts.sales_person foreign key column, while the second half (added
in commit 8f889b1083f) used a salesmen table and accounts.sales_id
for the foreign key.
This makes everything use the original names, thus eliminating the
unnecessarily gendered salesmen table.
---
doc/src/sgml/ref/update.sgml | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index 3a0285df79..2ab24b0523 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -387,23 +387,23 @@
<para>
Update contact names in an accounts table to match the currently assigned
- salesmen:
+ salespeople:
<programlisting>
UPDATE accounts SET (contact_first_name, contact_last_name) =
- (SELECT first_name, last_name FROM salesmen
- WHERE salesmen.id = accounts.sales_id);
+ (SELECT first_name, last_name FROM employees
+ WHERE employees.id = accounts.sales_person);
</programlisting>
A similar result could be accomplished with a join:
<programlisting>
UPDATE accounts SET contact_first_name = first_name,
contact_last_name = last_name
- FROM salesmen WHERE salesmen.id = accounts.sales_id;
+ FROM employees WHERE employees.id = accounts.sales_person;
</programlisting>
However, the second query may give unexpected results
- if <structname>salesmen</structname>.<structfield>id</structfield> is not a unique key, whereas
+ if <structname>employees</structname>.<structfield>id</structfield> is not a unique key, whereas
the first query is guaranteed to raise an error if there are multiple
<structfield>id</structfield> matches. Also, if there is no match for a particular
- <structname>accounts</structname>.<structfield>sales_id</structfield> entry, the first query
+ <structname>accounts</structname>.<structfield>sales_person</structfield> entry, the first query
will set the corresponding name fields to NULL, whereas the second query
will not update that row at all.
</para>
--
2.30.2
> On 25 Mar 2022, at 13:59, Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> wrote: > > Daniel Gustafsson <daniel@yesql.se> writes: > >>> On 24 Mar 2022, at 19:34, Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> wrote: >> >>> I just spotted an unnecessarily gendered example involving a 'salesmen' >>> table in the UPDATE docs. Here's a patch that changes that to >>> 'salespeople'. >> >> No objections to changing that, it's AFAICT the sole such usage in the docs. > > There's a mention of the travelling salesman problem in the GEQO docs > (and one in the code comments), but that's the established name for that > problem (although I do note the Wikipedia page says it's "also called > the travelling salesperson problem"). I would be slightly worried about "git grep'ability" when changing such an established name (even though the risk might be miniscule here). Unless it's deemed controversial I would err on the side of caution and leave this alone. >>> Update contact names in an accounts table to match the currently assigned >>> - salesmen: >>> + salespeople: >>> <programlisting> >>> UPDATE accounts SET (contact_first_name, contact_last_name) = >>> - (SELECT first_name, last_name FROM salesmen >>> - WHERE salesmen.id = accounts.sales_id); >>> + (SELECT first_name, last_name FROM salespeople >>> + WHERE salespeople.id = accounts.sales_id); >> >> This example is a bit confusing to me, it's joining on accounts.sales_id to get >> the assigned salesperson, but in the example just above we are finding the >> salesperson by joining on accounts.sales_person. Shouldn't this be using the >> employees table to keep it consistent? (which also avoids the gendered issue >> raised here) The same goes for the second example. Or am I missing something? > > Yeah, you're right. The second section (added by Tom in commit > 8f889b1083f) is inconsistent with the first half in both table and > column names. Here's a patch that makes it all consistent, eliminating > the salesmen references completely, rather than renaming them. I think this is an improvement, both in language and content. The example does show off a strange choice of schema but it's after all an example of syntax and not data modelling. Barring objections I plan to go ahead with this. -- Daniel Gustafsson https://vmware.com/