From: Elijah Newren <newren@gmail.com>
Date: Wed, 08 Oct 2025 03:57:41 GMT
Subject: Re: [PATCH v2 3/4] doc: sparse-checkout.adoc: fix asciidoc warnings
Message-ID: <CABPp-BEYF6MdcaXU1qAYctRBAt754j7PGkE3Tgjmm03bBkBjNQ@mail.gmail.com>
In-Reply-To: <20251002221233.541844-4-ramsay@ramsayjones.plus.com>

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.

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


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)