Re: [PATCH] pretty-formats.txt: fix whitespace

From: Linus Arver <linusa@google.com>
Date: Sep 26, 2023, 18:52 UTC
Message-ID: <owlypm24sr6n.fsf@fine.c.googlers.com>
In-Reply-To: <CACZqfqCVsv-ZaSRWt_ejMn5f_U_1E2h7wsCgUg_50A+KHzOgkA@mail.gmail.com>

Josh Soref <jsoref@gmail.com> writes:

Show 13 quoted lines

> Junio C Hamano <gitster@pobox.com> wrote:
>> > * space before `(`
>>
>> If you mean by the above that we used to say
>>
>>         ... as described below(see linkgit:git-config[1]))
>>
>> and you added a SP before "(see", that is a definite improvement.  I
>> however didn't find an example of a line that lacks SP before '('
>> that got corrected to have a SP there.
>
> I'm pretty sure that's what I meant, but I can't find the change in my
> git reflog, and I'm not quite sure how I could have made that mistake.

I too would support this sort of fix (fixing a missing space before `(`).

WRT 2-space vs 1-space, I am not sure we need this because this is a stylistic issue. Same thing for the commas. I am much more in favor of changes that would actually help users find the information they need (e.g., fixing spelling mistakes so that users who type in the correct spelling can get the expected documentation hits).

FWIW we already have some guidelines about what is acceptable for doc patches in SubmittingPatches:

    We currently have a liberal mixture of US and UK English norms for
    spelling and grammar, which is somewhat unfortunate.  A huge patch that
    touches the files all over the place only to correct the inconsistency
    is not welcome, though.  Potential clashes with other changes that can
    result from such a patch are not worth it.  We prefer to gradually
    reconcile the inconsistencies in favor of US English, with small and
    easily digestible patches, as a side effect of doing some other real
    work in the vicinity (e.g. rewriting a paragraph for clarity, while
    turning en_UK spelling to en_US).  Obvious typographical fixes are much
    more welcomed ("teh -> "the"), preferably submitted as independent
    patches separate from other documentation changes.

and both the 2-space vs 1-space and comma changes seem to fall into the "not welcome" category.