Re: [PATCH v2 2/4] doc: remembering-renames.adoc: fix asciidoc warnings

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

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