<repository> is the URL of the new submodule's origin repository.
 This may be either an absolute URL, or (if it begins with ./
 or ../), the location relative to the superproject's origin
-repository. If the superproject doesn't have an origin configured
+repository (Please note that to specify a repository 'foo.git'
+which is located right next to a superproject 'bar.git', you'll
+have to use '../foo.git' instead of './foo.git' - as one might expect
+when following the rules for relative URLs - because the evaluation
+of relative URLs in Git is identical to that of relative directories).
+If the superproject doesn't have an origin configured
 the superproject is its own authoritative upstream and the current
 working directory is used instead.
 +
 sync::
        Synchronizes submodules' remote URL configuration setting
        to the value specified in .gitmodules. It will only affect those
-       submodules which already have an url entry in .git/config (that is the
+       submodules which already have a URL entry in .git/config (that is the
        case when they are initialized or freshly added). This is useful when
        submodule URLs change upstream and you need to update your local
        repositories accordingly.