Re: [RFC/PATCH 2/3] Documentation: gitrevisions

[Stephen Boyd <bebarino@gmail.com>]

  On 07/14/2010 01:42 AM, Michael J Gruber wrote:
>
> I added this text on purpose. The "DESCRIPTION" section is meant to give
> a concise description of the overall picture so that, e.g., you
> understand which section will answer which question without having to
> read all of them. In this case it gives you a short overview of what can
> be referred to by revisions (commit, commit range, general object)
> before the sections go into the details of how to specify them.
>
> Also, as I mentioned in the cover letter, I suggest a rework of the
> actual (included, old) content if that structure is to stay. So, in a
> second step, one could avoid duplications.

Ok, I must have missed that in the cover letter. I hope in the next version we can rework the old content and integrate it into the two paragraphs in this patch. I don't see how keeping the DESCRIPTION section this verbose is helpful. At most it should say:

Many Git commands take revisions as parameters. A revision typically specifies a commit, but it can also specify a blob, a tree, or a set of commits. A set of commits is commonly referred to as a revision range. (or just range?)

And then I wonder if that should just go in the SYNOPSIS section and the DESCRIPTION should be deleted.