Subject: Re: [PATCH v2 1/9] CodingGuidelines: move period inside parentheses

From: Junio C Hamano <[email-masked]>
Date: Thu, 21 Dec 2023 13:03:36 -0800

"Josh Soref via GitGitGadget" <[email-masked]> writes:

> From: Josh Soref <[email-masked]>
>
> The contents within parenthesis should be omittable without resulting
> in broken text.
>
> Eliding the parenthesis left a period to end a run without any content.

Nobody seems to have commented on this one in the previous round,
but quite honestly, for this particular instance, I suspect that it
may become easier to read if we just lost these parentheses, as the
next sentence "You do not have to include more than ..." is just a
bit of extra material to support the first sentence like the one we
see in the parentheses.  Alternatively, moving that "You do not have
to" also inside the same parentheses might work slightly better.

It might be even easier to follow if we moved the list of "approved
headers" (and the "You do not have to ... more than one" note that
supports the "currently approved list") totally out of line by
making it a side note.

> Signed-off-by: Josh Soref <[email-masked]>
> ---
>  Documentation/CodingGuidelines | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 8ed517a5ca0..af94ed3a75d 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -450,7 +450,7 @@ For C programs:
>     one of the approved headers that includes it first for you.  (The
>     approved headers currently include "builtin.h",
>     "t/helper/test-tool.h", "xdiff/xinclude.h", or
> -   "reftable/system.h").  You do not have to include more than one of
> +   "reftable/system.h".)  You do not have to include more than one of
>     these.
>  
>   - A C file must directly include the header files that declare the