[RFC PATCH] Write new giturl(7) manpage

[Ramkumar Ramachandra <artagnon@gmail.com>]

Write a new manpage for documenting how different URLs are handled by
remote helpers.
---
 It severely lacks polish, but I thought I'd send in an early draft requesting
 comments. Also, I've made it more cryptic than Jonathan's revision and
 included more references.

 I'm not entirely happy with it because the remote vcs setting doesn't
 quite fit here. Plus, it seems like a dirty hack to me. The name doesn't do
 justice: giturl exists to host Ilari's remote helper notes. How can it be
 expanded to be more general?

 Why doesn't urls.txt document <transport>::<address> syntax? Should I
 fix this?

 Documentation/giturl.txt |   85 ++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 85 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/giturl.txt

diff --git a/Documentation/giturl.txt b/Documentation/giturl.txt
new file mode 100644
index 0000000..9ffd17c
--- /dev/null
+++ b/Documentation/giturl.txt
@@ -0,0 +1,85 @@
+giturl(7)
+=========
+
+NAME
+----
+giturl - An overview on how different URLs are handled by Git
+
+SYNOPSIS
+--------
+git *
+
+DESCRIPTION
+-----------
+
+URLs are used in two places. Directly on the command line by the end
+user, and in remotes configuration (see REMOTES section below). They
+all have the general structure described in the URLS section
+below. While most of them are handled by Git internally, some of them
+are handled by remote helper programs. When a URL thatgit doesn't
+handle internally is encountered either on the command line or in the
+remotes configuration, a remote helper that does will be used
+transparently by the transport machinery of git (i.e., by commands
+such as git ls-remote, git send-pack, and git archive --remote). The
+following is a list of such URLs:
+
+<transport>::<address>
+~~~~~~~~~~~~~~~~~~~~~~
+A URL of the form `<transport>::<rest-of-URL>` is used on the command
+line by the end-user.
+
+The 'git remote-<transport>' helper will be invoked with the full
+<transport>::<rest-of-URL> URL as the first argument and <address> as
+the second argument.
+
+<name> with vcs set
+~~~~~~~~~~~~~~~~~~~
+`remote.<name>.vcs` is set to `<transport>` (see
+git-config[1]). `remote.<name>.url` is optionally set to a URL of the
+form `<transport>://<rest-of-URL>`.
+
+If the `remote.<name>.url` is set, the helper will be invoked with
+`<name>` as the first argument and `<rest-of-URL>` as the second
+argument.  Otherwise, the helper will be invoked with a single
+argument, `<name>`.
+
+<nickname> with vcs unset
+~~~~~~~~~~~~~~~~~~~~~~~~~
+`remote.<name>.url` is set to a URL of the form
+`<transport>://<rest-of-URL>`.
+
+The ‘git remote-<transport>’ helper will be invoked with the
+`<name>` as first argument and `<transport>://<rest-of-URL>` as the
+second argument.
+
+Exception: the built-in 'rsync', 'file', 'git', 'ssh', 'git+ssh', and
+'ssh+git' transports are not handled using remote helpers.
+
+<transport>://<rest-of-URL>
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A URL of the form `<transport>://<rest-of-URL>` is used on the command
+line by the end-user.
+
+If 'transport' is not one of the built-in protocols listed above, the
+'git remote-<transport>' helper will be invoked with two arguments,
+both equal to the full `<transport>://<rest-of-URL>` URL.
+
+include::urls-remotes.txt[]
+
+SEE ALSO
+--------
+linkgit:git-remote-helpers[1]
+linkgit:git-remote[1]
+linkgit:git-config[1]
+
+Author
+------
+Written by Ramkumar Ramachandra
+
+Documentation
+-------------
+Documentation by Ilari Liusvaara and the git-list <git@vger.kernel.org>
+
+GIT
+---
+Part of the linkgit:git[1] suite
-- 
1.7.0.3