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

Jeff King [off-list ref] writes:

On Sat, Oct 09, 2021 at 11:33:38AM -0500, Rob Browning wrote:

quoted

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.

quoted

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 [off-list ref] 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.

On Mon, Oct 11, 2021 at 01:04:48PM -0700, Junio C Hamano wrote:

quoted

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).

Yeah, I was hoping that calling it out explicitly would help to serve
that purpose, even if they can't see it. But it's still pretty subtle.

I did consider annotating it more directly in the example, but I was
worried it would end up being syntactically confusing, because we don't
have a well-known convention for marking "end of line". But the example
you showed:

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 [off-list ref] 1465981137 +0000
  gpgsig -----BEGIN PGP SIGNATURE-----
   Version: GnuPG v1
   $
   iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
   HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
   DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA

perhaps?

...coupled with the explanation you gave is not too bad. I had thought
to maybe do something like:

   gpgsig -----BEGIN PGP SIGNATURE-----
   _Version: GnuPG v1
   _
   _iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
   _HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
   _DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA

but that is pretty ugly. I like yours much better.

-Peff