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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 22, 2024, 16:38 UTC
Message-ID: <xmqqr0h4h2sz.fsf@gitster.g>
In-Reply-To: <2926790.e9J7NaK4W3@cayenne>

Jean-Noël AVILA <jn.avila@free.fr> 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.