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

[Junio C Hamano <gitster@pobox.com>]

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.