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

From: Jeff King <peff@peff.net>
Date: Oct 12, 2021, 02:08 UTC
Message-ID: <YWTuAOjqK6fy9ZRT@coredump.intra.peff.net>
In-Reply-To: <xmqq4k9ncopr.fsf@gitster.g>

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

Show 14 quoted lines

> > 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:

Show 20 quoted lines

> 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?

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