1 files changed, 110 insertions, 0 deletions
diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst
new file mode 100644
index 0000000..e134707
--- /dev/null
+++ b/docs/source/installation/linux.rst
@@ -0,0 +1,110 @@
+*********************
+Installation on Linux
+*********************
+
+The following distribution-specific packages are officially supported, and they 
+provide an easy way of installing and upgrading Powerline. The packages will 
+automatically do most of the configuration.
+
+* `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_
+* `Arch Linux (AUR), Python 3 version <https://aur.archlinux.org/packages/python-powerline-git/>`_
+* Gentoo Live ebuild in `raiagent <https://github.com/leycec/raiagent>`_ overlay
+* Powerline package is available for Debian starting from Wheezy (via `backports 
+  <https://packages.debian.org/wheezy-backports/powerline>`_). Use `search 
+  <https://packages.debian.org/search?keywords=powerline&searchon=names&suite=all&section=all>`_ 
+  to get more information.
+
+If used distribution does not have an official package installation guide below 
+should be followed:
+
+1. Install Python 3.2+, Python 2.6+ or PyPy and ``pip`` with ``setuptools``. 
+   This step is distribution-specific, so no commands provided.
+2. Install Powerline using one of the following commands:
+
+   .. code-block:: sh
+
+      pip install --user powerline-status
+
+   will get the latest release version and
+
+   .. code-block:: sh
+
+      pip install --user git+https://github.com/powerline/powerline
+
+   will get the latest development version.
+
+   .. note:: Due to the naming conflict with an unrelated project powerline is
+      named ``powerline-status`` in PyPI.
+
+   .. note::
+      Powerline developers should be aware that``pip install --editable`` does 
+      not currently fully work. Installation performed this way are missing 
+      ``powerline`` executable that needs to be symlinked. It will be located in 
+      ``scripts/powerline``.
+
+Fonts installation
+==================
+
+Fontconfig
+----------
+
+This method only works on Linux. It’s the second recommended method if terminal 
+emulator supports it as patching fonts is not needed, and it generally works 
+with any coding font.
+
+#. Download the latest version of the symbol font and fontconfig file::
+
+      wget https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf
+      wget https://github.com/powerline/powerline/raw/develop/font/10-powerline-symbols.conf
+
+#. Move the symbol font to a valid X font path. Valid font paths can be 
+   listed with ``xset q``::
+
+      mv PowerlineSymbols.otf ~/.local/share/fonts/
+
+#. Update font cache for the path the font was moved to (root privileges may be 
+   needed to update cache for the system-wide paths)::
+
+      fc-cache -vf ~/.local/share/fonts/
+
+#. Install the fontconfig file. For newer versions of fontconfig the config 
+   path is ``~/.config/fontconfig/conf.d/``, for older versions it’s  
+   ``~/.fonts.conf.d/``::
+
+      mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/
+
+If custom symbols still cannot be seen then try closing all instances of the 
+terminal emulator. Restarting X may be needed for the changes to take effect.
+
+If custom symbols *still* can’t be seen, double-check that the font have been 
+installed to a valid X font path, and that the fontconfig file was installed to 
+a valid fontconfig path. Alternatively try to install a :ref:`patched font 
+<installation-patched-fonts>`.
+
+Patched font installation
+-------------------------
+
+This is the preferred method, but it is not always available because not all 
+fonts were patched and not all fonts *can* be patched due to licensing issues.
+
+After downloading font the following should be done:
+
+#. Move the patched font to a valid X font path. Valid font paths can be 
+   listed with ``xset q``::
+
+      mv 'SomeFont for Powerline.otf' ~/.local/share/fonts/
+
+#. Update font cache for the path the font was moved to (root privileges may be 
+   needed for updating font cache for some paths)::
+
+      fc-cache -vf ~/.local/share/fonts/
+
+After installing patched font terminal emulator, GVim or whatever application 
+powerline should work with must be configured to use the patched font. The 
+correct font usually ends with *for Powerline*.
+
+If custom symbols cannot be seen then try closing all instances of the terminal 
+emulator. X server may need to be restarted for the changes to take effect.
+
+If custom symbols *still* can’t be seen then double-check that the font have 
+been installed to a valid X font path.