Re: [PATCH v7 1/2] Documentation/remote-helpers: Rewrite description
- From
Daniel Barkalow <barkalow@iabervon.org>
- Date
- Mar 29, 2010, 05:09 UTC
- Message-ID
- <alpine.LNX.2.00.1003290055000.14365@iabervon.org>
- In-Reply-To
- <4BAFFFAB.4080808@gmail.com>
On Sun, 28 Mar 2010, Gabriel Filion wrote:
Show 29 quoted lines
> Hello, > > On 2010-03-28 14:03, Ramkumar Ramachandra wrote: > [...] > > diff --git a/Documentation/git-remote-helpers.txt > > b/Documentation/git-remote-helpers.txt > > index 1b5f61a..1304813 100644 > > --- a/Documentation/git-remote-helpers.txt > > +++ b/Documentation/git-remote-helpers.txt > [...] > > @@ -12,11 +12,31 @@ SYNOPSIS > [...] > > +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 > > Oops, "needs" is repeated twice here... > > Apart from that, it seems nice and helps to better understand what they > should be used for. > > It doesn't really concern this patch but If I'm not wrong, there still > is no documentation written on how exactly git invokes the remote > helpers. A good description was given previously by Ilari Liusvaara (so > I've added you, Ilari in the cc list). The description can be seen here: > > http://lists.zerezo.com/git/msg712892.html > > Should we add this information on this man page?
That information ought to be in the documentation, but possibly not on this man page in particular. I think it would be better to document that part in the documentation of the code and programs that call the helper, not in the helper documentation. In general, I'd like the helpers to make as few assumptions about their caller as possible, and similarly keep the information about the caller out of their documentation.
Also, I think it would be more helpful in general to get that information into documentation of the transport and remote code and configuration of these things, because users are going to come at this from that side ("I want to access an SVN repository, how does that work?") rather than from the helper documentation side ("I want to exercise git-remote-svn's export support, just to run that code").
-Daniel *This .sig left intentionally blank*