Re: [PATCH v2 3/4] doc: sparse-checkout.adoc: fix asciidoc warnings

From: Ramsay Jones <ramsay@ramsayjones.plus.com>
Date: Oct 8, 2025, 21:54 UTC
Message-ID: <05bc7369-af6a-45db-a792-a452d2442dbb@ramsayjones.plus.com>
In-Reply-To: <CABPp-BEYF6MdcaXU1qAYctRBAt754j7PGkE3Tgjmm03bBkBjNQ@mail.gmail.com>

On 08/10/2025 4:57 am, Elijah Newren wrote:

Show 28 quoted lines

> On Thu, Oct 2, 2025 at 3:13 PM Ramsay Jones <ramsay@ramsayjones.plus.com> wrote:
>>
>> Both asciidoc and asciidoctor issue warnings about 'list item index:
>> expected n got n-1' for n=1->7 on lines 928, 931, 951, 974, 980, 1033
>> and 1049. 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 17. (asciidoc only complains about the first instance of this,
>> while asciidoctor complains about them all, on lines 95, 258, 303, 316,
>> 545, 612, 752, 824, 895, 923 and 1053). 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 severn, rather than zero to six. Fortunately, this does not
>> require altering additional text, since the enumeration of 'Known Bugs'
>> is not referred to anywhere else in the document.
>>
>> 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 apparent (sub-)titles are
>> not marked up with sub-title syntax, so add some '=== ' prefix(s) to the
>> relevant headings.
> 
> Kinda surprising; if it's complaining about lack of title nesting, I'd
> think you'd need a '= title =' somewhere before using '== title =='.
> Maybe jumping skipping one nesting level it's fine with, but skipping
> two is where the problem starts?  No idea.

I have no idea either! see previous email.

Show 20 quoted lines

> 
>> In addition to the warnings, address some other formatting issues:
>>
>>   - the use of heavily nested unordered lists is not reflected in the
>>     output (making the file totally unreadable) because each level of
>>     nesting requires a different syntax. (i.e. replace '*' with '**'
>>     for the second level, '*' with '***' for the third level, etc.)
>>   - make use of literal blocks and manual indentation to get asciidoc
>>     and asciidoctor to display even remotely similar output.
>>   - make use of labelled lists, in some places, to get a similar looking
>>     output to the input, for both asciidoc and asciidoctor.
>>   - replace the trailing space in: `git grep ${SEARCH_TERM} OLDREV `
>>     otherwise the entire line in which that appears is removed from
>>     the output.
> 
> Again, sorry for putting you through all this; I had assumed
> Documentation/technical/ was stuff meant for other Git developers to
> see and didn't need to be typeset with asciidoc or asciidoctor and had
> never attempted to run the documents I added there under either.
> Someone else renamed them to .adoc...

No problem. I already floated the idea of renaming these files to .txt and removing them from the meson build (in my cover letter), but I had to assume that it was now the policy for these docs to be formatted.

I was very conscious of me butchering your documents (and Derrick's) to make an attempt to fix-up the formatting. It was quite frustrating to find that asciidoc and asciidoctor don't agree on how that should be done ... (frequently). :(

[I was hopeful that an asciidoc guru would help me fix the two remaining problems (that I know about) - fingers crossed!]

> I skimmed through the document, and it all looked like typesetting
> changes which don't impair the readability of the source text, so
> seems fine to me.  (Same with the previous patch)

I hoped that would be the case, but I must say that I think you are being very generous! ;)

Thanks.

ATB, Ramsay Jones