Ramkumar Ramachandra <artagnon@xxxxxxxxx> writes: > I prepared this revision after Daniel Barkalow's comments [2] > and [3]. > Daniel: Could you please comment on this? Sorry for putting you in an awkward place. I think Daniel and I have different target audience in mind for various pieces of documentation. Here is what I think. - An end user who has heard of a "svn" foreign interface may want to look at something like urls.txt (which is included by the manual page for clone and perhaps fetch) to learn how to use a repository his friends who are still using Subversion use with his git installation. When "svn" foreign interface is polished enough to be a first class citizen, I would imagine that we would have a simple "to access Subversion repository using their native protocol, use the same URL as your Subversion friends use, e.g. svn://svn.rockbox.org/rockbox", and that description would appear at the same level as our native URLs like "git://k.org/pub/scm/git/git.git" (that is what I mean by "first class citizen"). - On the other hand, I think git-remote-helpers.txt would be more for helper writers than the end users. We could move detailed discussion that are needed by helper writers to Documentation/technical/, but then I do not see much else to discuss in git-remote-helpers left. I do not see how the end user needs anything deeper than the simple "here is how you would give the protocol and location to your 'git clone' and everything else will be set up for you" that would be in urls.txt. > [2] http://thread.gmane.org/gmane.comp.version-control.git/143438 [regarding Ilari's description on how helper is chosen] 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"). While in principle I can understand Daniel's aversion of spelling things out in too much detail to paint himself in a corner he cannot get out of, I think it is necessary to give the overall picture to the readers (my intended target audience is "helper writers"). In other words, I think the documentation needs to say something like: "clone" gets transport and transport specific data to identify the data source in _this_ way from the user, stores it in .git/config for future interaction with the same foreign repository by _this_ and _that_ command, and all these will cause your helper program to be called _this_ way, hence your program must be prepared to do _this_ and _that_. and it wouldn't be as helpful to the helper writers if we only said the last "your program must do this and that" part. > [3] http://thread.gmane.org/gmane.comp.version-control.git/143483 I think getting information on what the helper is supposed to do with its command-line arguments into this man page would be good, and the appropriate focus for the man page. The current answer is this: argv[1] is the name of a remote, which may be a nickname or some more direct name; in any case, remote_get() will produce the available data for it. argv[2] is the URL, if there is one. Since a remote could have more than one URL, the helper gets the URL it should be handling. Some systems don't use URLs, and these will just look at the remote or something like that. The rest of what you wrote is true, but it's really more information on how the attributes of remotes are determined than what the helper should be worrying about. Here mostly Daniel agrees with me that having techinical details that is needed for helper writers in git-remote-helpers.txt is a good idea, but I am not sure if I agree with the last paragraph. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html