Re: Git in a Nutshell guide

Junio C Hamano [off-list ref] writes:

I think the ref naming syntax is so commonly used and
fundamental that we could treat it as prerequiste for individual
manual pages.  Maybe move the section to git(7)?  That would
certainly be better than having it in git-rev-parse(1), but does
not reduce the cross referencing complaints.

Well, obviously, something which isn't addressed by my patch is the
fact that some of the documentation an average user needs is in the
plumbing man pages.

(Gosh, I was going to cite the manpage for git-log and git-rev-parse
as an example, but it has already been fixed :-). Good job !)

git-rev-parse(1) is full of terribly usefull information, and that
information is definitely not in the place an average user would look
at.

I have no ideal solution for that. git(7) is already really long.
Perhaps some "topic man pages" would be good. By "topic man page", I
mean "man git-something" where "something" isn't a git command, but a
crosscutting concept. For example, here, "man git-refspec" to document
reference specifiers like HEAD@{42}, master~55, d71c6c8e24a and
friends. "man git-i18n" would be another candidate.

Anyway, my patch is definitely a step forward, even if it's just the
first, small one ;-).

-- 
Matthieu