Re: [PATCH v7 1/2] Documentation/remote-helpers: Rewrite description

[Ramkumar Ramachandra <artagnon@gmail.com>]

Hi,

> 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.

I agree that the callers need to document the subset of the
invocations they make to remote helpers. I think we can defer this
until we have a real remote helper in `git.git` that actually
interfaces with a foreign versioning system.

I've thought about documenting the full set of invocations in the code
for the developer, but there's a problem. Here's an excerpt from
remote-curl.c, showing how it parses its command line arguments:

	remote = remote_get(argv[1]);

	if (argc > 2) {
		url = argv[2];
	} else {
		url = remote->url[0];
	}

Unfortunately, I don't see where else this documentation can fit in:
if it were to go into a specific remote helper's code, then it'll have
to be duplicated for all the remote helpers, since all of them parse
options similarly. It certainly cannot go into remote.c or
transport-helper.c, because they have little/ nothing to do with the
actual argument parsing.

I could try modifying the documentation I've written to serve more to
specify "how remote helpers are invoked" and less about "how callers
invoke remote helpers", and try to fit it in this manpage. It's more
of a developer manpage and less of an end-user manpage as it is. Or we
could create another page about remote helpers intended to be read
exclusively by developers. What are your thoughts on this?

-- Ram