Rewrite the description section to describe what exactly remote
helpers are and the need for them. Also mention the curl family of
remote helpers as an example.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/git-remote-helpers.txt |   32 ++++++++++++++++++++++++++------
 1 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt
index 1b5f61a..15214ae 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -3,7 +3,7 @@ git-remote-helpers(1)
 
 NAME
 ----
-git-remote-helpers - Helper programs for interoperation with remote git
+git-remote-helpers - Helper programs to interact with remote repositories
 
 SYNOPSIS
 --------
@@ -12,11 +12,31 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-These programs are normally not used directly by end users, but are
-invoked by various git programs that interact with remote repositories
-when the repository they would operate on will be accessed using
-transport code not linked into the main git binary. Various particular
-helper programs will behave as documented here.
+Remote helper programs are normally not used directly by end users,
+but are invoked by git when it needs to interact with remote
+repositories. They implement a subset of the capabilities documented
+here, and conform to the "remote helper protocol". When git needs
+needs to interact with a repository served by a remote helper, it
+spawns the helper as an independent process and interacts with it over
+the specified protocol. git sends commands to the helper
+over standard input, and receives the result written to standard
+output by the helper over a pipe. Because a remote helper runs as
+an independent process to interact with remote repositories, there
+is no need to re-link git when adding a new helper nor need to link
+the helper with the implementation of git.
+
+All the capabilities of remote helpers have to do ...
[ message continues ]

I’m not a remote helper expert, but I’ll review it to get the ball
rolling.  I assume you’ve already gone through this a lot.  Most of
what’s left is nitpicks.


nitpick: comma usage.  Probably the simplest fix would to add a
subject after ", but".

  Remote helper programs are normally not used directly by end-users,
  but they are invoked by git when it needs to interact with remote

Pedantic usage nitpick: I think by “interacts with it over the
specified protocol” here, you mean “interacts with it according to the
aforementioned protocol”.  It would probably be simpler to skip
mention of the protocol altogether, like this:

  A given helper will implement a subset of the commands documented
  here.  When git needs to interact with a repository using a remote
  helper, it spawns the helper as an independent process, sends
  commands to the helper’s standard input, and expects results from
  the helper’s standard output.  Because a remote helper runs as an
  independent process from git, there is no need to re-link git to add
  a new helper, nor any need to link the helper with the
  implementation of git.


Odd phrasing: this does not actually explain what capabilities are.

  Every helper must support the "capabilities" command, which git will
  use to determine what other commands the helper will accept [*].  Other
  commands generally concern facilities like discovering and updating
  remote refs, transporting objects between the object database and
  the remote repository, and updating the local object store.

[*] and to read in refspecs for remote-tracking branches.  This seems
silly (and would not scale well too many refspecs) --- why doesn’t git

Does “they” refer to the helpers or their capabilities?  Best to avoid
the question:

  Helpers supporting the 'fetch' capability can discover refs from the
  remote repository and transfer objects reachable from those refs to
  the local object store.

The original phrasing separated transfer from inclusion in the ...
[ message continues ]

Hi Jonathan,

Since patch has already been reviewed many times, and signed off by
Junio before going into pu, I've tried to minimize changes and prepare
a fixup patch while addressing all your concerns. Do tell me if it's
alright.

diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt
index 6ffc0da..52332ed 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -12,26 +12,27 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Remote helper programs are normally not used directly by end users,
+Remote helper programs are normally not used directly by end users
 but are invoked by git when it needs to interact with remote
 repositories. They implement a subset of the capabilities documented
-here, and conform to the "remote helper protocol". When git needs
+here and conform to the "remote helper protocol". When git needs
 needs to interact with a repository served by a remote helper, it
-spawns the helper as an independent process and interacts with it over
-the specified protocol. git sends commands to the helper
-over standard input, and receives the result written to standard
+spawns the helper as an independent process, sends it commands
+over standard input, and receives the results written to standard
 output by the helper over a pipe. Because a remote helper runs as
 an independent process to interact with remote repositories, there
 is no need to re-link git when adding a new helper nor need to link
 the helper with the implementation of git.
 
-All the capabilities of remote helpers have to do with discovering and
+Every helper must support the "capabilities" command, which lists a
+set of commands corresponding to the capabilities of the helper.
+The capabilities have to do with discovering and
 updating remote refs, transporting objects between local and remote,
-and updating the local object store. Using the 'fetch' capability,
-they can discover refs on the remote, transfer objects from the ...
[ message continues ]

Hi,

On Sun, Apr 18, 2010 at 12:58 PM, Ramkumar Ramachandra

barring any comment from Junio, I think a fixup is probably more
onerous than a resend with the fixup squashed in; that is, assuming
the old iteration is already git-am'ed in, and the fixup applies onto
a new iteration.

-- 
Cheers,
Ray Chuan
--

[ message continues ]

I'll clarify. The fixup applies to `d8e255cb385365` in `pu`. The
thread begins with a patch generated from this commit: the commit is
stalled in `pu` due to lack of acks.

-- Ram
--

[ message continues ]

I think this is much easier to read.  If it is Ok with
Ramkumar, I'd squash this into the first one in the series.

Thanks.
--

[ message continues ]

Okay, sounds good.

-- Ram
--

[ message continues ]