On Mon, Oct 11, 2021 at 01:04:48PM -0700, Junio C Hamano wrote: > > 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 <committer@xxxxxxxxxxx> 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
