Re: [PATCH v3] doc: add a explanation of Git's data model

[Junio C Hamano <gitster@pobox.com>]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

>     xmlto: <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml does not validate (status 3)
>     xmlto: Fix document syntax or use --skip-validation option
>     <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:71: element link: validity error : IDREF attribute linkend references an unknown ID "tree"
>     <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:96: element link: validity error : IDREF attribute linkend references an unknown ID "tree"
>     <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml:397: element link: validity error : IDREF attribute linkend references an unknown ID "tree"
>     Document <git repo>/Documentation/tmp-doc-diff/worktree/Documentation/gitdatamodel.xml does not validate
>     make[1]: *** [Makefile:380: gitdatamodel.7] Error 13
>     make[1]: *** Waiting for unfinished jobs....
>     make[1]: Leaving directory '<git repo>/Documentation/tmp-doc-diff/worktree/Documentation'
>     make: *** [Makefile:3676: install-man] Error 2
>     make: Leaving directory '<git repo>/Documentation/tmp-doc-diff/worktree'
>
> The syntax looks correct.  So I don’t know what is wrong.  `make html`
> works *and* makes the link.
>
> At first look it might be to do with the anchor on a definition list but
> I tried removing the anchors and expected to get an error for `blob`
> next.  But that didn’t happen.
>
> In short I don’t see what is special about `tree`.

This seems to work it around without breaking .html generation too
badly for AsciiDoc and without breaking .7/.html generation for
Asciidoctor.  Generation of .7 were broken with AsciiDoc so we
cannot complain even if the result is suboptimal, but the generated
manpage with this patch using AsciiDoc did not look too bad, either.

I do not know AsciiDoc internals (and I am not particularly
interested to learn it now), but I am guessing that the bug is that
when it sees [[tree]], it tries to find an element to put id="tree",
but before it finds any approprifate one, it sees [[filemode]] and
uses the element it finds to hold id="filemode", losing sight of the
need to add id="tree" somewhere.



 Documentation/gitdatamodel.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index f49574dfae..7232fe3861 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -83,8 +83,10 @@ trees::
     A tree is how Git represents a directory. It lists, for each item in
     the tree:
 +
+1. The *file mode*, for example `100644`.
++
 [[file-mode]]
-1. The *file mode*, for example `100644`. The format is inspired by Unix
+The format is inspired by Unix
    permissions, but Git's modes are much more limited. Git only supports these file modes:
 +
   - `100644`: regular file (with type `blob`)
-- 
2.51.1-556-g06b2a500e9