From: Ramsay Jones <ramsay@ramsayjones•plus.com>
To: Elijah Newren <newren@gmail•com>
Cc: GIT Mailing-list <git@vger•kernel.org>,
Patrick Steinhardt <ps@pks•im>, Derrick Stolee <stolee@gmail•com>,
Junio C Hamano <gitster@pobox•com>
Subject: Re: [PATCH v2 2/4] doc: remembering-renames.adoc: fix asciidoc warnings
Date: Wed, 8 Oct 2025 22:38:39 +0100 [thread overview]
Message-ID: <f75779d4-9a92-4681-ae91-83ca7724c655@ramsayjones.plus.com> (raw)
In-Reply-To: <CABPp-BGiziz6-7zyq+Z-f0g+JDPMpGuXanmXNEM=0hV-7jKNsQ@mail.gmail.com>
On 08/10/2025 4:51 am, Elijah Newren wrote:
> On Thu, Oct 2, 2025 at 3:13 PM Ramsay Jones <ramsay@ramsayjones•plus.com> wrote:
>>
>> Both asciidoc and ascidoctor issue warnings about 'list item index:
>> expected n got n-1' for n=1->9 on lines 13, 15, 17, 20, 23, 25, 29,
>> 31 and 33. In asciidoc, numbered lists must start at one, whereas this
>> file has a list starting at zero. Also, asciidoc and asciidoctor warn
>> about 'section title out of sequence: expected level 1, got level 2'
>> on line 38. (asciidoc only complains about the first instance of this,
>> while asciidoctor complains about them all, on lines 94, 141, 142,
>> 184, 185, 257, 288, 289, 290, 397, 424, 485, 486 and 487). These
>> warnings stem from the section titles not being correctly nested within
>> a document/chapter title.
>>
>> In order to address the first set of warnings, simply renumber the list
>> from one to nine, rather than zero to eight. This also requires altering
>> the text which refers to the section numbers, including other section
>> titles.
>>
>> In order to address the second set of warnings, change the section title
>> syntax from '=== title ===' to '== title ==', effectively reducing the
>> nesting level of the title by one. Also, some of the titles are given
>> over multiple lines (they are very long), with an title '===' prefix
>> on each line. This leads to them being treated as separate sections
>> with no body text (as you can see from the line numbers given for the
>> asciidoctor warnings, above). So, for these titles, turn them into a
>> single (long) line of text.
>>
>> In addition to the warnings, address some other formatting issues:
>>
>> - the ascii branch diagrams didn't format correctly on asciidoctor
>> so include them in a literal block.
>> - several blocks of text were intended to be formatted 'as is' but
>> were not included in a literal block.
>> - in section 8, format the (A)->(D) in the text description as a
>> literal with `` marks, since (C) is rendered as a copyright
>> symbol in html otherwise.
>> - in section 9, a sub-list of two items is not formatted as such.
>> change the '*' introducer to '**' to correct the sub-list format.
>
> Sorry to put you through all this work. I had no idea the stuff under
> Documentation/technical/ was ever meant to be run through
> asciidoc/asciidoctor. The .txt ending didn't hint at anything like
> this; I mean, sure lots of other files were put through those, but I
> assumed this directory was just stuff for other Git developers...
As I mentioned in my cover letter, I didn't think these documents were
ever meant to be submitted to asciidoc(tor) either, but had to assume
that the current policy required it; so, I had to show willing ... :)
If it was not already obvious, until this patch series I had managed to
completely avoid any knowledge of 'asciidoc standard markup' (which appears
to be anything but standard)!
>> -=== 0. Assumptions ===
>> +== 1. Assumptions ==
>
> It doesn't like '===' but is fine with '=='? I'm a bit surprised. If
> it was about nesting, wouldn't '==' also complain since there is no
> '=' headers anywhere.
>
Yep, '=' is a level 0 header, but the asciidoc message said 'expected
level 1, got level 2', so I just dropped it down one level and asciidoc(tor)
was happy!
Thanks.
ATB,
Ramsay Jones
next prev parent reply other threads:[~2025-10-08 21:41 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <https://lore.kernel.org/git/bcb3b3a3-bb13-4808-9363-442b5f9be05f@ramsayjones.plus.com/>
2025-10-02 22:12 ` [PATCH v2 0/4] technical docs in make build Ramsay Jones
2025-10-02 22:12 ` [PATCH v2 1/4] doc: add some missing technical documents Ramsay Jones
2025-10-08 6:45 ` Patrick Steinhardt
2025-10-08 19:00 ` Junio C Hamano
2025-10-08 22:01 ` Ramsay Jones
2025-10-08 22:33 ` Junio C Hamano
2025-10-08 21:56 ` Ramsay Jones
2025-10-02 22:12 ` [PATCH v2 2/4] doc: remembering-renames.adoc: fix asciidoc warnings Ramsay Jones
2025-10-08 3:51 ` Elijah Newren
2025-10-08 21:38 ` Ramsay Jones [this message]
2025-10-02 22:12 ` [PATCH v2 3/4] doc: sparse-checkout.adoc: " Ramsay Jones
2025-10-07 12:20 ` Kristoffer Haugsbakk
2025-10-07 22:17 ` Ramsay Jones
2025-10-08 3:57 ` Elijah Newren
2025-10-08 21:54 ` Ramsay Jones
2025-10-02 22:12 ` [PATCH v2 4/4] doc: commit-graph.adoc: fix up some formatting Ramsay Jones
2025-10-02 22:38 ` [PATCH v2 0/4] technical docs in make build Ramsay Jones
2025-10-16 20:02 ` [PATCH v3 " Ramsay Jones
2025-10-16 20:02 ` [PATCH v3 1/4] doc: remembering-renames.adoc: fix asciidoc warnings Ramsay Jones
2025-10-16 20:02 ` [PATCH v3 2/4] doc: sparse-checkout.adoc: " Ramsay Jones
2025-10-16 20:03 ` [PATCH v3 3/4] doc: commit-graph.adoc: fix up some formatting Ramsay Jones
2025-10-16 20:03 ` [PATCH v3 4/4] doc: add large-object-promisors.adoc to the docs build Ramsay Jones
2025-10-17 16:37 ` Ramsay Jones
2025-10-23 19:33 ` [PATCH v3 0/4] technical docs in make build Junio C Hamano
2025-10-23 20:06 ` Ramsay Jones
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=f75779d4-9a92-4681-ae91-83ca7724c655@ramsayjones.plus.com \
--to=ramsay@ramsayjones$(echo .)plus.com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=newren@gmail$(echo .)com \
--cc=ps@pks$(echo .)im \
--cc=stolee@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox