Re: Rendering back-ticks in plaintext docs (was Re: [PATCH] git-rebase.txt: use back-ticks consistently)

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 28, 2022, 16:59 UTC
Message-ID: <xmqqfsjolo5f.fsf@gitster.g>
In-Reply-To: <a01c1ff7-74a7-b32f-1a1e-a8f2e840ae31@github.com>

Derrick Stolee <derrickstolee@github.com> writes:

Show 14 quoted lines

>> I see Phillip spotted some of this already, but the "exec" change here
>> looks unwanted, i.e. let's use double quotes there.
>
> This is definitely an issue where I was looking at the HTML formatted
> output, which respects back-ticks. Thanks for pointing out that the
> text docs just ignore back-ticks. This seems problematic, in my opinion.
>
> Is it possible to update our doc formatting to convert back-ticks into
> something like single quotes? That would help these plain-text documents
> point out these places where exact strings are very important.
>
> I also have no idea where to look to make such a change, and it would be
> very wide-ranging. I just think that the plaintext docs are currently a
> lossy medium and we should work to improve that.

Looking at "man -l git-rebase.1" output, not the "doc-diff" output that renders to pure plain text by deliberately losing font information in the roff output, I think this change is OK. IOW, "git help -m rebase" shows these marked-up parts in bold on the terminal (and on the paper, but who prints manual pages theres days?), which is what we want.

If there is something we found in this episode that we might want to improve, it is doc-diff, I would think.

Thanks.