docs: outline the challenges of specifying a locale for services (Issue #340)

Trying to embed the most essential parts of
http://blog.dscpl.com.au/2014/09/setting-lang-and-lcall-when-using.html and
https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIDaemonProcess.html
.

(some rewording by Thomas De Schampheleire)

docs/overview.rst

@@ -37,6 +37,41 b' environment used for running Kallithea.'
 We recommend using virtualenv for installing Kallithea.
 
 
+Locale environment
+------------------
+
+In order to ensure a correct functioning of Kallithea with respect to non-ASCII
+characters in user names, file paths, commit messages, etc., it is very
+important that Kallithea is run with a correct `locale` configuration.
+
+On Unix, environment variables like ``LANG`` or ``LC_ALL`` can specify a language (like
+``en_US``) and encoding (like ``UTF-8``) to use for code points outside the ASCII
+range. The flexibility of supporting multiple encodings of Unicode has the flip
+side of having to specify which encoding to use - especially for Mercurial.
+
+It depends on the OS distribution and system configuration which locales are
+available. For example, some Docker containers based on Debian default to only
+supporting the ``C`` language, while other Linux environments have ``en_US`` but not
+``C``. The ``locale -a`` command will show which values are available on the
+current system. Regardless of the actual language, you should normally choose a
+locale that has the ``UTF-8`` encoding (note that spellings ``utf8``, ``utf-8``,
+``UTF8``, ``UTF-8`` are all referring to the same thing)
+
+For technical reasons, the locale configuration **must** be provided in the
+environment in which Kallithea runs - it cannot be specified in the ``.ini`` file.
+How to practically do this depends on the web server that is used and the way it
+is started. For example, gearbox is often started by a normal user, either
+manually or via a script. In this case, the required locale environment
+variables can be provided directly in that user's environment or in the script.
+However, web servers like Apache are often started at boot via an init script or
+service file. Modifying the environment for this case would thus require
+root/administrator privileges. Moreover, that environment would dictate the
+settings for all web services running under that web server, Kallithea being
+just one of them. Specifically in the case of Apache with ``mod_wsgi``, the
+locale can be set for a specific service in its ``WSGIDaemonProcess`` directive,
+using the ``lang`` parameter.
+
+
 Installation methods
 --------------------
 

docs/setup.rst

@@ -539,6 +539,12 b" that, you'll need to:"
 - Add the necessary ``WSGI*`` directives to the Apache Virtual Host configuration
   file, like in the example below. Notice that the WSGI dispatch script created
   above is referred to with the ``WSGIScriptAlias`` directive.
+  The default locale settings Apache provides for web services are often not
+  adequate, with `C` as the default language and `ASCII` as the encoding.
+  Instead, use the ``lang`` parameter of ``WSGIDaemonProcess`` to specify a
+  suitable locale. See also the :ref:`overview` section and the
+  `WSGIDaemonProcess documentation`_.
+
   Apache will by default run as a special Apache user, on Linux systems
   usually ``www-data`` or ``apache``. If you need to have the repositories
   directory owned by a different user, use the user and group options to
@@ -549,7 +555,7 b" that, you'll need to:"
   .. code-block:: apache
 
       WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 \
-          python-home=/srv/kallithea/venv
+          python-home=/srv/kallithea/venv lang=C.UTF-8
       WSGIProcessGroup kallithea
       WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
       WSGIPassAuthorization On
@@ -558,7 +564,7 b" that, you'll need to:"
 
   .. code-block:: apache
 
-      WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100
+      WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 lang=en_US.utf8
       WSGIProcessGroup kallithea
       WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
       WSGIPassAuthorization On
@@ -583,3 +589,4 b' the ``init.d`` directory of the Kallithe'
 .. _Redis: http://redis.io/
 .. _mercurial-server: http://www.lshift.net/mercurial-server.html
 .. _PublishingRepositories: https://www.mercurial-scm.org/wiki/PublishingRepositories
+.. _WSGIDaemonProcess documentation: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIDaemonProcess.html