{"thread":{"id":"64207","subject":"[PATCH 0/4] technical docs in make build","startedAt":"2025-09-26T00:23:05Z","lastAt":"2025-09-26T00:23:05Z","messageCount":1,"participants":["Ramsay Jones"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"527382","messageId":"bcb3b3a3-bb13-4808-9363-442b5f9be05f@ramsayjones.plus.com","threadId":"64207","inReplyTo":null,"subject":"[PATCH 0/4] technical docs in make build","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2025-09-26T00:19:56Z","receivedAt":"2025-09-26T00:23:05Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\nI have been trying to get back to the 'misc build updates (part #3)'\npatches, so that I can send them to the list, but I have not been able\nto find a spare minute for quite some time. :(\n\nHowever, this sub-sequence of patches hangs together as a single theme and\nI need help to finish them up! (asciidoc is not my forte).\n\nThe first patch adds some technical documents to the Makefile build which\nare already part of the meson build. In particular, the following are\nbuilt by meson, but not by the Makefile:\n\n    commit-graph.adoc\n    directory-rename-detection.adoc\n    packfile-uri.adoc\n    remembering-renames.adoc\n    repository-version.adoc\n    rerere.adoc\n    sparse-checkout.adoc\n    sparse-index.adoc\n\nAlthough I am not convinced that some of these files were ever meant to be\nformatted by asciidoc, I have assumed that is the case for the purposes of\nthis patch series. (otherwise, we should remove them from the meson build\nand rename the files instead).\n\nWhen I attempt to build the html docs, with patch #1 applied, on Linux:\n\n  $ make html >out-doc 2>&1\n\n  $ grep SyntaxWarning out-doc | head -n1\n  <unknown>:1: SyntaxWarning: invalid escape sequence '\\S'\n  $ grep SyntaxWarning out-doc | wc -l\n  524\n  $ \n\n  $ asciidoc --version\n  asciidoc 10.2.0\n  $ python3 --version\n  Python 3.12.3\n  $ \n\nThis is caused by the python version I am using, which was recently changed\n(in version 3.12) to issue the SyntaxWarning when a 'non-raw' string contains\nsome escape sequences (here \\S). [some versions prior to 3.12 used to issue\na deprecation warning].\n\nThis is a known issue, see e.g. [0], which has been addressed by a patch [1],\nand as seen in [2] has been included in a new version 10.2.1 of asciidoc.\n\n  [0] https://trac.macports.org/ticket/70039\n  [1] 1https://github.com/asciidoc-py/asciidoc-py/pull/267\n  [2] https://github.com/asciidoc-py/asciidoc-py/commits/main/\n\n[cygwin does not have this problem, because the phython version is 3.9.16]\n\nSo, ignoring that issue, we still see some warnings from asciidoc:\n\n  $ grep WARNING out-doc\n  asciidoc: WARNING: remembering-renames.adoc: line 13: list item index: expected 1 got 0\n  asciidoc: WARNING: remembering-renames.adoc: line 15: list item index: expected 2 got 1\n  asciidoc: WARNING: remembering-renames.adoc: line 17: list item index: expected 3 got 2\n  asciidoc: WARNING: remembering-renames.adoc: line 20: list item index: expected 4 got 3\n  asciidoc: WARNING: remembering-renames.adoc: line 23: list item index: expected 5 got 4\n  asciidoc: WARNING: remembering-renames.adoc: line 25: list item index: expected 6 got 5\n  asciidoc: WARNING: remembering-renames.adoc: line 29: list item index: expected 7 got 6\n  asciidoc: WARNING: remembering-renames.adoc: line 31: list item index: expected 8 got 7\n  asciidoc: WARNING: remembering-renames.adoc: line 33: list item index: expected 9 got 8\n  asciidoc: WARNING: remembering-renames.adoc: line 38: section title out of sequence: expected level 1, got level 2\n  asciidoc: WARNING: sparse-checkout.adoc: line 17: section title out of sequence: expected level 1, got level 2\n  asciidoc: WARNING: sparse-checkout.adoc: line 928: list item index: expected 1 got 0\n  asciidoc: WARNING: sparse-checkout.adoc: line 931: list item index: expected 2 got 1\n  asciidoc: WARNING: sparse-checkout.adoc: line 951: list item index: expected 3 got 2\n  asciidoc: WARNING: sparse-checkout.adoc: line 974: list item index: expected 4 got 3\n  asciidoc: WARNING: sparse-checkout.adoc: line 980: list item index: expected 5 got 4\n  asciidoc: WARNING: sparse-checkout.adoc: line 1033: list item index: expected 6 got 5\n  asciidoc: WARNING: sparse-checkout.adoc: line 1049: list item index: expected 7 got 6\n  $ \n\nI also tried asciidoctor, just for fun:\n\n  $ asciidoctor --version\n  Asciidoctor 2.0.20 [https://asciidoctor.org]\n  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)\n  $ \n\n  $ make USE_ASCIIDOCTOR=1 html >out-doctor 2>&1\n\n  $ grep WARNING out-doctor\n  asciidoctor: WARNING: remembering-renames.adoc: line 13: list item index: expected 1, got 0\n  asciidoctor: WARNING: remembering-renames.adoc: line 15: list item index: expected 2, got 1\n  asciidoctor: WARNING: remembering-renames.adoc: line 17: list item index: expected 3, got 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 20: list item index: expected 4, got 3\n  asciidoctor: WARNING: remembering-renames.adoc: line 23: list item index: expected 5, got 4\n  asciidoctor: WARNING: remembering-renames.adoc: line 25: list item index: expected 6, got 5\n  asciidoctor: WARNING: remembering-renames.adoc: line 29: list item index: expected 7, got 6\n  asciidoctor: WARNING: remembering-renames.adoc: line 31: list item index: expected 8, got 7\n  asciidoctor: WARNING: remembering-renames.adoc: line 33: list item index: expected 9, got 8\n  asciidoctor: WARNING: remembering-renames.adoc: line 38: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 94: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 141: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 142: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 184: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 185: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 257: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 288: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 289: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 290: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 397: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 424: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 485: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 486: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: remembering-renames.adoc: line 487: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 17: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 95: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 258: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 303: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 316: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 545: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 612: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 752: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 824: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 895: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 923: section title out of sequence: expected level 1, got level 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 928: list item index: expected 1, got 0\n  asciidoctor: WARNING: sparse-checkout.adoc: line 931: list item index: expected 2, got 1\n  asciidoctor: WARNING: sparse-checkout.adoc: line 951: list item index: expected 3, got 2\n  asciidoctor: WARNING: sparse-checkout.adoc: line 974: list item index: expected 4, got 3\n  asciidoctor: WARNING: sparse-checkout.adoc: line 980: list item index: expected 5, got 4\n  asciidoctor: WARNING: sparse-checkout.adoc: line 1033: list item index: expected 6, got 5\n  asciidoctor: WARNING: sparse-checkout.adoc: line 1049: list item index: expected 7, got 6\n  asciidoctor: WARNING: sparse-checkout.adoc: line 1053: section title out of sequence: expected level 1, got level 2\n  $ \n\nYou can see that asciidoc only complains about the first 'section title out of\nsequence', whereas asciidoctor complains about them all.\n\n[asciidoctor also reports:\nNote: namesp. cut : stripped namespace before processing           Git User Manual]\n\nPatch #2 was a nightmare which I really gave up on! :) An early attempt\ninvolved renumbering the 'outline list' at the top from 0->8 to 1->9\n(I thought there was a way to start numbering at zero, but I lost a lot\nof time trying to do so, without any success). So, of course I 'just'\ntried global search/replace in vim to do the renumbering (backwards).\nThis was a complete disaster (of course), which I 'fixed' many many times.\n(Not everything which is numbered is a section, there are 'cases' as well).\n\nIn the end, I just disabled the 'outline' list, by removing the period\non the numbers (again '0\\. Assumptions' should have worked, but didn't)\nand fixing up the section titles without renumbering them. Note that\nasciidoctor mis-formats the 'ascii branch diagrams', which asciidoc\nformats correctly. I think there are other formatting problems left.\n\nIn patch #3, the formatting changes are confined to the section titles and\nrenumbering the 'known bugs' from 0->6 to 1->7. (I think I noticed some\nsub-sub lists which are not formatted correctly, but I don't seem to be\nable to see them now ...).\n\nIn patch #4, most of the formatting changes relate to section titles, but\nI could not fix some inline text formatting starting at 'File Layouts'\n(within 'Commit-Graph Chains') with text that is monospaced with `` but\nalso contains an '{' character. For example:\n\n  `$OBJDIR/info/commit-graphs/graph-{hash}.graph`\n\nis monospaced (blue colour with asciidoc) up until the {hash}.graph which\ndoes not have any formatting. (It is not so noticeable with asciidoctor\nbecause the formatting consists of a *very* subtle gray background to the\ntext which, to my eyes anyway, is almost not visible).\n\nI have tried several suggestions from an on-line asciidoc syntax cheatsheet\nsuch as:\n\n  `$OBJDIR/info/commit-graphs/graph-\\{hash\\}.graph`\n  `+$OBJDIR/info/commit-graphs/graph-{hash}.graph+`\n\nbut nothing worked. Note that there are many similar instances of this\nproblem (including just `{hash}`).\n\nNote also that asciidoctor did not render the second diagram correctly\n(the one in 'Merging commit-graph files'), but asciidoc was just fine.\n\nThe remaining documents:\n\n    directory-rename-detection.adoc\n    packfile-uri.adoc\n    repository-version.adoc\n    rerere.adoc\n    sparse-index.adoc\n\nall appear to be formatted correctly.\n\nSo, I really need help with the asciidoc formatting, in patches #2->#4,\nwhich I am marking as RFC. Having said that, these patches represent\nan improvement over the existing documents in terms of formatting\n(just not by much!).\n\nAny help fixing up these patches would be much appreciated. :)\n\nThanks.\n\nATB,\nRamsay Jones\n\n \nRamsay Jones (4):\n  doc: add some missing technical documents\n  doc: remembering-renames.adoc: fix asciidoc warnings\n  doc: sparse-checkout.adoc: fix asciidoc warnings\n  doc: commit-graph.adoc: fix up some formatting\n\n Documentation/Makefile                        |  8 +++\n Documentation/technical/commit-graph.adoc     | 34 +++++-----\n .../technical/remembering-renames.adoc        | 63 +++++++++----------\n Documentation/technical/sparse-checkout.adoc  | 38 +++++------\n 4 files changed, 74 insertions(+), 69 deletions(-)\n\n-- \n2.51.0\n"}]}