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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html