Subject: Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax

From: Junio C Hamano <[email-masked]>
Date: Thu, 22 Feb 2024 08:38:36 -0800

Jean-Noël AVILA <[email-masked]> writes:

>> So, perhaps we do not have to do a lot of 'word' -> _word_
>> replacements, hopefully?

> ... At least, we 
> should try to stick as much as possible to the common markup _ for emphasis.

OK, that clears up my confusion.  Thanks.

We do not want to rely on an external party indefinitely maintaining
what they consider backward compatibility wart, so the mark-up migration
would need to happen before it becomes too late.

> This would have the added benefit of differentiating single quotes from 
> backticks, because single quotes would completely disappear in the end, except 
> when a real single quote is needed.

Given enough time, yes.  Or we can actively disable AsciiDoctor's
compatibility mode and/or tweak asciidoc.conf to do the equivalent
for AsciiDoc, to start early.  Until then, we cannot really use "a
real single quote", right?

> For the migration to "standard" asciidoc, I would also recommend using "=" 
> prefix for titles instead of underlines which require changing two lines when 
> modifying  a title and are a pain for translators in languages with variable 
> width characters.

I personally strongly prefer the underline format because I care
about readability of sources, but that is just me.  Is that also
getting deprecated?

Thanks.