Add font installation instructions

docs/source/installation.rst

@@ -52,6 +52,38 @@ and you will have to do something like::
     (``git+https://github.com/Lokaltog/powerline``) protocols. ``git`` protocol 
     should be the fastest, but least secure one though.
 
+Fonts installation
+==================
+
+Powerline uses several special glyphs to get the arrow effect and some custom 
+symbols for developers. This requires that you either have a symbol font or 
+a patched font on your system. Your terminal emulator must also support either 
+patched fonts or fontconfig for Powerline to work properly.
+
+You can also enable :ref:`24-bit color support <config-common-term_truecolor>` 
+if your terminal emulator supports it (see :ref:`the terminal emulator support 
+matrix <usage-terminal-emulators>`).
+
+There are basically two ways to get powerline glyphs displayed: use 
+:file:`PowerlineSymbols.otf` font as a fallback for one of the existing fonts or 
+install a patched font.
+
+.. _installation-patched-fonts:
+
+Patched fonts
+-------------
+
+This method is the fallback method and works for every terminal, with the 
+exception of :ref:`rxvt-unicode <tips-and-tricks-urxvt>`.
+
+Download the font of your choice from `powerline-fonts`_. If you can't find 
+your preferred font in the `powerline-fonts`_ repo, you'll have to patch your 
+own font instead.
+
+.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
+
+After downloading this font refer to platform-specific instructions.
+
 Installation on various platforms
 =================================
 

docs/source/installation/linux.rst

@@ -27,3 +27,69 @@ follow the installation guide below:
    --editable`` does not currently fully work. If you
    install powerline this way you will be missing ``powerline`` executable and 
    need to symlink it. It will be located in ``scripts/powerline``.
+
+Fonts installation
+==================
+
+Fontconfig
+----------
+
+This method only works on Linux. It's the recommended method if your 
+terminal emulator supports it as you don't have to patch any fonts, and it 
+generally works well with any coding font.
+
+#. Download the latest version of the symbol font and fontconfig file::
+
+      wget https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf
+      wget https://github.com/Lokaltog/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 ~/.fonts/
+
+#. Update font cache for the path you moved the font to (you may need to be 
+   root to update the cache for system-wide paths)::
+
+      fc-cache -vf ~/.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 you can't see the custom symbols, please close all instances of your 
+terminal emulator. You may need to restart X for the changes to take
+effect.
+
+If you *still* can't see the custom symbols, double-check that you have 
+installed the font to a valid X font path, and that you have installed the 
+fontconfig file to a valid fontconfig path. Alternatively try to install 
+a :ref:`patched font <installation-patched-fonts>`.
+
+Patched font installation
+-------------------------
+
+After downloading font you should do the following:
+
+#. Move the patched font to a valid X font path. Valid font paths can be 
+   listed with ``xset q``::
+
+      mv 'MyFont for Powerline.otf' ~/.fonts/
+
+#. Update font cache for the path you moved the font to (you may need to be 
+   root to update the cache for system-wide paths)::
+
+      fc-cache -vf ~/.fonts/
+
+After installing the patched font you need to update Gvim or your terminal 
+emulator to use the patched font. The correct font usually ends with *for 
+Powerline*.
+
+If you can't see the custom symbols, please close all instances of your 
+terminal emulator. You may need to restart X for the changes to take
+effect.
+
+If you *still* can't see the custom symbols, double-check that you have 
+installed the font to a valid X font path.

docs/source/installation/osx.rst

@@ -40,3 +40,13 @@ Any terminal vim version with Python 3.2+ or Python 2.6+ support should work,
 but if you're using MacVim you need to install it using the following command::
 
     brew install macvim --env-std --override-system-vim
+
+Fonts installation
+==================
+
+Install downloaded patched font by double-clicking the font file in Finder, then 
+clicking :guilabel:`Install this font` in the preview window.
+
+After installing the patched font you need to update MacVim or your terminal 
+emulator to use the patched font. The correct font usually ends with *for 
+Powerline*.

docs/source/tips-and-tricks.rst

@@ -16,6 +16,8 @@ statusline:
    set laststatus=2 " Always display the statusline in all windows
    set noshowmode " Hide the default mode text (e.g. -- INSERT -- below the statusline)
 
+.. _tips-and-tricks-urxvt:
+
 Rxvt-unicode
 ============
 

docs/source/usage.rst

@@ -21,6 +21,8 @@ packages.
 
 Vim version 7.3.661 or newer is recommended for performance reasons.
 
+.. _usage-terminal-emulators:
+
 Terminal emulator requirements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^