From: Junio C Hamano <gitster@pobox.com>
Date: Sat, 27 Sep 2025 01:36:36 GMT
Subject: Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting
Message-ID: <xmqqa52gad7f.fsf@gitster.g>
In-Reply-To: <3323ebff-f6ac-4065-8507-efd5a9e4a16d@ramsayjones.plus.com>

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

>> That is, which one of these do AsciiDoc and Asciidoctor want?
>> 
>>     Deleting graph-\{hash\} files
>>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> This is what I did and, with asciidoc anyway, looked fine.
>
>>     Deleting graph-\{hash\} files
>>     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> I just tried this, and it was fine also! :)
>
> Hmm, let me just try asciidoctor ...
>
> Well, with asciidoctor it requires the underlining to be exactly
> the same size as the text (ie the second example above), otherwise
> it mangles the heading (well it doesn't seem to recognize it as a
> heading at all. It looks like:
>
> Deleting graph-{hash} files ~~~~~~~~~
>
> So, not the first time asciidoc and asciidoctor differ in the rendered
> output. (yes, the number of ~ chars is not the same as the input).

Yeah, so the latter one (i.e. count escapes and mark-up letters when
computing how long your underline need to be) is required to please
both.  I knew AsciiDoc allowed a bit of slop and that is how your
experiment (the first one above) was fine.  I didn't know how large
a slop AsciiDoc allowed, but it seems at least we can be missing two
and the tool is still happy.

> So, I need to change the diff to extend the underlining on that
> heading, so both asciidoc and asciidoctor both render it correctly.

So it seems.

Thanks.