Re: [PATCH] docs: improve the example that illustrates git-notes path names

[Taylor Blau <me@ttaylorr.com>]

On Mon, Aug 03, 2020 at 10:04:15AM -0700, Junio C Hamano wrote:
> Taylor Blau <me@ttaylorr.com> writes:
>
> >> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> >> index ced2e8280e..9fc1979531 100644
> >> --- a/Documentation/git-notes.txt
> >> +++ b/Documentation/git-notes.txt
> >> @@ -223,7 +223,7 @@ are taken from notes refs.  A notes ref is usually a branch which
> >>  contains "files" whose paths are the object names for the objects
> >>  they describe, with some directory separators included for performance
> >>  reasons footnote:[Permitted pathnames have the form
> >> -'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
> >> +'12'`/`'34'`/`'56'`/`'...'`/`'789abc...': a sequence of directory
> >
> > I had to read this twice to figure out why the first 'ab' changed to
> > '12'. It appears that this is to avoid having to use 'gh...' in the
> > last directory, since 'g', 'h' and so on aren't hexadecimal digits.
>
> You can wrap-around to '0' after counting up to 'f', no ;-)?

;-).

> Having '/.../' between '56' and '789' to indicate "there are more
> levels possible here" is somewhat misleading with the new example.
> We could argue that the original objectname does not have to be
> "123456789abc.." but then the whole exercise becomes somewhat
> pointless as the objectname could have been 'abcdef...abcdef...'.
>
> Another minor nit: it probably makes it read more natural to start
> counting from '0' when writing hexadecimal, if we really want to
> use sequence of ascending hexdigits.
>
> Using a seemingly random example 85/b4/.../808d9ee6debdf167ced3
> might be less confusing, because ...
>
> >>  names of two hexadecimal digits each followed by a filename with the
> >>  rest of the object ID.].
>
> ... I think these two lines is pleanty clear than any example, so I
> am OK with either the old or the updated example, but I think a
> seemingly random example as long as the leaf level does not share
> the leading hexdigits as the pathname would work the best.

I agree with your reasoning (it didn't occur to me as a problem before,
but seeing it spelled out in front of me I could understand how such an
example might be confusing).

Thanks,
Taylor