Re: [PATCH 1/4] Documentation: use singular they when appropriate
- From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- Date
- Jun 7, 2021, 18:21 UTC
- Message-ID
- <878s3l4jod.fsf@evledraar.gmail.com>
- In-Reply-To
- <9ae26bcd-c6b7-682d-f895-3196c6c04ce2@gmail.com>
On Mon, Jun 07 2021, Derrick Stolee wrote:
Show 32 quoted lines
> On 6/7/2021 1:09 PM, Ævar Arnfjörð Bjarmason wrote: >> >> On Mon, Jun 07 2021, Derrick Stolee via GitGitGadget wrote: >> >>> From: Derrick Stolee <dstolee@microsoft.com> >>> >>> 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 <dstolee@microsoft.com> >> >> I think this is mostly an improvement, however: >> >>> .../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/ > > 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"...