Subject: Re: [PATCH 1/3] doc: interpret-trailers: remove trailing spaces

From: Junio C Hamano <[email-masked]>
Date: Fri, 31 Mar 2023 11:46:52 -0700

Kristoffer Haugsbakk <[email-masked]> writes:

>  $ git interpret-trailers <<EOF
>  > subject
> -> 
> +>
>  > message
> -> 
> +>
>  > see: HEAD~2
>  > EOF
>  subject

This example pretends as if the above was an interactive session the
writer of the documentation did with a shell in a terminal, and
these lines are trying to show that each line is prefixed with $PS2
(the secondary prompt string given by the shell for continued
lines).

Taking that fact into account, it is arguably more correct to keep
these spaces rather than removing them like this patch does, but of
course it does not make a practical difference, because these spaces
are invisible unless the reader reads the source documentation pages
without passing them through AsciiDoc machinery.

The only folks that would be helped by this patch are those of us
who edit one of these four lines of the source file (perhaps by
replacing '>' with '|', such a patch tries to show use of a
different $PS2) and are annoyed to see trailing whitespaces their
patch inherited from the original trigger "git diff --check"; I
wonder if that is a good enough justification.

I, however, do wonder if we should make our example more friendly to
cutting and pasting.  And I would not mind it if we got rid of these
4 trailing whitespaces as a side effect of such an effort.

One way to do so, while still pretending to show an actual session
with an interactive shell, may be to give the example with an empty
string set to $PS2, i.e.

    $ git interpret-trailers <<\EOF
    subject

    message

    see: HEAD~2
    EOF
    subject
    ...

but then it makes it a bit harder to see what is input and what is
output.  Showing with a separate intermediate file, i.e.

    $ cat sample-message.txt
    subject

    message

    see: HEAD~2
    $ git interpret-trailers <sample-message.txt
    subject
    ...

might make the result slightly easier to follow.  I dunno.

The same comment applies to the other hunk.

Thanks.