# HG changeset patch
# User Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
# Date 1428175740 -7200
# Node ID 4185f87f0ee0d8dc9ae38672324eb3a0e0f7144c
# Parent  543bf62d06c70229cba2500c652ee074d66d3b25
docs/usage: rework section on non-changeable repository URLs and call them 'permanent'

diff -r 543bf62d06c7 -r 4185f87f0ee0 docs/usage/general.rst
--- a/docs/usage/general.rst	Sat Apr 04 21:13:47 2015 +0200
+++ b/docs/usage/general.rst	Sat Apr 04 21:29:00 2015 +0200
@@ -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
-------------------------------
+Permanent repository URLs
+-------------------------
 
 Due to the complicated nature of repository grouping, URLs of repositories
-can often change.
-
-example::
+can often change. For example, a repository originally accessible from::
 
-  #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 mitigate this,
+Kallithea provides permanent URLs using the 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 ``Clone URL``.
 
 E-mail notifications
 --------------------
diff -r 543bf62d06c7 -r 4185f87f0ee0 kallithea/lib/base.py
--- a/kallithea/lib/base.py	Sat Apr 04 21:13:47 2015 +0200
+++ b/kallithea/lib/base.py	Sat Apr 04 21:29:00 2015 +0200
@@ -154,7 +154,7 @@
     def _get_by_id(self, repo_name):
         """
         Gets a special pattern _<ID> from clone url and tries to replace it
-        with a repository_name for support of _<ID> non changeable urls
+        with a repository_name for support of _<ID> permanent URLs
 
         :param repo_name:
         """
diff -r 543bf62d06c7 -r 4185f87f0ee0 kallithea/templates/admin/repos/repo_edit_settings.html
--- a/kallithea/templates/admin/repos/repo_edit_settings.html	Sat Apr 04 21:13:47 2015 +0200
+++ b/kallithea/templates/admin/repos/repo_edit_settings.html	Sat Apr 04 21:29:00 2015 +0200
@@ -8,12 +8,12 @@
                 </div>
                 <div class="input">
                     ${h.text('repo_name',class_="medium")}
-                    <span class="help-block">${_('Non-changeable id')}: `_${c.repo_info.repo_id}` <span><a id="show_more_clone_id" href="#">${_('What is that?')}</a></span></span>
+                    <span class="help-block">${_('Permanent Repository ID')}: `_${c.repo_info.repo_id}` <span><a id="show_more_clone_id" href="#">${_('What is that?')}</a></span></span>
                     <span id="clone_id" class="help-block" style="display: none">
                         ${_('URL by id')}: `${c.repo_info.clone_url(with_id=True)}` </br>
                         ${_('''In case this repository is renamed or moved into another group the repository URL changes.
-                               Using the above URL guarantees that this repository will always be accessible under such URL.
-                               Useful for CI systems, or any other cases that you need to hardcode the URL into 3rd party service.''')}</span>
+                               Using the above permanent URL guarantees that this repository always will be accessible on that URL.
+                               This is useful for CI systems, or any other cases that you need to hardcode the URL into a 3rd party service.''')}</span>
                 </div>
            </div>
            <div class="field">