[PATCH v2] Documentation/urls: Rewrite to accomodate <transport>::<address>

[Ramkumar Ramachandra <artagnon@gmail.com>]

Rewrite the first part of the document to explicitly show differences
between the URLs that can be used with different transport
protocols. Mention <transport>::<address> format to explicitly invoke
a remote helper.
---
 Complete rewrite since v1. Ilari's review mentioned that <address>
 can be anything, depending on the remote helper used. Removed
 redundancy and clarified rest of document so that this fact isn't
 confusing.

 Documentation/urls.txt |   58 +++++++++++++++++++++++------------------------
 1 files changed, 28 insertions(+), 30 deletions(-)

diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 459a394..262c729 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -1,44 +1,42 @@
 GIT URLS[[URLS]]
 ----------------

-One of the following notations can be used
-to name the remote repository:
-
-- rsync://host.xz/path/to/repo.git/
-- http://host.xz{startsb}:port{endsb}/path/to/repo.git/
-- https://host.xz{startsb}:port{endsb}/path/to/repo.git/
-- git://host.xz{startsb}:port{endsb}/path/to/repo.git/
-- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/
-- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/
-- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/
-- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/
-- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git
-
-SSH is the default transport protocol over the network.  You can
-optionally specify which user to log-in as, and an alternate,
-scp-like syntax is also supported.  Both syntaxes support
-username expansion, as does the native git protocol, but
-only the former supports port specification. The following
-three are identical to the last three above, respectively:
-
-- {startsb}user@{endsb}host.xz:/path/to/repo.git/
-- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/
+In general, URLs contain information about the transport protocol, the
+address of the remote server and the path to the repository. Depending
+on the transport protocol, some of these may be omitted.
+
+SSH is the default transport protocol over the network, which allows
+optional username and port specification. An alternate scp-like syntax
+is also supported, and both syntaxes support username expansion.
+
+- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git
 - {startsb}user@{endsb}host.xz:path/to/repo.git

-To sync with a local directory, you can use:
+The native git, rsync, http, and https transport helpers support the
+following syntaxes:
+
+- git://host.xz{startsb}:port{endsb}/path/to/repo.git
+- rsync://host.xz/path/to/repo.git
+- http://host.xz{startsb}:port{endsb}/path/to/repo.git
+- https://host.xz{startsb}:port{endsb}/path/to/repo.git

-- /path/to/repo.git/
-- file:///path/to/repo.git/
+For local respositories, the following syntaxes are supported:
+
+- /path/to/repo.git
+- file:///path/to/repo.git

 ifndef::git-clone[]
-They are mostly equivalent, except when cloning.  See
-linkgit:git-clone[1] for details.
+They are mostly equivalent, except when cloning, when the former
+implies --local option. See linkgit:git-clone[1] for details.
 endif::git-clone[]

-ifdef::git-clone[]
-They are equivalent, except the former implies --local option.
-endif::git-clone[]
+To explicity request a remote helper for a certain transport protocol,
+you can use:
+
+- <transport>::<address>

+where <address> may be a path, a server and path, or something else
+depending on the remote helper.

 If there are a large number of similarly-named remote repositories and
 you want to use a different format for them (such that the URLs you
-- 
1.7.0.3