[PATCH v4] Improve remote-helpers documentation

[PATCH v4] Improve remote-helpers documentation

[Ramkumar Ramachandra]

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

diff --git a/Documentation/git-remote-helpers.txt
b/Documentation/git-remote-helpers.txt
index 1b5f61a..2d5aa8c 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 for interacting with remote repositories

 SYNOPSIS
 --------
@@ -13,10 +13,23 @@ 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.
+invoked by various git programs that interact with remote
+repositories.  For a program to qualify as a remote helper, it must
+implement a subset of the capabilities documented here, and conform to
+the remote helper protocol. Remote helpers are spawned as binaries by
+the main git programs and interact using text streams, without
+linking.
+
+The curl helper is one such program. It is invoked via
+'git-remote-http', 'git-remote-https', 'git-remote-ftp', or
+'git-remote-ftps', and implments the capabilities 'fetch', 'option',
+and 'push'. The curl helper essentially helps in transporting native
+git objects.
+
+As opposed to native git objects, remote helpers can also provide a
+fast-import stream through the 'import' capability. This makes them
+especially useful when native interoperability with a foreign
+versioning system is desired.

 COMMANDS
 --------
@@ -118,17 +131,9 @@ capabilities reported by the helper.
 CAPABILITIES
 ------------

-'fetch'::
-	This helper supports the 'fetch' command.
-
-'option'::
-	This helper supports the option command.
-
-'push'::
-	This helper supports the 'push' command.
-
-'import'::
-	This helper supports the 'import' command.
+The following capabilities indicate that the remote helper supports
+the corresponding command with the same name: 'fetch', 'option',
+'push', 'connect', and 'import'.

 'refspec' 'spec'::
 	When using the import command, expect the source ref to have
@@ -140,9 +145,6 @@ CAPABILITIES
 	all, it must cover all refs reported by the list command; if
 	it is not used, it is effectively "*:*"

-'connect'::
-	This helper supports the 'connect' command.
-
 REF LIST ATTRIBUTES
 -------------------

-- 
1.7.0.2

Re: [PATCH v4] Improve remote-helpers documentation

[Daniel Barkalow]

Looks good, other than an optional suggestion below. Incidentally, it's 
often helpful to describe the differences between earlier versions and v4 
of the patch between the "---" and the diffstat; that part of the email 
doesn't go into the commit, but can be seen by reviewers.

On Mon, 22 Mar 2010, Ramkumar Ramachandra wrote:

> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/git-remote-helpers.txt |   40 +++++++++++++++++----------------
>  1 files changed, 21 insertions(+), 19 deletions(-)
> 
> diff --git a/Documentation/git-remote-helpers.txt
> b/Documentation/git-remote-helpers.txt
> index 1b5f61a..2d5aa8c 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 for interacting with remote repositories
> 
>  SYNOPSIS
>  --------
> @@ -13,10 +13,23 @@ 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.
> +invoked by various git programs that interact with remote
> +repositories.  For a program to qualify as a remote helper, it must
> +implement a subset of the capabilities documented here, and conform to
> +the remote helper protocol. Remote helpers are spawned as binaries by
> +the main git programs and interact using text streams, without
> +linking.
> +
> +The curl helper is one such program. It is invoked via
> +'git-remote-http', 'git-remote-https', 'git-remote-ftp', or
> +'git-remote-ftps', and implments the capabilities 'fetch', 'option',
> +and 'push'. The curl helper essentially helps in transporting native
> +git objects.
> +
> +As opposed to native git objects, remote helpers can also provide a
> +fast-import stream through the 'import' capability. This makes them
> +especially useful when native interoperability with a foreign
> +versioning system is desired.
> 
>  COMMANDS
>  --------
> @@ -118,17 +131,9 @@ capabilities reported by the helper.
>  CAPABILITIES
>  ------------
> 
> -'fetch'::
> -	This helper supports the 'fetch' command.
> -
> -'option'::
> -	This helper supports the option command.
> -
> -'push'::
> -	This helper supports the 'push' command.
> -
> -'import'::
> -	This helper supports the 'import' command.
> +The following capabilities indicate that the remote helper supports
> +the corresponding command with the same name: 'fetch', 'option',
> +'push', 'connect', and 'import'.

This is, indeed, what I was suggesting, although I think it might be more 
readable like:

'fetch'::
'option'::
'push'::
'connect'::
'import'::
	This helper supports the corresponding command with the same name.

But I'm fine with whichever format is most helpful for someone trying to 
read the document (that is, to you).

	-Daniel
*This .sig left intentionally blank*

Re: [PATCH v4] Improve remote-helpers documentation

[Ramkumar Ramachandra]

> But I'm fine with whichever format is most helpful for someone trying to
> read the document (that is, to you).

Your format is indeed more elegant- I've incorporated this change in v5. Thanks.

-- Ram