Re: [PATCH 1/1] signature-format.txt: add space to fix gpgsig continuation line

[Junio C Hamano <gitster@pobox.com>]

Jeff King <peff@peff.net> writes:

> On Sat, Oct 09, 2021 at 11:33:38AM -0500, Rob Browning wrote:
>
>> Add a space to the blank line after the version header in the example
>> gpgsig commit header.
>
> Thanks, this is a good catch. The space is important for the header
> continuation.
>
>> diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt
>> index 2c9406a56a..6acc0b1247 100644
>> --- a/Documentation/technical/signature-format.txt
>> +++ b/Documentation/technical/signature-format.txt
>> @@ -78,7 +78,7 @@ author A U Thor <author@example.com> 1465981137 +0000
>>  committer C O Mitter <committer@example.com> 1465981137 +0000
>>  gpgsig -----BEGIN PGP SIGNATURE-----
>>   Version: GnuPG v1
>> -
>> + 
>>   iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
>>   HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
>>   DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA
>
> The patch is quite subtle to read, of course. :) But more importantly,
> it is subtle for somebody reading the documentation to notice. Perhaps
> it's worth calling it out explicitly? E.g., squashing in something like:
> ...
> -  (content is preceded by a space)
> +  (content is preceded by a space; note that this includes the
> +   "empty" line between the GnuPG header and signature, which
> +   consists of a single space).
>  - example: commit with subject `signed commit`

To those who are reading on paper or on terminal, the difference
will not be even seen.  It only can be _found_ if you are in an
editor or a pager and explicitly look for a trailing whitespace (or
told your tool to highlight such for you).

I wonder if we can have some typesetting convention for this part of
the documentation.  Perhaps something like

    In the following example, the end of line that ends with a
    whitespace letter is highlighted with a "$" sign; if you are
    trying to recreate these example by hand, do not cut and paste
    them---they are there primarily to highlight extra whitespace at
    the end of some lines.

before a displayed material like this:

  committer C O Mitter <committer@example.com> 1465981137 +0000
  gpgsig -----BEGIN PGP SIGNATURE-----
   Version: GnuPG v1
   $
   iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
   HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
   DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA

perhaps?

I am reasonably sure that running "git am" on Rob's patch will by
default end up as a no-op patch, because auto-correcting whitespace
breakage is the default setting I use, and a change like the one
suggested above would help avoid such a problem, too.

Thanks.