[PATCH 00/10] Docs: git tag

[PATCH 00/10] Docs: git tag

[Michael Witten]

Small patches fixing up the `git tag' docs.

Michael Witten (10):
  Docs: git tag: Add `the'
  Docs: git tag: peoples back -> people's backs
  Docs: git tag: Revise a paragraph.
  Docs: git tag: other's -> the other person's
  Docs: git tag: Streamline a sentence.
  Docs: git tag: Add missing 'the'
  Docs: git tag: Use 'who' again
  Docs: git tag: Remove superfluous 'with'
  Docs: git tag: Use semicolon
  Docs: git tag: Rewrite discussion of GIT_COMMITTER_DATE

 Documentation/git-tag.txt |   39 ++++++++++++++++++++-------------------
 1 files changed, 20 insertions(+), 19 deletions(-)

-- 
1.7.4.18.g68fe8

[PATCH 01/10] Docs: git tag: Add `the'

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 61263fa..7844ff1 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -165,7 +165,7 @@ You can test which tag you have by doing
 
 which should return 0123456789abcdef.. if you have the new version.
 
-Sorry for inconvenience.
+Sorry for the inconvenience.
 ------------
 
 Does this seem a bit complicated?  It *should* be. There is no
-- 
1.7.4.18.g68fe8

[PATCH 02/10] Docs: git tag: peoples back -> people's backs

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 7844ff1..e276393 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -169,7 +169,7 @@ Sorry for the inconvenience.
 ------------
 
 Does this seem a bit complicated?  It *should* be. There is no
-way that it would be correct to just "fix" it behind peoples
+way that it would be correct to just "fix" it behind people's
 backs. People need to know that their tags might have been
 changed.
 
-- 
1.7.4.18.g68fe8

Re: [PATCH 02/10] Docs: git tag: peoples back -> people's backs

[Eric Raible]

On 11:59 AM, Michael Witten wrote:
> Signed-off-by: Michael Witten <mfwitten@gmail.com>
> ---
>  Documentation/git-tag.txt |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index 7844ff1..e276393 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -169,7 +169,7 @@ Sorry for the inconvenience.
>  ------------
>  
>  Does this seem a bit complicated?  It *should* be. There is no
> -way that it would be correct to just "fix" it behind peoples
> +way that it would be correct to just "fix" it behind people's
>  backs. People need to know that their tags might have been
>  changed.

s/people's/peoples'/

Or probably even better:

/behind people's backs/automatically/

Re: [PATCH 02/10] Docs: git tag: peoples back -> people's backs

[Michael Witten]

On Mon, Mar 28, 2011 at 13:02, Eric Raible <raible@nextest.com> wrote:
> On 11:59 AM, Michael Witten wrote:
>> Signed-off-by: Michael Witten <mfwitten@gmail.com>
>> ---
>>  Documentation/git-tag.txt |    2 +-
>>  1 files changed, 1 insertions(+), 1 deletions(-)
>>
>> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
>> index 7844ff1..e276393 100644
>> --- a/Documentation/git-tag.txt
>> +++ b/Documentation/git-tag.txt
>> @@ -169,7 +169,7 @@ Sorry for the inconvenience.
>>  ------------
>>
>>  Does this seem a bit complicated?  It *should* be. There is no
>> -way that it would be correct to just "fix" it behind peoples
>> +way that it would be correct to just "fix" it behind people's
>>  backs. People need to know that their tags might have been
>>  changed.
>
> s/people's/peoples'/

Actually, "people" is already plural, and thus "people's" is the
correct possessive form (as with "women" and "women's"); "peoples", on
the other hand, means diffent groups of people. For instance:

  There are many people in China.

  Each of the various peoples in China has
  its own language; Hokkien is the language
  of my particular people.

At least that's how I know the usage.

How about changing it to "behind a person's back"? Perhaps the whole
informal tone is what needs to be changed.

> Or probably even better:
>
> /behind people's backs/automatically/

I don't feel that the word "automatically" sufficiently conveys the
unexpected nature of such an event.

[PATCH 03/10] Docs: git tag: Revise a paragraph.

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index e276393..68eebee 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -189,9 +189,10 @@ the toplevel but not limited to them.  Mere mortals when pulling
 from each other do not necessarily want to automatically get
 private anchor point tags from the other person.
 
-You would notice "please pull" messages on the mailing list says
-repo URL and branch name alone.  This is designed to be easily
-cut&pasted to a 'git fetch' command line:
+Often, "please pull" messages on the mailing list just provide
+two pieces of information: a repo URL and a branch name; this
+is designed to be easily cut&pasted at the end of a 'git fetch'
+command line:
 
 ------------
 Linus, please pull from
-- 
1.7.4.18.g68fe8

[PATCH 04/10] Docs: git tag: other's -> the other person's

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 68eebee..b348c3d 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -208,8 +208,8 @@ becomes:
 $ git pull git://git..../proj.git master
 ------------
 
-In such a case, you do not want to automatically follow other's
-tags.
+In such a case, you do not want to automatically follow the other
+person's tags.
 
 One important aspect of git is it is distributed, and being
 distributed largely means there is no inherent "upstream" or
-- 
1.7.4.18.g68fe8

[PATCH 05/10] Docs: git tag: Streamline a sentence.

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index b348c3d..9ec2715 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -211,8 +211,8 @@ $ git pull git://git..../proj.git master
 In such a case, you do not want to automatically follow the other
 person's tags.
 
-One important aspect of git is it is distributed, and being
-distributed largely means there is no inherent "upstream" or
+One important aspect of git is its distributed nature, which
+largely means there is no inherent "upstream" or
 "downstream" in the system.  On the face of it, the above
 example might seem to indicate that the tag namespace is owned
 by upper echelon of people and tags only flow downwards, but
-- 
1.7.4.18.g68fe8

[PATCH 06/10] Docs: git tag: Add missing 'the'

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 9ec2715..73f340b 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -215,7 +215,7 @@ One important aspect of git is its distributed nature, which
 largely means there is no inherent "upstream" or
 "downstream" in the system.  On the face of it, the above
 example might seem to indicate that the tag namespace is owned
-by upper echelon of people and tags only flow downwards, but
+by the upper echelon of people and that tags only flow downwards, but
 that is not the case.  It only shows that the usage pattern
 determines who are interested in whose tags.
 
-- 
1.7.4.18.g68fe8

[PATCH 07/10] Docs: git tag: Use 'who' again

[Michael Witten]

Also, remove an unnecessary parenthetical comment.

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 73f340b..695a224 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -225,9 +225,9 @@ primarily interested in the networking part of the kernel") who may
 have their own set of tags (e.g. "this is the third release
 candidate from the networking group to be proposed for general
 consumption with 2.6.21 release") to another circle of people
-(e.g. "people who integrate various subsystem improvements").
-The latter are usually not interested in the detailed tags used
-internally in the former group (that is what "internal" means).
+(e.g. "people who integrate various subsystem improvements") who
+are usually not interested in the detailed tags used
+internally in the former group.
 That is why it is desirable not to follow tags automatically in
 this case.
 
-- 
1.7.4.18.g68fe8

[PATCH 08/10] Docs: git tag: Remove superfluous 'with'

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 695a224..0b24c87 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -233,7 +233,7 @@ this case.
 
 It may well be that among networking people, they may want to
 exchange the tags internal to their group, but in that workflow
-they are most likely tracking with each other's progress by
+they are most likely tracking each other's progress by
 having remote-tracking branches.  Again, the heuristic to automatically
 follow such tags is a good thing.
 
-- 
1.7.4.18.g68fe8

[PATCH 09/10] Docs: git tag: Use semicolon

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 0b24c87..3dd78a0 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -243,7 +243,7 @@ On Backdating Tags
 
 If you have imported some changes from another VCS and would like
 to add tags for major releases of your work, it is useful to be able
-to specify the date to embed inside of the tag object.  The data in
+to specify the date to embed inside of the tag object; such data in
 the tag object affects, for example, the ordering of tags in the
 gitweb interface.
 
-- 
1.7.4.18.g68fe8

[PATCH 10/10] Docs: git tag: Rewrite discussion of GIT_COMMITTER_DATE

[Michael Witten]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-tag.txt |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 3dd78a0..21dc06f 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -248,16 +248,16 @@ the tag object affects, for example, the ordering of tags in the
 gitweb interface.
 
 To set the date used in future tag objects, set the environment
-variable GIT_COMMITTER_DATE to one or more of the date and time.  The
-date and time can be specified in a number of ways; the most common
-is "YYYY-MM-DD HH:MM".
+variable GIT_COMMITTER_DATE (see the later discussion of possible
+values; the most common form is "YYYY-MM-DD HH:MM").
 
-An example follows.
+For example:
 
 ------------
 $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
 ------------
 
+include::date-formats.txt[]
 
 SEE ALSO
 --------
-- 
1.7.4.18.g68fe8

Re: [PATCH 00/10] Docs: git tag

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

> Small patches fixing up the `git tag' docs.
>
> Michael Witten (10):
>   Docs: git tag: Add `the'
>   Docs: git tag: peoples back -> people's backs
>   Docs: git tag: Revise a paragraph.
>   Docs: git tag: other's -> the other person's
>   Docs: git tag: Streamline a sentence.
>   Docs: git tag: Add missing 'the'
>   Docs: git tag: Use 'who' again
>   Docs: git tag: Remove superfluous 'with'
>   Docs: git tag: Use semicolon
>   Docs: git tag: Rewrite discussion of GIT_COMMITTER_DATE

Thanks; all looked sensible changes, except for 7/10 which I somehow find
the original is more readable than the new text, partly because the
sentences are shorter but more importantly because the two sentences make
two separate assertions (the first is about what "one-shot" pull means,
the second is about why automatic tag following is not desired in that
situation).

Re: [PATCH 00/10] Docs: git tag

[Michael Witten]

On Mon, Mar 28, 2011 at 13:04, Junio C Hamano <gitster@pobox.com> wrote:
> Michael Witten <mfwitten@gmail.com> writes:
>
>> Small patches fixing up the `git tag' docs.
>>
>> Michael Witten (10):
>>   Docs: git tag: Add `the'
>>   Docs: git tag: peoples back -> people's backs
>>   Docs: git tag: Revise a paragraph.
>>   Docs: git tag: other's -> the other person's
>>   Docs: git tag: Streamline a sentence.
>>   Docs: git tag: Add missing 'the'
>>   Docs: git tag: Use 'who' again
>>   Docs: git tag: Remove superfluous 'with'
>>   Docs: git tag: Use semicolon
>>   Docs: git tag: Rewrite discussion of GIT_COMMITTER_DATE
>
> Thanks; all looked sensible changes, except for 7/10 which I somehow find
> the original is more readable than the new text, partly because the
> sentences are shorter but more importantly because the two sentences make
> two separate assertions (the first is about what "one-shot" pull means,
> the second is about why automatic tag following is not desired in that
> situation).

Fair enough.

Re: [PATCH 00/10] Docs: git tag

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 28.03.2011 20:04:
> Michael Witten <mfwitten@gmail.com> writes:
> 
>> Small patches fixing up the `git tag' docs.
>>
>> Michael Witten (10):
>>   Docs: git tag: Add `the'
>>   Docs: git tag: peoples back -> people's backs
>>   Docs: git tag: Revise a paragraph.
>>   Docs: git tag: other's -> the other person's
>>   Docs: git tag: Streamline a sentence.
>>   Docs: git tag: Add missing 'the'
>>   Docs: git tag: Use 'who' again
>>   Docs: git tag: Remove superfluous 'with'
>>   Docs: git tag: Use semicolon
>>   Docs: git tag: Rewrite discussion of GIT_COMMITTER_DATE
> 
> Thanks; all looked sensible changes, except for 7/10 which I somehow find
> the original is more readable than the new text, partly because the
> sentences are shorter but more importantly because the two sentences make
> two separate assertions (the first is about what "one-shot" pull means,
> the second is about why automatic tag following is not desired in that
> situation).

Looked mostly sensible to me (and I share Junio's view on 7), too,
although I probably would have changed "other's" simply to "others'".

And yes, while I like the dramatic sound of "behind peoples' backs",
you're absolutely right with "people's", of course:)

Those 10 patches could have been 1 actually, they are really divided
into atoms (which is not bad per se) even though they all fall under
"cosmetic language corrections and improvements" without any content
change nor restructuring.

Michael

Re: [PATCH 00/10] Docs: git tag

[Michael Witten]

On Tue, Mar 29, 2011 at 01:25, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Junio C Hamano venit, vidit, dixit 28.03.2011 20:04:
>> Michael Witten <mfwitten@gmail.com> writes:
>>
>>> Small patches fixing up the `git tag' docs.
>>>
>>> Michael Witten (10):
>>>   Docs: git tag: Add `the'
>>>   Docs: git tag: peoples back -> people's backs
>>>   Docs: git tag: Revise a paragraph.
>>>   Docs: git tag: other's -> the other person's
>>>   Docs: git tag: Streamline a sentence.
>>>   Docs: git tag: Add missing 'the'
>>>   Docs: git tag: Use 'who' again
>>>   Docs: git tag: Remove superfluous 'with'
>>>   Docs: git tag: Use semicolon
>>>   Docs: git tag: Rewrite discussion of GIT_COMMITTER_DATE
>>
>> Thanks; all looked sensible changes, except for 7/10 which I somehow find
>> the original is more readable than the new text, partly because the
>> sentences are shorter but more importantly because the two sentences make
>> two separate assertions (the first is about what "one-shot" pull means,
>> the second is about why automatic tag following is not desired in that
>> situation).
>
> Looked mostly sensible to me (and I share Junio's view on 7), too,
> although I probably would have changed "other's" simply to "others'".

I probably chose the singular variant for 2 reasons: I generally
prefer singular renditions, and the sentence is referring to an
example of a pull-request from one individual.

On Tue, Mar 29, 2011 at 01:25, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> Those 10 patches could have been 1 actually, they are really divided
> into atoms (which is not bad per se) even though they all fall under
> "cosmetic language corrections and improvements" without any content
> change nor restructuring.

It's always hard to tell what delineations will be appreciated.
However, it's almost always the case that the smaller a patch is, the
more quickly it can be reviewed and approved (also, the smaller the
diff, the more meaningful the commit message), so I err on the side of
too small; after all, it's generally much easier to squash than to
split.

Of course, I would have no problem if Junio ultimately saw fit to
squash some or all of them (with a note that such squashing has
occurred).

Thanks for your input.