From 9a4e1edfbcaffaebf08f6f685ac91e25aaf6fd1b Mon Sep 17 00:00:00 2001
From: ZyX <kp-pav@yandex.ru>
Date: Mon, 23 Jun 2014 20:03:24 +0400
Subject: [PATCH] Update documentation

---
 docs/source/configuration.rst | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index 73c9943a..0ab55695 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -305,8 +305,22 @@ Themes
     step 2 is obviously avoided.
 
 ``segments``
-    A dict with a ``left`` and a ``right`` list, consisting of segment 
-    dicts. Each segment has the following options:
+    A dict with a ``left`` and a ``right`` lists, consisting of segment 
+    dictionaries. Shell themes may also contain ``above`` list of dictionaries. 
+    Each item in ``above`` list may have ``left`` and ``right`` keys like this 
+    dictionary, but no ``above`` key.
+
+    .. _config-themes-above:
+
+    ``above`` list is used for multiline shell configurations.
+
+    ``left`` and ``right`` lists are used for segments that should be put on the 
+    left or right side in the output. Actual mechanizm of putting segments on 
+    the left or the right depends on used renderer, but most renderers require 
+    one to specify segment with :ref:`width <config-themes-seg-width>` ``auto`` 
+    on either side to make generated line fill all of the available width.
+
+    Each segment dictionary has the following options:
 
     ``type``
         The segment type. Can be one of ``function`` (default), ``string`` 
@@ -368,6 +382,8 @@ Themes
         right (``r``).
 
     ``width``
+        .. _config-themes-seg-width:
+
         Enforces a specific width for this segment.
 
         This segment will work as a spacer if the width is set to ``auto``.
@@ -566,6 +582,15 @@ configuration script was sourced (in fish case: after ``powerline-setup``
 function was run). To disable specific feature support set one of these 
 variables to some non-empty value.
 
+If you do not want to disable prompt in shell, but yet do not want to launch 
+python twice to get :ref:`above <config-themes-above>` lines you do not use in 
+tcsh you should set ``$POWERLINE_NO_TCSH_ABOVE`` or 
+``$POWERLINE_NO_SHELL_ABOVE`` variable.
+
+If you do not want to see additional space which is added to the right prompt in 
+fish in order to support multiline prompt you should set 
+``$POWERLINE_NO_FISH_ABOVE`` or ``$POWERLINE_NO_SHELL_ABOVE`` variables.
+
 .. note::
 
     Most supported shells’ configuration scripts check for additional