Re: [RFC PATCH 4/4] doc: commit-graph.adoc: fix up some formatting

From: Ramsay Jones <ramsay@ramsayjones.plus.com>
Date: Sep 26, 2025, 23:30 UTC
Message-ID: <3323ebff-f6ac-4065-8507-efd5a9e4a16d@ramsayjones.plus.com>
In-Reply-To: <xmqqwm5kap0r.fsf@gitster.g>

On 26/09/2025 10:21 pm, Junio C Hamano wrote:

Show 18 quoted lines

> Ramsay Jones <ramsay@ramsayjones.plus.com> writes:
> 
>> I tried searching the web for the answer, without success, so went with
>> the 'prefix' style used here. However, when I read the above, it made me
>> look at out current docs and gitworkflows.adoc showed me I should have
>> used an '~' character instead.
>>
>> I just tried this and it works great (apart from having to \-quote the
>> '{' and '}' characters in one title), so a revised 'diff' is given below.
> 
> Oy.  It is one of the special things I am unsure about---would a
> character used for such quoting (e.g., backslash in this case) count
> as one display space to count the number of underlying characters?
> 
> 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).

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

BTW, the asciidoc version of this document has a date which appears after the initial heading (but it is the day before the 'last date updated' one at the end of the document) and I have no idea why it is there!

(To be clear, it does not appear in the asciidoctor rendering!)

ATB, Ramsay Jones