Re: Doc patch: replace 'salesmen' with 'salespeople' - Mailing list pgsql-hackers

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