1 files changed, 161 insertions, 0 deletions
diff --git a/docs/source/usage/shell-prompts.rst b/docs/source/usage/shell-prompts.rst
new file mode 100644
index 0000000..17774da
--- /dev/null
+++ b/docs/source/usage/shell-prompts.rst
@@ -0,0 +1,161 @@
+.. _usage-shell:
+
+*************
+Shell prompts
+*************
+
+.. note::
+    Powerline can operate without a background daemon, but the shell performance
+    can be very slow.  The Powerline daemon improves this performance
+    significantly, but must be started separately. It is advised to add
+
+    .. code-block:: bash
+
+        powerline-daemon -q
+
+    before any other powerline-related code in the shell configuration file.
+
+Bash prompt
+===========
+
+Add the following line to the :file:`bashrc`, where ``{repository_root}`` is the 
+absolute path to the Powerline installation directory (see :ref:`repository root 
+<repository-root>`):
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/bash/powerline.sh
+
+.. note::
+    Since without powerline daemon bash bindings are very slow PS2 
+    (continuation) and PS3 (select) prompts are not set up. Thus it is advised 
+    to use
+
+    .. code-block:: bash
+
+       powerline-daemon -q
+       POWERLINE_BASH_CONTINUATION=1
+       POWERLINE_BASH_SELECT=1
+       . {repository_root}/powerline/bindings/bash/powerline.sh
+
+    in the bash configuration file. Without ``POWERLINE_BASH_*`` variables PS2 
+    and PS3 prompts are computed exactly once at bash startup.
+
+.. warning::
+    At maximum bash continuation PS2 and select PS3 prompts are computed each 
+    time main PS1 prompt is computed. Thus putting e.g. current time into PS2 or 
+    PS3 prompt will not work as expected.
+
+    At minimum they are computed once on startup.
+
+Zsh prompt
+==========
+
+Add the following line to the :file:`zshrc`, where ``{repository_root}`` is the 
+absolute path to the Powerline installation directory (see :ref:`repository root 
+<repository-root>`):
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/zsh/powerline.zsh
+
+Fish prompt
+===========
+
+Add the following line to :file:`config.fish`, where ``{repository_root}`` is 
+the absolute path to the Powerline installation directory (see :ref:`repository 
+root <repository-root>`):
+
+.. code-block:: bash
+
+   set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
+   powerline-setup
+
+.. warning:: Fish is supported only starting from version 2.1.
+
+Rcsh prompt
+===========
+
+Powerline supports Plan9 rc reimplementation *by Byron Rakitzis* packaged by 
+many \*nix distributions. To use it add
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/rc/powerline.rc
+
+(``{repository_root}`` is the absolute path to the Powerline installation 
+directory, see :ref:`repository root <repository-root>`) to :file:`rcrc` file 
+(usually :file:`~/.rcrc`) and make sure ``rc`` is started as a login shell (with 
+``-l`` argument): otherwise this configuration file is not read.
+
+.. warning::
+   Original Plan9 shell and its \*nix port are not supported because they are 
+   missing ``prompt`` special function (it is being called once before each 
+   non-continuation prompt). Since powerline could not support shell without 
+   this or equivalent feature some other not-so-critical features of that port 
+   were used.
+
+Busybox (ash), mksh and dash prompt
+=====================================
+
+After launching busybox run the following command:
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/shell/powerline.sh
+
+where ``{repository_root}`` is the absolute path to the Powerline installation 
+directory (see :ref:`repository root <repository-root>`).
+
+Mksh users may put this line into ``~/.mkshrc`` file. Dash users may use the 
+following in ``~/.profile``:
+
+.. code-block:: bash
+
+    if test "$0" != "${0#dash}" ; then
+        export ENV={repository_root}/powerline/bindings/shell/powerline.sh
+    fi
+
+.. note::
+    Dash users that already have ``$ENV`` defined should either put the ``. 
+    …/shell/powerline.sh`` line in the ``$ENV`` file or create a new file which 
+    will source (using ``.`` command) both former ``$ENV`` file and 
+    :file:`powerline.sh` files and set ``$ENV`` to the path of this new file.
+
+.. warning::
+    Mksh users have to set ``$POWERLINE_SHELL_CONTINUATION`` and 
+    ``$POWERLINE_SHELL_SELECT`` to 1 to get PS2 and PS3 (continuation and 
+    select) prompts support respectively: as command substitution is not 
+    performed in these shells for these prompts they are updated once each time 
+    PS1 prompt is displayed which may be slow.
+
+    It is also known that while PS2 and PS3 update is triggered at PS1 update it 
+    is *actually performed* only *next* time PS1 is displayed which means that 
+    PS2 and PS3 prompts will be outdated and may be incorrect for this reason.
+
+    Without these variables PS2 and PS3 prompts will be set once at startup. 
+    This only touches mksh users: busybox and dash both have no such problem.
+
+.. warning::
+    Job count is using some weird hack that uses signals and temporary files for 
+    interprocess communication. It may be wrong sometimes. Not the case in mksh.
+
+.. warning::
+    Busybox has two shells: ``ash`` and ``hush``. Second is known to segfault in 
+    busybox 1.22.1 when using :file:`powerline.sh` script.
+    
+Python Virtual Environments (conda, pyenv)
+==========================================
+
+If your system uses virtual environments to manage different Python versions,
+such as pyenv or anaconda, these tools will add a performance delay to every
+shell prompt.  This delay can be bypassed by explicitly specifying your command
+path.
+
+    .. code-block:: bash
+
+        export POWERLINE_COMMAND={path_to_powerline}
+        
+where ``{path_to_powerline}`` is the full filepath for powerline.  If you
+installed Powerline within an environment, you can find this path for pyenv
+with ``pyenv which powerline`` or for conda with ``which powerline``.