Re: [PATCH 1/4] Documentation: use singular they when appropriate

On Mon, Jun 07 2021, Derrick Stolee wrote:

On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote:

quoted

On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote:

quoted

From: Derrick Stolee <redacted>

There are several instances in our documentation where we refer to an
anonymous user as "a contributor" or "an integrator" or similar. To
avoid repeating this role, pronouns are used. Previous examples
chose a gender for this user, using "he/him" or "she/her" arbitrarily.

Replace these uses with "they/them" to ensure that these documentation
examples apply to all potential users without exception.

Signed-off-by: Derrick Stolee <redacted>

I think this is mostly an improvement, however:

quoted

 .../using-signed-tag-in-pull-request.txt      | 38 +++++++++----------

This is a quote from a mail of Junio's[1] (date and all). I don't think
it makes sense to copyedit that after the fact without at least editing
the header that indicates that it's a verbatim reproduction.

1. https://lore.kernel.org/git/7vehuyosaa.fsf@alter.siamese.dyndns.org/ (local)

That's a good point. It does look a little strange that there is
an email in our Documentation/ directory. I wondered if this was
included in the docs that get posted to git-scm.com, but I see that
the link I manually constructed [1] redirects to the GitHub mirror.

[1] https://git-scm.com/docs/howto/using-signed-tag-in-pull-request.txt

We have a few of those FWIW, try grepping for ^Subject Documentation/

It seems git-scm.com dosen't carry them, but googling around e.g. this
site does: https://gitirc.eu/howto/using-signed-tag-in-pull-request.html

As long as this file remains formatted as an archived email message,
the edits here are inappropriate. It's another question of whether the
files within Documentation/howto should be updated to be docs that can
be more easily posted in places like git-scm.com.

*Nod*, I have some unrelated patches to fix some of this state of
 affairs in Documentation/, but for now it's like that...

I do think there's a time & place for it though, and it's unfortunate
that we haven't done as much of this recently. We've had quite a few
"E-Mails of reference", and IMO we're better off with them in
Documentation/ than not at all, and if we require that they be formatted
into "normal" documentation we're probably closer to "not at all"...