RFC: Conscious language in the Binutils

[DJ Delorie]

Nick Clifton via Binutils <binutils@sourceware.org> writes:
>   Inside Red Hat there is an initiative to address some of the language
>   used in open source projects, making it more inclusive:

I will open by saying that I'm *in general* opposed to such things, as
words are about communication, and when a large group of people share
one understanding of a word, rewriting to avoid alternate meanings can
reduce communications.  Plus, if start prohibiting colors, eventually we
run out of crayons.

I'm not opposed to rewriting cases where harm was *intended*, of course.
Just saying it's not, er, black and white, but shades of grey.  Or gray.
(No offense intended towards the elderly, or the Mimbari)

However, I will take a moment to actually review the patch on technical
terms, for posterity, as I am not opposed to rewrites for clarity ;-)

> -    /* In the multi-got case, assigned_gotno of the master got_info
> +    /* In the multi-got case, assigned_gotno of the main got_info

This is a harmless change, but...

> -  /* GG is now the master GOT, and G is the primary GOT.  */
> +  /* GG is now the main GOT, and G is the primary GOT.  */

It makes this comment pretty much nonsensical (but not much more
nonsensical than before).

> -  fixS *master;			/* The literal reloc.  */
> +  fixS *litrelocs;		/* The literal reloc.  */

"master" is a common word in English.  "litrelocs" is not.  If you
desire clarity here, spell it out as "literal_relocs".  We have plenty
of storage space.

> -  fixS *slaves;			/* Head of linked list of lituses.  */
> +  fixS *lituses;		/* Head of linked list of lituses.  */

Likewise.  Also, comments should never use word-mashups like that unless
they refer to a specific type (and even then should be marked up somehow
to make that obvious).

However, some semantics have been lost here.  The master/slave wordings
implied that one list was, for lack of a politically correct word, the
master.  "relocs" and "uses" do not imply that relationship as strongly.

> -  0	\(indirect line string, offset: 0x.*\): master directory
> +  0	\(indirect line string, offset: 0x.*\): main directory
>    1	\(indirect line string, offset: 0x.*\): secondary directory

This change is nonsense, but it was nonsense before.  The correct
pairing for "secondary" is "primary".  Either that should be listed
here, or if "primary" is intentionally omitted, there should be a
comment saying why, or better terms should be used.

> -  0	0 0x00000000000000000000000000000000	\(indirect line string, offset: 0x.*\): master source file
> +  0	0 0x00000000000000000000000000000000	\(indirect line string, offset: 0x.*\): main source file
>    1	1 0x00000000000000000000000000000000	\(indirect line string, offset: 0x.*\): secondary source file

Likewise.

> -	.file 0 "master directory/master source file"
> +	.file 0 "main directory/main source file"

That wording would propogate here, etc.

> -manipulated while holding the master Workqueue lock.  Relatively few
> +manipulated while holding the controlling Workqueue lock.  Relatively few

This in no way averts the politically problematic meaning of "master"
anyway.  If you mean "a lock which covers a wide area including other
locks of smaller scope" perhaps "blanket lock" or "module-wide
meta-lock"?

> -  // The master GOT information.
> -  Mips_got_info<size, big_endian>* master_got_info_;
> +  // The main GOT information.
> +  Mips_got_info<size, big_endian>* main_got_info_;
>    // The  primary GOT information.
>    Mips_got_info<size, big_endian>* primary_got_;
>    // Secondary GOT fixups.

This patch has master/main *and* primary *and* secondary.  Needs a
rethink anyway.  What are the actual purposes of these three lists?  Are
there better terms that make it obvious when a programmer should choose
each, or what implied rules (readonly, atomic, arch-dependent, etc)
exist for each?  Blindly replacing one word with a different one does
not always convey the same meaning.

> -// We want to avoid a master list of targets, which implies using a
> +// We want to avoid a built-in list of targets, which implies using a

Example where a different replacment choice results in a better
understanding of where the list comes from.  Ok.

> -/* The master list of all plugins.  */
> +/* The list of all plugins.  */

This is ok too :-)