[PATCH 06 of 14] docs/usage: rework section on non-changeable repository URLs

[Thomas De Schampheleire]

# HG changeset patch
# User Thomas De Schampheleire <thomas.de.schampheleire at gmail.com>
# Date 1428175740 -7200
#      Sat Apr 04 21:29:00 2015 +0200
# Node ID 4fea222af02fbfbd876a79f203d48650cc20e9bc
# Parent  f490e9de73ac48f9945fc49d862556d0a5034c1e
docs/usage: rework section on non-changeable repository URLs

diff --git a/docs/usage/general.rst b/docs/usage/general.rst
--- a/docs/usage/general.rst
+++ b/docs/usage/general.rst
@@ -70,31 +70,32 @@
   (and its ancestors) by selecting it and clicking the ``Open new pull request
   for selected changesets`` button.
 
-Non changeable repository urls
+Non-changeable repository URLs
 ------------------------------
 
 Due to the complicated nature of repository grouping, URLs of repositories
-can often change.
+can often change. For example, a repository originally accessible from::
 
-example::
+  http://server.com/repo_name
 
-  #before
-  http://server.com/repo_name
-  # after insertion to test_group group the url will be
+would get a new URL after moving it to test_group::
+
   http://server.com/test_group/repo_name
 
-This can be an issue for build systems and any other hardcoded scripts, moving
-a repository to a group leads to a need for changing external systems. To
-overcome this Kallithea introduces a non-changable replacement URL. It's
-simply a repository ID prefixed with ``_``. The above URLs are also accessible as::
+Such moving of a repository to a group can be an issue for build systems and
+other scripts where the repository paths are hardcoded.  To overcome this,
+Kallithea introduces a non-changeable replacement URL, based on a repository ID
+prefixed with an underscore. In all Kallithea URLs, for example those for the
+changelog and the file view, a repository name can be replaced by this ``_ID``
+string.  Since IDs are always the same, moving the repository to a different
+group will not affect such URLs.
+
+In the example, the repository could also be accessible as::
 
   http://server.com/_<ID>
 
-Since IDs are always the same, moving the repository will not affect
-such a URL.  the ``_<ID>`` syntax can be used anywhere in the system so
-URLs with ``repo_name`` for changelogs and files can be exchanged
-with the ``_<ID>`` syntax.
-
+The ID of a given repository can be shown from the repository ``Summary`` page,
+by selecting the ``Show by ID`` button next to the ``Clone URL``.
 
 E-mail notifications
 --------------------