From acb098a382b25af42176f149ca5f78c195ea318d Mon Sep 17 00:00:00 2001
From: Foo <kp-pav@yandex.ru>
Date: Sat, 30 May 2015 14:24:30 +0300
Subject: [PATCH] Clarify where powerline configuration files are located

Closes #1375
---
 docs/source/configuration.rst | 42 +++++++++++++++++------------------
 1 file changed, 20 insertions(+), 22 deletions(-)

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index 7c20eb17..412fb6a6 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -15,20 +15,27 @@ written in Python.
 Powerline provides default configurations in the following locations:
 
 :ref:`Main configuration <config-main>`
-    :file:`powerline/config.json`
+    :file:`{powerline}/config.json`
 :ref:`Colorschemes <config-colorschemes>`
-    :file:`powerline/colorschemes/{name}.json`, 
-    :file:`powerline/colorscheme/{extension}/__main__.json`, 
-    :file:`powerline/colorschemes/{extension}/{name}.json`
+    :file:`{powerline}/colorschemes/{name}.json`, 
+    :file:`{powerline}/colorschemes/{extension}/__main__.json`, 
+    :file:`{powerline}/colorschemes/{extension}/{name}.json`
 :ref:`Themes <config-themes>`
-    :file:`powerline/themes/{top_theme}.json`, 
-    :file:`powerline/themes/{extension}/__main__.json`, 
-    :file:`powerline/themes/{extension}/default.json`
+    :file:`{powerline}/themes/{top_theme}.json`, 
+    :file:`{powerline}/themes/{extension}/__main__.json`, 
+    :file:`{powerline}/themes/{extension}/default.json`
 
-The default configuration files are stored in the main package. User 
-configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for 
-Linux users, and in :file:`~/.config/powerline` for OS X users. This usually 
-corresponds to :file:`~/.config/powerline` on both platforms.
+Here `{powerline}` is one of the following:
+
+#. The default configuration directory located in the main package: 
+   :file:`{powerline_root}/powerline/config_files`. May be absent in some 
+   packages (e.g. when installing via Gentoo ebuilds).
+#. If variable ``$XDG_CONFIG_DIRS`` is set and non-empty then to any 
+   :file:`{directory}/powerline` where `{directory}` is a directory listed in 
+   a colon-separated ``$XDG_CONFIG_DIRS`` list. Directories are checked in 
+   reverse order.
+#. User configuration directory located in :file:`$XDG_CONFIG_HOME/powerline`. 
+   This usually corresponds to :file:`~/.config/powerline` on all platforms.
 
 If per-instance configuration is needed please refer to :ref:`Local 
 configuration overrides <local-configuration-overrides>`.
@@ -37,17 +44,8 @@ configuration overrides <local-configuration-overrides>`.
 
 .. note::
    Existing multiple configuration files that have the same name, but are placed 
-   in different directories, will be merged. Merging happens in the following 
-   order:
-
-   * :file:`{powerline_root}/powerline/config_files` is checked for 
-     configuration first. Configuration from this source has least priority.
-   * :file:`$XDG_CONFIG_DIRS/powerline` directories are the next ones to check. 
-     Checking happens in the reversed order: directories mentioned last are 
-     checked before directories mentioned first. Each new found file is merged 
-     with the result of previous merge.
-   * :file:`$XDG_CONFIG_HOME/powerline` directory is the last to check. 
-     Configuration from there has top priority.
+   in different directories, will be merged. Merging happens in the order given 
+   in the above list of possible `{powerline}` meanings.
 
    When merging configuration only dictionaries are merged and they are merged 
    recursively: keys from next file overrule those from the previous unless