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

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