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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Mar 29, 2010, 06:39 UTC
Message-ID: <20100329063952.GA20360@progeny.tock>
In-Reply-To: <f3271551003282318vc256d20j90bb83170b0a983@mail.gmail.com>

Ramkumar Ramachandra wrote:

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

[...]

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

One possibility: new manpage, called giturl(7) or something, with:

 - the information from your patch, reformatted a little to be from
   the caller’s perspective;

 - the information currently in the GIT URLS and REMOTES sections 
   of git-pull(1) and and other urls-remotes.txt includers;

 - pointers to appropriate high-level and low-level documentation
   for more information.

This would at least avoid some duplication of text in explaining how the [remote "<name>"] setups work.

> It certainly cannot go into remote.c or
> transport-helper.c, because they have little/ nothing to do with the
> actual argument parsing.

One possibility would be to put it in Documentation/technical/transport.txt or some similarly named new file. Later that file could expand to an overview of the transport layer, which would be nice to have.

Files in Documentation/technical do not get installed as manpages, which would make this less convenient when writing a new helper without a full documentation tree available.

More importantly, the “how to configure access to a foreign repository” aspect of what you are writing is really more pertinent to users than remote helper developers. Remote helper developers only need to know “first argument is a remote nickname or some nonsense with a colon; second argument is a transport-native address identifying the remote repository; second argument can be omitted only if a remote nickname was used”.

HTH, Jonathan