From: Mark Lodato <lodatom@gmail.com>
Date: Tue, 16 Mar 2010 01:12:08 GMT
Subject: Re: [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>
Message-ID: <ca433831003151812l7cc2c1b4hc11c9748ec8ed570@mail.gmail.com>
In-Reply-To: <7vwrxf6fnc.fsf@alter.siamese.dyndns.org>

On Sat, Mar 13, 2010 at 6:05 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Mark Lodato <lodatom@gmail.com> writes:
>
>> There exist no commands that accept a <commit> but not a <commit-ish>,
>
> I have one worry about this and [07/12].  The droppage of -ish would make
> sense from the point of view of describing command line arguments,
> i.e. what you can give to the commands, but it would make it impossible
> for us to talk about places that _only_ tree not arbitrary tree-ish can
> appear.  For example, don't we ever talk about something like this?
>
>    A tree object is a sequence of records, each of which describes the
>    type of entry, object name, and the name of the entry in the tree.
>    When the type is "tree", the object name must name a tree, when the
>    type is "gitlink", the object name must name a commit, ...
>
> Other than that small worry, I think the series goes in the right
> direction.

Yes, it would probably be best to leave the -ish terms in the glossary
(which I evidently did by mistake) and in the comments and
documentation, but just not use them as an identifier in angle
brackets.  For example, a command accepting a <tree> would also accept
commits or tags unless otherwise noted, but the term "tree object"
would still only refer to an actual tree object, not a tree-ish.  When
it is unclear, one can use the -ish term, like I just did in that last
sentence.

I'll wait a few days to see if there are any more comments, and then
I'll try fixing up this series.