From: Ramsay Jones Date: Wed, 08 Oct 2025 21:54:25 GMT Subject: Re: [PATCH v2 3/4] doc: sparse-checkout.adoc: fix asciidoc warnings Message-ID: <05bc7369-af6a-45db-a792-a452d2442dbb@ramsayjones.plus.com> In-Reply-To: On 08/10/2025 4:57 am, Elijah Newren wrote: > On Thu, Oct 2, 2025 at 3:13 PM Ramsay Jones 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. > >> 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