diff --git a/docs/source/fontpatching.rst b/docs/source/fontpatching.rst index b91dd8d2..49062b18 100644 --- a/docs/source/fontpatching.rst +++ b/docs/source/fontpatching.rst @@ -7,6 +7,9 @@ Powerline provides a font patcher for custom glyphs like the segment dividers (arrows), branch symbol, padlock symbol, etc. The font patcher requires FontForge with Python bindings to work. +You may be able to avoid patching your coding font to use the custom glyphs! +See :ref:`font-installation` for instructions. + Check out the `powerline-fonts `_ repository on GitHub for patched versions of some popular programming fonts. diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 64bd3f9e..eefb919d 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -6,6 +6,11 @@ Requirements Powerline requires Python 2.7 to work. +Powerline uses several special glyphs to get the arrow effect and some +custom symbols for developers. This requires that you either have the symbol +font or a patched font on your system. See `Font installation`_ for more +details. + Vim plugin requirements ^^^^^^^^^^^^^^^^^^^^^^^ @@ -48,6 +53,61 @@ they provide an easy way of installing and upgrading Powerline: * `Arch Linux (AUR) `_ +.. _font-installation: + +Font installation +^^^^^^^^^^^^^^^^^ + +Linux +***** + +If you're running Linux, you may be able to avoid patching your coding font +to get the special glyphs required by Powerline. This works by utilizing +fontconfig's fallback font feature, which replaces missing glyphs in a font +with another font on your system. + +This has been tested and works very well with many different coding fonts, +but some fonts may look terrible, in which case you'll have to use a patched +font (see :ref:`font-patching` for details). + +1. Download the `latest version of PowerlineSymbols + `_. +2. Move :file:`PowerlineSymbols.otf` to :file:`~/.fonts`. +3. Run ``fc-cache -vf ~/.fonts`` to update your font cache. +4. Edit your fontconfig file, located in either :file:`~/.fonts.conf` or + :file:`~/.config/fontconfig/fonts.conf`, depending on your fontconfig + version. If your fontconfig file is empty, add the entire code block + below. If you already have a custom font configuration, only add the + ```` block to your font configuration: + + .. code-block:: xml + + + + + + + monospace + + PowerlineSymbols + YOUR MONOSPACE FONT HERE + + + + + Remember to replace ``YOUR MONOSPACE FONT HERE`` with your preferred + coding font. +5. Configure your terminal emulator or gvim to use the ``monospace`` font. +6. If you still don't see the arrow symbols, please close all instances of + your terminal emulator or gvim. You may also have to restart X for the + changes to take effect. + +OS X and Windows +**************** + +You'll have to use a patched font to use the Powerline symbols. See +:ref:`font-patching` for details on font patching and pre-patched fonts. + Usage -----