From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 25 Aug 2009 20:37:14 GMT
Subject: Re: [PATCH] git-tag(1): Refer to git-check-ref-format(1) for <name>
Message-ID: <7vd46jocjp.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20090825172100.6117@nanako3.lavabit.com>

Nanako Shiraishi <nanako3@lavabit.com> writes:

> Quoting myself...
>
>> Subject: Documentation: consistently refer to check-ref-format
>>
>> Change the <name> placeholder to <tagname> in the SYNOPSIS section of
>> git-tag documentation, and describe it in the OPTIONS section in a way
>> similar to how documentation for git-branch does.
>>
>> Add SEE ALSO section to list the other documentation pages these two pages
>> refer to.
>>
>> Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com>
>
> Should I further polish this patch?

No, it just fell through the cracks of my mailbox.  I tend to agree that
it is better to mention only the presense of rules, and refer to the rules
described in the definitive document.

Safe names are designed to be what most sane people would naturally choose
to use anyway and they would not need to see the clutter that describes
only the half of the rules there.  And more importantly, the people who do
get errors by choosing illegal names by accident would _want_ to see the
full set of rules before choosing another name to avoid getting the same
error again.

Spelling only the half of the rules in the tag/branch manual page would
not help neither audience.