Update docs and README
This commit is contained in:
Kim Silkebækken
parent
69f726af1a
commit
50fa8a33ca
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
-----
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<https://github.com/Lokaltog/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
|
||||
========== ===== ===========
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<https://aur.archlinux.org/packages/powerline-git/>`_ 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) <https://aur.archlinux.org/packages/powerline-git/>`_
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<https://github.com/Lokaltog/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``.
|
||||
|
|
|
|||
Loading…
Reference in New Issue