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

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Jul 14, 2010, 08:42 UTC
Message-ID: <4C3D785D.1050000@drmicha.warpmail.net>
In-Reply-To: <4C3D562B.3070404@gmail.com>

Stephen Boyd venit, vidit, dixit 14.07.2010 08:16:

Show 46 quoted lines

>   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