Re: [PATCH] Documentation/fast-import: put explanation of M 040000 <dataref> "" in context

Jonathan Nieder [off-list ref] writes:

For whom is this paragraph written?  People who produce g-f-i streams, or
people who interpret somebody else's g-f-i streams?

I am wondering if it is easier to read if we consistently target the
former, something like this:

        The root of the tree can be represented by `<mode> 040000` with an
        empty string as `<path>`.

because all the surrounding description seems to describe rules
(e.g. "quoting should be used", "The value of `<path>` must be ...").

Junio C Hamano wrote:

Jonathan Nieder [off-list ref] writes:

quoted

+++ b/Documentation/git-fast-import.txt

@@ -542,7 +542,7 @@ The value of `<path>` must be in canonical form. That is it must not:
 * contain the special component `.` or `..` (e.g. `foo/./bar` and
   `foo/../bar` are invalid).
 
-In `040000` mode, `<path>` can be the empty string (`""`)
+If `<mode>` is `040000`, `<path>` can be the empty string (`""`)
 to specify the root of the tree.

For whom is this paragraph written?  People who produce g-f-i streams, or
people who interpret somebody else's g-f-i streams?

I am wondering if it is easier to read if we consistently target the
former, something like this:

        The root of the tree can be represented by `<mode> 040000` with an
        empty string as `<path>`.

Sounds good to me.  I suppose the clause "by <mode> 040000" should just
be left out --- we already explained that directories must have mode
S_IFDIR a few lines earlier.