Jeff King <peff@xxxxxxxx> 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@xxxxxxxxxxx> 1465981137 +0000
>> committer C O Mitter <committer@xxxxxxxxxxx> 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@xxxxxxxxxxx> 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.
