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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 26, 2025, 21:21 UTC
Message-ID: <xmqqwm5kap0r.fsf@gitster.g>
In-Reply-To: <c8e40336-0a16-4da9-b251-d166f80ffeb3@ramsayjones.plus.com>

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

Show 7 quoted lines

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

    Deleting graph-\{hash\} files
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~--

There is

    OPTIONS[[OPTIONS]]
    ------------------

that appears in MyFirstContribution.adoc (even though that is an illustration of what you would write in the source and never used), and

    `builtin_objectmode`
    ~~~~~~~~~~~~~~~~~~~~

that appears in gitattributes.adoc (this one is rendered), so I've been assuming that these characters necessary for mark-up do count.

I guess this is the same "prefix is easier to write, underling is harder to write correctly" theme? If we know which one is correct and can use the correct version, then I do prefer the underlined form.

Thanks.