[PATCH] Clarify role of init command in git-submodules documentation

["martin f. krafft" <madduck@madduck.net>]

As per the discussion in this thread:

  http://marc.info/?t=118721709500008&r=1&w=2

this patch updates the git-submodules documentation to make the situation
a bit clearer and documents the intended workflow.

Signed-off-by: martin f. krafft <madduck@madduck.net>
---
 Documentation/git-submodule.txt |   30 +++++++++++++++++++-----------
 1 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2c48936..8bc818a 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -32,15 +32,17 @@ status::
 	repository. This command is the default command for git-submodule.
 
 init::
-	Initialize the submodules, i.e. register in .git/config each submodule
-	name and url found in .gitmodules. The key used in .git/config is
-	`submodule.$name.url`. This command does not alter existing information
-	in .git/config.
+	Initialize the submodules, i.e. register in $GIT_DIR/config each
+	submodule name and url found in .gitmodules. The key used in
+	$GIT_DIR/config is `submodule.$name.url`. This command does not alter
+	existing information in $GIT_DIR/config, it only serves to initialise
+	the local configuration from the defaults in .gitmodules.
 
 update::
-	Update the registered submodules, i.e. clone missing submodules and
-	checkout the commit specified in the index of the containing repository.
-	This will make the submodules HEAD be detached.
+	Update the submodules registered in $GIT_DIR/config, i.e. clone
+	missing submodules and checkout the commit specified in the index of
+	the containing repository. This will make the submodules HEAD be
+	detached.
 
 
 OPTIONS
@@ -62,10 +64,16 @@ OPTIONS
 
 FILES
 -----
-When initializing submodules, a .gitmodules file in the top-level directory
-of the containing repository is used to find the url of each submodule.
-This file should be formatted in the same way as $GIR_DIR/config. The key
-to each submodule url is "submodule.$name.url".
+To work with submodules, a user has to prepare a repository clone with the
+command `git-submodule init`. This command copies the url of each submodule
+listed in the .gitmodules file in the top-level directory of the containing
+repository to $GIT_DIR/config. The key to each submodule url is
+"submodule.$name.url".
+
+The .gitmodules file then specifies the location of each submodule with
+respect to the repository (and is shared among all contributors), while the
+url of each submodule comes from the local configuration in $GIT_DIR/config
+and can thus be modified independently of all other users.
 
 
 AUTHOR
-- 
1.5.3.rc5.40.g2f82