# [PATCH 0/4] technical docs in make build 1 messages from 2025-09-26 to 2025-09-26. Participants: Ramsay Jones. Thread: https://gitlist.dev/t/64207 ## Ramsay Jones, 2025-09-26 00:19 Subject: [PATCH 0/4] technical docs in make build Message-ID: URL: https://gitlist.dev/e/bcb3b3a3-bb13-4808-9363-442b5f9be05f%40ramsayjones.plus.com ``` I have been trying to get back to the 'misc build updates (part #3)' patches, so that I can send them to the list, but I have not been able to find a spare minute for quite some time. :( However, this sub-sequence of patches hangs together as a single theme and I need help to finish them up! (asciidoc is not my forte). The first patch adds some technical documents to the Makefile build which are already part of the meson build. In particular, the following are built by meson, but not by the Makefile: commit-graph.adoc directory-rename-detection.adoc packfile-uri.adoc remembering-renames.adoc repository-version.adoc rerere.adoc sparse-checkout.adoc sparse-index.adoc Although I am not convinced that some of these files were ever meant to be formatted by asciidoc, I have assumed that is the case for the purposes of this patch series. (otherwise, we should remove them from the meson build and rename the files instead). When I attempt to build the html docs, with patch #1 applied, on Linux: $ make html >out-doc 2>&1 $ grep SyntaxWarning out-doc | head -n1 :1: SyntaxWarning: invalid escape sequence '\S' $ grep SyntaxWarning out-doc | wc -l 524 $ $ asciidoc --version asciidoc 10.2.0 $ python3 --version Python 3.12.3 $ This is caused by the python version I am using, which was recently changed (in version 3.12) to issue the SyntaxWarning when a 'non-raw' string contains some escape sequences (here \S). [some versions prior to 3.12 used to issue a deprecation warning]. This is a known issue, see e.g. [0], which has been addressed by a patch [1], and as seen in [2] has been included in a new version 10.2.1 of asciidoc. [0] https://trac.macports.org/ticket/70039 [1] 1https://github.com/asciidoc-py/asciidoc-py/pull/267 [2] https://github.com/asciidoc-py/asciidoc-py/commits/main/ [cygwin does not have this problem, because the phython version is 3.9.16] So, ignoring that issue, we still see some warnings from asciidoc: $ grep WARNING out-doc asciidoc: WARNING: remembering-renames.adoc: line 13: list item index: expected 1 got 0 asciidoc: WARNING: remembering-renames.adoc: line 15: list item index: expected 2 got 1 asciidoc: WARNING: remembering-renames.adoc: line 17: list item index: expected 3 got 2 asciidoc: WARNING: remembering-renames.adoc: line 20: list item index: expected 4 got 3 asciidoc: WARNING: remembering-renames.adoc: line 23: list item index: expected 5 got 4 asciidoc: WARNING: remembering-renames.adoc: line 25: list item index: expected 6 got 5 asciidoc: WARNING: remembering-renames.adoc: line 29: list item index: expected 7 got 6 asciidoc: WARNING: remembering-renames.adoc: line 31: list item index: expected 8 got 7 asciidoc: WARNING: remembering-renames.adoc: line 33: list item index: expected 9 got 8 asciidoc: WARNING: remembering-renames.adoc: line 38: section title out of sequence: expected level 1, got level 2 asciidoc: WARNING: sparse-checkout.adoc: line 17: section title out of sequence: expected level 1, got level 2 asciidoc: WARNING: sparse-checkout.adoc: line 928: list item index: expected 1 got 0 asciidoc: WARNING: sparse-checkout.adoc: line 931: list item index: expected 2 got 1 asciidoc: WARNING: sparse-checkout.adoc: line 951: list item index: expected 3 got 2 asciidoc: WARNING: sparse-checkout.adoc: line 974: list item index: expected 4 got 3 asciidoc: WARNING: sparse-checkout.adoc: line 980: list item index: expected 5 got 4 asciidoc: WARNING: sparse-checkout.adoc: line 1033: list item index: expected 6 got 5 asciidoc: WARNING: sparse-checkout.adoc: line 1049: list item index: expected 7 got 6 $ I also tried asciidoctor, just for fun: $ asciidoctor --version Asciidoctor 2.0.20 [https://asciidoctor.org] Runtime Environment (ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux-gnu]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8) $ $ make USE_ASCIIDOCTOR=1 html >out-doctor 2>&1 $ grep WARNING out-doctor asciidoctor: WARNING: remembering-renames.adoc: line 13: list item index: expected 1, got 0 asciidoctor: WARNING: remembering-renames.adoc: line 15: list item index: expected 2, got 1 asciidoctor: WARNING: remembering-renames.adoc: line 17: list item index: expected 3, got 2 asciidoctor: WARNING: remembering-renames.adoc: line 20: list item index: expected 4, got 3 asciidoctor: WARNING: remembering-renames.adoc: line 23: list item index: expected 5, got 4 asciidoctor: WARNING: remembering-renames.adoc: line 25: list item index: expected 6, got 5 asciidoctor: WARNING: remembering-renames.adoc: line 29: list item index: expected 7, got 6 asciidoctor: WARNING: remembering-renames.adoc: line 31: list item index: expected 8, got 7 asciidoctor: WARNING: remembering-renames.adoc: line 33: list item index: expected 9, got 8 asciidoctor: WARNING: remembering-renames.adoc: line 38: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 94: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 141: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 142: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 184: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 185: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 257: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 288: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 289: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 290: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 397: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 424: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 485: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 486: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: remembering-renames.adoc: line 487: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 17: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 95: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 258: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 303: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 316: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 545: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 612: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 752: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 824: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 895: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 923: section title out of sequence: expected level 1, got level 2 asciidoctor: WARNING: sparse-checkout.adoc: line 928: list item index: expected 1, got 0 asciidoctor: WARNING: sparse-checkout.adoc: line 931: list item index: expected 2, got 1 asciidoctor: WARNING: sparse-checkout.adoc: line 951: list item index: expected 3, got 2 asciidoctor: WARNING: sparse-checkout.adoc: line 974: list item index: expected 4, got 3 asciidoctor: WARNING: sparse-checkout.adoc: line 980: list item index: expected 5, got 4 asciidoctor: WARNING: sparse-checkout.adoc: line 1033: list item index: expected 6, got 5 asciidoctor: WARNING: sparse-checkout.adoc: line 1049: list item index: expected 7, got 6 asciidoctor: WARNING: sparse-checkout.adoc: line 1053: section title out of sequence: expected level 1, got level 2 $ You can see that asciidoc only complains about the first 'section title out of sequence', whereas asciidoctor complains about them all. [asciidoctor also reports: Note: namesp. cut : stripped namespace before processing Git User Manual] Patch #2 was a nightmare which I really gave up on! :) An early attempt involved renumbering the 'outline list' at the top from 0->8 to 1->9 (I thought there was a way to start numbering at zero, but I lost a lot of time trying to do so, without any success). So, of course I 'just' tried global search/replace in vim to do the renumbering (backwards). This was a complete disaster (of course), which I 'fixed' many many times. (Not everything which is numbered is a section, there are 'cases' as well). In the end, I just disabled the 'outline' list, by removing the period on the numbers (again '0\. Assumptions' should have worked, but didn't) and fixing up the section titles without renumbering them. Note that asciidoctor mis-formats the 'ascii branch diagrams', which asciidoc formats correctly. I think there are other formatting problems left. In patch #3, the formatting changes are confined to the section titles and renumbering the 'known bugs' from 0->6 to 1->7. (I think I noticed some sub-sub lists which are not formatted correctly, but I don't seem to be able to see them now ...). In patch #4, most of the formatting changes relate to section titles, but I could not fix some inline text formatting starting at 'File Layouts' (within 'Commit-Graph Chains') with text that is monospaced with `` but also contains an '{' character. For example: `$OBJDIR/info/commit-graphs/graph-{hash}.graph` is monospaced (blue colour with asciidoc) up until the {hash}.graph which does not have any formatting. (It is not so noticeable with asciidoctor because the formatting consists of a *very* subtle gray background to the text which, to my eyes anyway, is almost not visible). I have tried several suggestions from an on-line asciidoc syntax cheatsheet such as: `$OBJDIR/info/commit-graphs/graph-\{hash\}.graph` `+$OBJDIR/info/commit-graphs/graph-{hash}.graph+` but nothing worked. Note that there are many similar instances of this problem (including just `{hash}`). Note also that asciidoctor did not render the second diagram correctly (the one in 'Merging commit-graph files'), but asciidoc was just fine. The remaining documents: directory-rename-detection.adoc packfile-uri.adoc repository-version.adoc rerere.adoc sparse-index.adoc all appear to be formatted correctly. So, I really need help with the asciidoc formatting, in patches #2->#4, which I am marking as RFC. Having said that, these patches represent an improvement over the existing documents in terms of formatting (just not by much!). Any help fixing up these patches would be much appreciated. :) Thanks. ATB, Ramsay Jones Ramsay Jones (4): doc: add some missing technical documents doc: remembering-renames.adoc: fix asciidoc warnings doc: sparse-checkout.adoc: fix asciidoc warnings doc: commit-graph.adoc: fix up some formatting Documentation/Makefile | 8 +++ Documentation/technical/commit-graph.adoc | 34 +++++----- .../technical/remembering-renames.adoc | 63 +++++++++---------- Documentation/technical/sparse-checkout.adoc | 38 +++++------ 4 files changed, 74 insertions(+), 69 deletions(-) -- 2.51.0 ```