Update docs and README
This commit is contained in:
parent
69f726af1a
commit
50fa8a33ca
|
@ -34,3 +34,7 @@ Screenshots
|
||||||
:alt: Truncation illustration
|
:alt: Truncation illustration
|
||||||
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate3.png
|
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate3.png
|
||||||
:alt: Truncation illustration
|
: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
|
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
|
Powerline provides a font patcher for custom glyphs like the segment
|
||||||
dividers (arrows), branch symbol, padlock symbol, etc. The font patcher
|
dividers (arrows), branch symbol, padlock symbol, etc. The font patcher
|
||||||
requires FontForge with Python bindings to work.
|
requires FontForge with Python bindings to work.
|
||||||
|
|
||||||
Powerline stores all special glyphs in the Unicode *Private Use Area*
|
Check out the `powerline-fonts
|
||||||
(``U+E000``-``U+F8FF``).
|
<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
|
.. 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
|
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
|
Glyph table
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
|
Powerline stores all special glyphs in the Unicode *Private Use Area*
|
||||||
|
(``U+E000``-``U+F8FF``).
|
||||||
|
|
||||||
========== ===== ===========
|
========== ===== ===========
|
||||||
Code point Glyph Description
|
Code point Glyph Description
|
||||||
========== ===== ===========
|
========== ===== ===========
|
||||||
|
|
|
@ -18,21 +18,26 @@ Vim version 7.3.661 or newer is recommended for performance reasons.
|
||||||
Installation
|
Installation
|
||||||
------------
|
------------
|
||||||
|
|
||||||
Powerline is intended to be installed as a system-wide Python package that
|
Installing with ``pip``
|
||||||
can be easily included in other projects. It can be installed by running the
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
following command as root::
|
|
||||||
|
To install Powerline system-wide, run the following command as root::
|
||||||
|
|
||||||
pip install https://github.com/Lokaltog/powerline/tarball/develop
|
pip install https://github.com/Lokaltog/powerline/tarball/develop
|
||||||
|
|
||||||
Or, if you use ``easy_install``::
|
If you don't have root access or don't want to install Powerline
|
||||||
|
system-wide, install with ``pip install --user`` instead.
|
||||||
easy_install https://github.com/Lokaltog/powerline/tarball/develop
|
|
||||||
|
|
||||||
.. note:: Make sure that you install the package for Python 2. For distros
|
.. 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``.
|
like Arch Linux you'll have to run ``pip2`` instead of ``pip``.
|
||||||
|
|
||||||
Powerline is available `on the AUR
|
Distribution-specific packages
|
||||||
<https://aur.archlinux.org/packages/powerline-git/>`_ for Arch Linux users.
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
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
|
Usage
|
||||||
-----
|
-----
|
||||||
|
@ -40,16 +45,17 @@ Usage
|
||||||
Vim usage
|
Vim usage
|
||||||
^^^^^^^^^
|
^^^^^^^^^
|
||||||
|
|
||||||
If Powerline is installed as a system-wide Python package, you can enable
|
If Powerline is installed as a Python package, you can enable the vim plugin
|
||||||
the plugin by adding the following line to your ``vimrc``::
|
by adding the following line to your ``vimrc``::
|
||||||
|
|
||||||
python from powerline.ext.vim import source_plugin; source_plugin()
|
python from powerline.ext.vim import source_plugin; source_plugin()
|
||||||
|
|
||||||
If Powerline is installed outside Python's search path (e.g. by having the
|
If Powerline is installed somewhere other than Python's site-packages
|
||||||
git repo in your dotfiles folder) you'll have to source the vim plugin file
|
directories (e.g. by having the git repo in your dotfiles directory) you'll
|
||||||
with an absolute path to the plugin location.
|
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
|
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
|
source {path}/powerline/ext/vim/powerline.vim
|
||||||
|
|
|
@ -1,2 +1,61 @@
|
||||||
Troubleshooting
|
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