Re: [PATCH] doc: technical details about the index file format

Nguyen Thai Ngoc Duy [off-list ref] writes:

Looks good. I don't really like ending a sentence with semicolon, but
that's just my taste.

I tend to do enumerated list like "A; B; and C."  Perhaps just a personal
taste.

I wonder if we should also point to relevant source files, so if this
document becomes out of date, the readers can jump in the source and
verify themselves (perhaps coming up with patches to this doc)?

I suspect that is a sure way to guarantee the document to go stale.

I didn't like the way I explained the cache-tree entry order.  Was it
understandable?

I am wondering if an illustration with an example might be in order.  I
think anybody halfway intelligent may be able to get a fuzzy idea of what
is going on by looking at the output from test-dump-cache-tree after
"reset --hard && write-tree" and then by comparing it with the output from
test-dump-cache-tree after running ">t/something && git add t/something"
(which invalidates the top-level tree and t/ subtree). But a well written
documentation should be able to help clarifying the idea obtainable that
way.  I don't think what I wrote in the previous message is sufficient
even for that (i.e. comparing the two output would give you better
explanation of what is going on than what I wrote--iow, what I wrote may
not be very useful for people who are motivated to learn).