From 74d19b4f52244ea6b13cfa8434c35772214a411f Mon Sep 17 00:00:00 2001 From: ZyX Date: Sun, 3 Aug 2014 02:43:13 +0400 Subject: [PATCH] Add font installation instructions --- docs/source/installation.rst | 32 +++++++++++++++ docs/source/installation/linux.rst | 66 ++++++++++++++++++++++++++++++ docs/source/installation/osx.rst | 10 +++++ docs/source/tips-and-tricks.rst | 2 + docs/source/usage.rst | 2 + 5 files changed, 112 insertions(+) diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 25f592b0..ab4fe6e8 100644 --- a/docs/source/installation.rst +++ b/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 ` +if your terminal emulator supports it (see :ref:`the terminal emulator support +matrix `). + +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 `. + +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 ================================= diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst index f4df8f40..5f8cd6d7 100644 --- a/docs/source/installation/linux.rst +++ b/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 `. + +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. diff --git a/docs/source/installation/osx.rst b/docs/source/installation/osx.rst index e2e1c9b8..204666a7 100644 --- a/docs/source/installation/osx.rst +++ b/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*. diff --git a/docs/source/tips-and-tricks.rst b/docs/source/tips-and-tricks.rst index 85713038..9961b8eb 100644 --- a/docs/source/tips-and-tricks.rst +++ b/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 ============ diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 0bf33b35..ccaa8925 100644 --- a/docs/source/usage.rst +++ b/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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^