Re: Git in a Nutshell guide

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 19, 2007, 22:29 UTC
Message-ID: <7v7ikdna24.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <0E0AA90A-2282-4AFE-8B94-EA0E35B57D65@lrde.epita.fr>

Benoit Sigoure <tsuna@lrde.epita.fr> writes:

Show 15 quoted lines

> On Nov 19, 2007, at 10:33 PM, Matthieu Moy wrote:
>
>> Benoit Sigoure <tsuna@lrde.epita.fr> writes:
>>
>>> No please stop adding links from on man page to another.  If you read
>>> man git-reflog, you surely want to learn the HEAD@{N} syntax and see
>>> practical uses cases.
>>
>> I don't understand your point.
>>
>> Yes, if I read man git-reflog, I do surely want to learn HEAD@{N}
>> syntax, but that is _precisely_ what my patch does.
>
> By telling you to read another man page which is annoying and a
> recurring complaint.

Which is a valid point. We could move that part into a separate source file and include it from different places appropriately, just we have done for the common diff options.

However, you need to think about what's appropriate. Any command that potentially takes a ref as (one of) its parameter? That means almost everybody.

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.