[PATCH v4 0/3] Make 'git help everyday' work

[Philip Oakley <philipoakley@iee.org>]

This is hopefully the final revision of the patch...
and integrates Junio's comments. 

I've eye-balled the man page and web page results, and corrected a few quote / back tick
items to be more consistent.

Re: [PATCH v3 1/3] doc: modernise everyday.txt wording and format in man page style
From: "Junio C Hamano" <gitster@pobox.com>
Sent: Tuesday, September 30, 2014 12:24 AM
Subject: Re: [PATCH v3 1/3] doc: modernise everyday.txt wording and format in man page style
> Philip Oakley <philipoakley@iee.org> writes:
> 
>> @@ -45,7 +58,7 @@ following commands.
>>  
>>    * linkgit:git-rebase[1] to maintain topic branches.
>>  
>> -  * linkgit:git-tag[1] to mark known point.
>> +  * linkgit:git-tag[1] to mark a known point.
> 
> I really appreciate your attention to details here.
> 
>> +<10> review commit logs; other forms to limit output can be
>>  combined and include `--max-count=10` (show 10 commits),
>>  `--until=2005-12-10`, etc.
> 
> s/--max-count=//; perhaps?
I've shown both in the update, as it's a help guide. How does it look?

> 
>> @@ -131,27 +145,34 @@ Clone the upstream and work on it.  Feed changes to upstream.::
>>  ------------
>>  $ git clone git://git.kernel.org/pub/scm/.../torvalds/linux-2.6 my2.6
>>  $ cd my2.6
>> +$ git checkout -b mine master <1>
>> +$ edit/compile/test; git commit -a -s <2>
>> +$ git format-patch master <3>
>> +$ git send-email --to="person <email@example.com>" 00*.patch <4>
>> +$ git pull <5>
> 
> This may be found somewhat questionable by some people, as "mine"
> does not build on the master at origin.  Insert "git checkout master"
> before this step to cause <5> update the pristine copy of their
> master, perhaps?  That way, the next step
I'd misunderstood this initially (confusion as to build start point).
I've added the checkout with a comment, and renumber those following.

> 
>> +$ git log -p ORIG_HEAD.. arch/i386 include/asm-i386 <6>
> 
> starts making more sense.
> 
>> +$ git fetch --tags <11>
>> ...
>> +<11> from time to time, obtain official tags from the `origin`
>>  and store them under `.git/refs/tags/`.
> 
> I am not sure if "fetch --tags" still needs to be taught, especially
> in a "quick guide" document, because "fetch" has auto-followed
> relevant tags for a long time since the original version of this
> document was written.
Done - removed.

> 
>> +<3> arrange `git push` to push all local branches to
>> +their corresponding branch of the mothership machine.
>> +<4> push will stash all our work away on `remotes/satellite/*`
>> +remote-tracking branches on the mothership machine.  You could use this
>>  as a back-up method.
> 
> The original mentions "a back-up method", but a larger benefit of
> this kind of settings is that it lets you pretend that mothership
> "fetched" from you.
> 
> We may want to say "You can use this to pretend as if the origin,
> aka mothership, ran 'git fetch' from you, aka satellite".  This is
> especially true because the next step <5> is about how to integrate
> your work done on 'satellite' into 'mothership' that cannot fetch
> from 'satellite' (imagine satellite is behind a NAT and it can only
> ssh out to mothership but not the other way around).
Text updated to include those points.

> 
>> -Integrator[[Integrator]]
>> +Integrator[[INTEGRATOR]]
>>  ------------------------
>>  
>>  A fairly central person acting as the integrator in a group
>> @@ -213,6 +235,9 @@ project receives changes made by others, reviews and integrates
>>  them and publishes the result for others to use, using these
>>  commands in addition to the ones needed by participants.
>>  
>> +This section can also be applied to a git-request-pull workflow,
>> +or the GitHub (www.github.com) pull-request flow.
> 
> Clarify which end of that workflow this can be applied, perhaps?
> E.g. "... also be used by the person who responds to 'git
> request-pull' or pull-request on GitHub to integrate others' work
> into your history".
Sorted, as below.

> 
> 
>> @@ -225,23 +250,26 @@ commands in addition to the ones needed by participants.
>>  
>>    * linkgit:git-push[1] to publish the bleeding edge.
>>  
>> +  * linkgit:git-request-pull[1] to create a summary of changes
>> +    for your upstream to pull.
>> +
> 
> This new item looks somewhat out of place, doesn't it?  It is
> because this is a participant item, not an integrator item.
The bullet item moved to Participant, and the text there updated.
> 
> Yes, I know a sub-area lieutenant would request a pull by the
> top-level maintainer, but when you interact with your 'upstream',
> you are not acting as an integrator.
> 
> If you really want to add request-pull to common 20-or-so commands,
> it would make more sense to do so in the participant's section and
> to explain that an sub-area lieutenant acts both as a participant
> and as an integrator.
Added text in line with your comment.

> 
> Thanks.

--

Philip Oakley (3):
  doc: modernise everyday.txt wording and format in man page style
  doc: Makefile regularise OBSOLETE_HTML list building
  Make 'git help everyday' work

 Documentation/Makefile             |   6 +-
 Documentation/everyday.txt         | 413 ---------------------------------
 Documentation/everyday.txto        |   9 +
 Documentation/git-push.txt         |   2 +-
 Documentation/git.txt              |   4 +-
 Documentation/gitcore-tutorial.txt |   2 +-
 Documentation/gitcvs-migration.txt |   2 +-
 Documentation/giteveryday.txt      | 455 +++++++++++++++++++++++++++++++++++++
 Documentation/gitglossary.txt      |   2 +-
 Documentation/gittutorial-2.txt    |   4 +-
 Documentation/gittutorial.txt      |   4 +-
 README                             |   2 +-
 builtin/help.c                     |   1 +
 13 files changed, 480 insertions(+), 426 deletions(-)
 delete mode 100644 Documentation/everyday.txt
 create mode 100644 Documentation/everyday.txto
 create mode 100644 Documentation/giteveryday.txt

-- 
1.9.4.msysgit.0