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

[Jonathan Nieder <jrnieder@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