Stephen Boyd venit, vidit, dixit 14.07.2010 08:16:
> On 07/05/2010 09:11 AM, Michael J Gruber wrote:
>> +
>> +DESCRIPTION
>> +-----------
>> +
>> +Many Git commands take revision parameters as arguments. Depending on
>> +the command, they denote a specific commit or, for commands which
>> +walk the revision graph (such as linkgit:git-log[1]), all commits which can
>> +be reached from that commit. In the latter case one can also specify a
>> +range of revisions explicitly.
>> +
>> +In addition, some Git commands (such as linkgit:git-show[1]) also take
>> +revision parameters which denote other objects than commits, e.g. blobs
>> +("files") or trees ("directories of files").
>> +
>
> Is any of this text (section?) necessary besides including revisions.txt? It seems that revisions.txt nicely covers the types of revisions in the first paragraph of each section and these two paragraphs repeat that.
>
> Can you squash this in?
>
> --->8----
>
> index fc4789f..0e25c5f 100644
> --- a/Documentation/gitrevisions.txt
> +++ b/Documentation/gitrevisions.txt
> @@ -10,19 +10,6 @@ SYNOPSIS
> gitrevisions
>
>
> -DESCRIPTION
> ------------
> -
> -Many Git commands take revision parameters as arguments. Depending on
> -the command, they denote a specific commit or, for commands which
> -walk the revision graph (such as linkgit:git-log[1]), all commits which can
> -be reached from that commit. In the latter case one can also specify a
> -range of revisions explicitly.
> -
> -In addition, some Git commands (such as linkgit:git-show[1]) also take
> -revision parameters which denote other objects than commits, e.g. blobs
> -("files") or trees ("directories of files").
> -
> include::revisions.txt[]
>
>
>
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.
But here, I find it really natural (if not necessary) that the first
paragraph in each detailed section picks up on the pertaining parts of
the concise description.
Michael
--
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