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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 31, 2023, 19:05 UTC
Message-ID: <xmqqo7o8eo83.fsf@gitster.g>
In-Reply-To: <xmqqsfdkep2b.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

[jc: I forgot to cc the area expert, so here is a forward]

Show 68 quoted lines

> Kristoffer Haugsbakk <code@khaugsbakk.name> 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.