From 50fa8a33ca951db7666fc5df0583e4287895104d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Silkeb=C3=A6kken?= Date: Wed, 19 Dec 2012 14:46:14 +0100 Subject: [PATCH] Update docs and README --- README.rst | 4 +++ docs/source/configuration.rst | 28 ++++++++++++++++ docs/source/fontpatching.rst | 14 +++++--- docs/source/overview.rst | 34 +++++++++++-------- docs/source/troubleshooting.rst | 59 +++++++++++++++++++++++++++++++++ 5 files changed, 121 insertions(+), 18 deletions(-) diff --git a/README.rst b/README.rst index c5404f76..2221ef8d 100644 --- a/README.rst +++ b/README.rst @@ -34,3 +34,7 @@ Screenshots :alt: Truncation illustration * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate3.png :alt: Truncation illustration + +The font in the screenshots is `Pragmata Pro`_ by Fabrizio Schiavi. + +.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 6e79ebdf..f27415e8 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -1,2 +1,30 @@ Configuration ============= + +Powerline is configured with one main configuration file, and with separate +configuration files for themes and colorschemes. All configuration files are +written in JSON, with the excepton of segment definitions, which are written +in Python. + +Powerline provides default configurations in the following locations: + +`Main configuration`_ + ``powerline/config.json`` +`Color scheme`_ + ``powerline/colorschemes/default.json`` +`Theme`_ + ``powerline/themes/{extension}/default.json`` + +The default configuration files are stored in the main package. User +configuration files are stored in ``$XDG_CONFIG_HOME/powerline`` for Linux +users, and in ``~/.config/powerline`` for OS X users. This usually +corresponds to ``~/.config/powerline`` on both platforms. + +Main configuration +------------------ + +Color scheme +------------ + +Theme +----- diff --git a/docs/source/fontpatching.rst b/docs/source/fontpatching.rst index 8b53dedf..513a8b13 100644 --- a/docs/source/fontpatching.rst +++ b/docs/source/fontpatching.rst @@ -1,12 +1,15 @@ -Font patcher -============ +.. _font-patching: + +Font patching +============= 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. -Powerline stores all special glyphs in the Unicode *Private Use Area* -(``U+E000``-``U+F8FF``). +Check out the `powerline-fonts +`_ repository on GitHub for +patched versions of some popular programming fonts. .. warning:: The code points have changed in this version of Powerline! This means that you either have to patch your font again, or change the glyphs @@ -20,6 +23,9 @@ Powerline stores all special glyphs in the Unicode *Private Use Area* Glyph table ----------- +Powerline stores all special glyphs in the Unicode *Private Use Area* +(``U+E000``-``U+F8FF``). + ========== ===== =========== Code point Glyph Description ========== ===== =========== diff --git a/docs/source/overview.rst b/docs/source/overview.rst index b881c9e5..9acde746 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -18,21 +18,26 @@ Vim version 7.3.661 or newer is recommended for performance reasons. Installation ------------ -Powerline is intended to be installed as a system-wide Python package that -can be easily included in other projects. It can be installed by running the -following command as root:: +Installing with ``pip`` +^^^^^^^^^^^^^^^^^^^^^^^ + +To install Powerline system-wide, run the following command as root:: pip install https://github.com/Lokaltog/powerline/tarball/develop -Or, if you use ``easy_install``:: - - easy_install https://github.com/Lokaltog/powerline/tarball/develop +If you don't have root access or don't want to install Powerline +system-wide, install with ``pip install --user`` instead. .. note:: Make sure that you install the package for Python 2. For distros like Arch Linux you'll have to run ``pip2`` instead of ``pip``. -Powerline is available `on the AUR -`_ for Arch Linux users. +Distribution-specific packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following distribution-specific packages are officially supported, and +they provide an easy way of installing and upgrading Powerline: + +* `Arch Linux (AUR) `_ Usage ----- @@ -40,16 +45,17 @@ Usage Vim usage ^^^^^^^^^ -If Powerline is installed as a system-wide Python package, you can enable -the plugin by adding the following line to your ``vimrc``:: +If Powerline is installed as a Python package, you can enable the vim plugin +by adding the following line to your ``vimrc``:: python from powerline.ext.vim import source_plugin; source_plugin() -If Powerline is installed outside Python's search path (e.g. by having the -git repo in your dotfiles folder) you'll have to source the vim plugin file -with an absolute path to the plugin location. +If Powerline is installed somewhere other than Python's site-packages +directories (e.g. by having the git repo in your dotfiles directory) you'll +have to source the vim plugin file with an absolute path to the plugin +location. Add the following line to your ``vimrc``, where ``{path}`` is the path to -the main Powerline project folder:: +the main Powerline project directory:: source {path}/powerline/ext/vim/powerline.vim diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 4edddddf..c153dc3b 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -1,2 +1,61 @@ Troubleshooting =============== + +I can't see any fancy symbols, what's wrong? + Make sure that you've configured gvim or your terminal emulator to use + a patched font (see :ref:`font-patching`). + + Make sure that vim is compiled with the ``--with-features=big`` flag. + + If you're using rxvt-unicode, make sure that it's compiled with the + ``--enable-unicode3`` flag. + + You need to set your ``LANG`` and ``LC_*`` environment variables to + a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's + documentation for information about setting these variables correctly. + +The fancy symbols look a bit blurry or "off"! + Make sure that you have patched all variants of your font (i.e. both the + regular and the bold font files). + +I'm unable to patch my font, what should I do? + Font patching is only known to work on most Linux and OS X machines. If + you have followed the instructions on :ref:`font-patching` and still + have problems, please submit an issue on GitHub. + + You could also check out the `powerline-fonts + `_ repository on GitHub for + patched versions of some popular programming fonts. + +The colors are weird in the default OS X Terminal app! + The default OS X Terminal app is known to have some issues with the + Powerline colors. Please use another terminal emulator. iTerm2 should + work fine. + + The arrows may have the wrong colors if you have changed the "minimum + contrast" slider in the color tab of your OS X settings. + +I'm using tmux and Powerline looks like crap, what's wrong? + You need to tell tmux that it has 256-color capabilities. Add this to + your ``.tmux.conf`` to solve this issue:: + + set -g default-terminal "screen-256color" + + If you use iTerm2, make sure that you have enabled the setting 'Set + locale variables automatically' in Profiles > Terminal > Environment. + +Vim-specific issues +------------------- + +The statusline has strange characters like ``^B`` in it! + Please add ``set encoding=utf-8`` to your ``vimrc``. + +The statusline has a lot of ``^`` or underline characters in it! + You need to configure the ``fillchars`` setting to disable statusline + fillchars (see ``:h fillchars`` for details). Add this to your + ``vimrc`` to solve this issue:: + + set fillchars+=stl:\ ,stlnc:\ + +The statusline is hidden/only appears in split windows! + Make sure that you have ``set laststatus=2`` in your ``vimrc``.