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

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Feb 24, 2024, 18:28 UTC
Message-ID: <6079595.lOV4Wx5bFT@cayenne>
In-Reply-To: <xmqqr0h4h2sz.fsf@gitster.g>

On Thursday, 22 February 2024 17:38:36 CET Junio C Hamano wrote:

Show 7 quoted lines

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

Show 9 quoted lines

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

Show 6 quoted lines

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

Show 6 quoted lines

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