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

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Thursday, 22 February 2024 17:38:36 CET Junio C Hamano wrote:
> 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?

The logic for managing single quotes as markup is that there should be a word 
boundary at the quote <SPC>'<letter> for opening and <letter>'<SPC> for 
closing, whereas for "real single quote" there's no space. This rule is 
"natural" when writing in English and writers don't pay attention.

> 
> > 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?
> 

The underline format is bound to be deprecated. Right now, Asciidoctor detects 
this formatting to infer a switch to compat-mode. That's why markup-quote 
works as expected with Asciidoctor in current documents.

> Thanks.
> 
>