Re: [PATCH v5 2/4] docs: improve formatting in git-send-email documentation

[Ben Knoble <ben.knoble@gmail.com>]

> Le 30 mai 2025 à 09:28, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> Aditya Garg <gargaditya08@live.com> writes:
> 
>>>> -When `--compose` is used, git send-email will use the From, To, Cc, Bcc,
>>>> -Subject, Reply-To, and In-Reply-To headers specified in the message. If
>>>> -the body of the message (what you type after the headers and a blank
>>>> -line) only contains blank (or Git: prefixed) lines, the summary won't be
>>>> +When `--compose` is used, `git send-email` will use the 'From', 'To', 'Cc',
>>>> +'Bcc', 'Subject', 'Reply-To', and 'In-Reply-To' headers specified in the
>>>> +message. If the body of the message (what you type after the headers and a
>>>> +blank line) only contains blank (or Git: prefixed) lines, the summary won't be
>>> 
>>> Shouldn't 'Git:' in "or Git: prefixed" be marked-up somehow as well?
>>> 
>>> As these mail header names are all literal parts, shouldn't ehy be
>>> marked up like `To`, `Cc`, etc.?
>> 
>> I think its ok to let these remain in '', and deviate from the rules a bit.
>> If backticks are used, it will be a mess when rendered on the website.
> 
> I do not think I agree; bending the rule only because the density of
> literals in a single paragraph is too heavy does not sound like a
> good application of a rule---it is hard to justify such an
> exception.

To go a bit further, rendered HTML is also not the only output format, though I don’t think the markup here affects manual pages substantially? So using « the website » (which? presumably git-scm.com) as justification prioritizes the look of one output format over other concerns, no?

For plaintext viewing, consistency is probably helpful.  

> 
>>>> -    by 'c_rehash', or a single file containing one or more PEM format
>>>> -    certificates concatenated together: see verify(1) -CAfile and
>>>> -    -CApath for more information on these). Set it to an empty string
>>>> +    by `c_rehash`, or a single file containing one or more PEM format
>>>> +    certificates concatenated together). Set it to an empty string
>>> 
>>> What is this change about?  grammatical errors?  non existent links?
>>> cpan links?  It does not look any of these.
>> 
>> Non existing links. Checkout the website.
> 
> But I do not see any link in ...
> 
>>>> -    by 'c_rehash', or a single file containing one or more PEM format
>>>> -    certificates concatenated together: see verify(1) -CAfile and
>>>> -    -CApath for more information on these). Set it to an empty string
> 
> ... the text that was removed.  The reference to verify(1) is a
> command in the OpenSSL suite, right?
>