Restructure and improve installation docs
The installation docs have been split into separate guides for OS X and Linux, with OS-specific troubleshooting as part of the installation guide. Terminal emulator support tables have been added to both guides. Closes #121.
This commit is contained in:
Kim Silkebækken
parent
a87309899f
commit
6ac9f0d602
Binary file not shown.
|
After Width: | Height: | Size: 473 B |
Binary file not shown.
|
After Width: | Height: | Size: 543 B |
Binary file not shown.
|
After Width: | Height: | Size: 451 B |
|
|
@ -8,9 +8,8 @@ Powerline
|
|||
|
||||
introduction
|
||||
overview
|
||||
fontpatching
|
||||
configuration
|
||||
troubleshooting
|
||||
fontpatching
|
||||
license-credits
|
||||
|
||||
Indices and tables
|
||||
|
|
|
|||
|
|
@ -0,0 +1,125 @@
|
|||
:tocdepth: 2
|
||||
|
||||
.. _installation-linux:
|
||||
|
||||
*********************
|
||||
Installation on Linux
|
||||
*********************
|
||||
|
||||
The following distribution-specific packages are officially supported, and
|
||||
they provide an easy way of installing and upgrading Powerline. The packages
|
||||
will automatically do most of the configuration for you, but you should
|
||||
still skim through this guide so you know how the plugin works.
|
||||
|
||||
* `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_
|
||||
* `Arch Linux (AUR), Python 3 version <https://aur.archlinux.org/packages/python-powerline-git/>`_
|
||||
* Gentoo Live ebuild (:file:`packages/gentoo/app-misc/powerline/`)
|
||||
|
||||
If you're running a distribution without an official package you'll have to
|
||||
follow the installation guide below:
|
||||
|
||||
Plugin installation
|
||||
===================
|
||||
|
||||
1. Install Python 3.3+ or Python 2.7.
|
||||
2. Install Powerline using the following command::
|
||||
|
||||
pip install --user git+git://github.com/Lokaltog/powerline
|
||||
|
||||
.. note:: You need to use the GitHub URI when installing Powerline! This
|
||||
project is currently unavailable on the PyPI due to a naming conflict
|
||||
with an unrelated project.
|
||||
|
||||
.. warning:: Installing Powerline with a vim plugin manager like Vundle is
|
||||
not recommended and not officially supported.
|
||||
|
||||
Font installation
|
||||
=================
|
||||
|
||||
================== ============================= ======================
|
||||
Application/terminal emulator font support table
|
||||
-----------------------------------------------------------------------
|
||||
Name Patched font support Fontconfig support
|
||||
================== ============================= ======================
|
||||
Gnome Terminal |supp_yes| |supp_yes|
|
||||
Gvim |supp_yes| |supp_no|
|
||||
Konsole |supp_yes| |supp_yes|
|
||||
lxterminal |supp_yes| |supp_yes|
|
||||
rxvt-unicode |supp_partial| [#]_ |supp_no|
|
||||
st |supp_yes| |supp_yes|
|
||||
Xfce Terminal |supp_yes| |supp_yes|
|
||||
xterm |supp_yes| |supp_no|
|
||||
================== ============================= ======================
|
||||
|
||||
.. |supp_yes| image:: ../_static/img/icons/tick.png
|
||||
.. |supp_no| image:: ../_static/img/icons/cross.png
|
||||
.. |supp_partial| image:: ../_static/img/icons/error.png
|
||||
|
||||
.. [#] Must be compiled with ``--enable-unicode3`` for the
|
||||
patched font to work.
|
||||
|
||||
Powerline provides two ways of installing the required fonts on Linux. The
|
||||
recommended method is using ``fontconfig`` if your terminal emulator
|
||||
supports it (see the table above).
|
||||
|
||||
Fontconfig
|
||||
----------
|
||||
|
||||
1. Download the `latest version of PowerlineSymbols
|
||||
<https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf>`_
|
||||
and the `latest version of the fontconfig file
|
||||
<https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf>`_.
|
||||
2. Move :file:`PowerlineSymbols.otf` to :file:`~/.fonts/` (or another X font
|
||||
directory).
|
||||
3. Run ``fc-cache -vf ~/.fonts`` to update your font cache.
|
||||
4. Move :file:`10-powerline-symbols.conf` to either :file:`~/.fonts.conf.d/`
|
||||
or :file:`~/.config/fontconfig/conf.d/`, depending on your fontconfig
|
||||
version.
|
||||
5. If you 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. If you *still* don't see the arrow symbols, please submit
|
||||
an issue on GitHub.
|
||||
|
||||
Patched font
|
||||
------------
|
||||
|
||||
1. 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. See :ref:`font-patching` for instructions.
|
||||
2. Move your patched font to :file:`~/.fonts/` (or another X font
|
||||
directory).
|
||||
3. Run ``fc-cache -vf ~/.fonts`` to update your font cache.
|
||||
4. Update Gvim or your terminal emulator to use the patched font. (the
|
||||
correct font usually ends with *for Powerline*).
|
||||
5. If you 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. If you *still* don't see the arrow symbols, please submit
|
||||
an issue on GitHub.
|
||||
|
||||
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
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`).
|
||||
* 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.
|
||||
* 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.
|
||||
|
||||
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).
|
||||
|
||||
.. include:: troubleshooting-common.rst
|
||||
|
|
@ -0,0 +1,129 @@
|
|||
:tocdepth: 2
|
||||
|
||||
.. _installation-osx:
|
||||
|
||||
********************
|
||||
Installation on OS X
|
||||
********************
|
||||
|
||||
Plugin installation
|
||||
===================
|
||||
|
||||
Python package
|
||||
--------------
|
||||
|
||||
1. Install a proper Python version (see `issue #39
|
||||
<https://github.com/Lokaltog/powerline/issues/39>`_ for a discussion
|
||||
regarding the required Python version on OS X)::
|
||||
|
||||
sudo port select python python27-apple
|
||||
|
||||
2. Install Powerline using the following command::
|
||||
|
||||
pip install --user git+git://github.com/Lokaltog/powerline
|
||||
|
||||
.. note:: You need to use the GitHub URI when installing Powerline! This
|
||||
project is currently unavailable on the PyPI due to a naming conflict
|
||||
with an unrelated project.
|
||||
|
||||
.. warning:: Installing Powerline with a vim plugin manager like Vundle is
|
||||
not recommended and not officially supported.
|
||||
|
||||
Vim installation
|
||||
----------------
|
||||
|
||||
Any terminal vim version with Python 3.3 or Python 2.7 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
|
||||
|
||||
Font installation
|
||||
=================
|
||||
|
||||
================== =============================
|
||||
Application/terminal emulator font support table
|
||||
------------------------------------------------
|
||||
Name Patched font support
|
||||
================== =============================
|
||||
iTerm2 |supp_yes|
|
||||
Terminal.app |supp_yes|
|
||||
================== =============================
|
||||
|
||||
.. |supp_yes| image:: ../_static/img/icons/tick.png
|
||||
.. |supp_no| image:: ../_static/img/icons/cross.png
|
||||
.. |supp_partial| image:: ../_static/img/icons/error.png
|
||||
|
||||
.. note:: You need a patched font for Powerline to work on OS X. Check out
|
||||
the `powerline-fonts`_ repository on GitHub for patched versions of some
|
||||
popular programming fonts.
|
||||
|
||||
1. Download the font of your choice and install it by double-clicking the
|
||||
font file in Finder and then click :guilabel:`Install this font` in the
|
||||
preview window.
|
||||
|
||||
If you can't find your preferred font in the `powerline-fonts`_ repo,
|
||||
you'll have to patch your own font instead. See :ref:`font-patching` for
|
||||
instructions.
|
||||
2. Configure MacVim or your terminal emulator to use the patched font (the
|
||||
correct font usually ends with *for Powerline*).
|
||||
|
||||
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
|
||||
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
I can't see any fancy symbols, what's wrong?
|
||||
--------------------------------------------
|
||||
|
||||
* If you're using iTerm2, please update to `this revision
|
||||
<https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_
|
||||
or newer.
|
||||
* 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 colors look weird in the default OS X Terminal app!
|
||||
-------------------------------------------------------
|
||||
|
||||
* The arrows may have the wrong colors if you have changed the "minimum
|
||||
contrast" slider in the color tab of your OS X settings.
|
||||
* 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 colors look weird in iTerm2!
|
||||
--------------------------------
|
||||
|
||||
* The arrows may have the wrong colors if you have changed the "minimum
|
||||
contrast" slider in the color tab of your OS X settings.
|
||||
* Please disable background transparency to resolve this issue.
|
||||
|
||||
I receive a ``NameError`` when trying to use Powerline with MacVim!
|
||||
-------------------------------------------------------------------
|
||||
|
||||
* Please install MacVim using this command::
|
||||
|
||||
brew install macvim --env-std --override-system-vim
|
||||
|
||||
Then install Powerline locally with ``pip install --user``, or by
|
||||
running these commands in the ``powerline`` directory::
|
||||
|
||||
./setup.py build
|
||||
./setup.py install --user
|
||||
|
||||
I receive an ``ImportError`` when trying to use Powerline on OS X!
|
||||
------------------------------------------------------------------
|
||||
|
||||
* This is caused by an invalid ``sys.path`` when using system vim and system
|
||||
Python. Please try to select another Python distribution::
|
||||
|
||||
sudo port select python python27-apple
|
||||
|
||||
* See `issue #39 <https://github.com/Lokaltog/powerline/issues/39>`_ for
|
||||
a discussion and other possible solutions for this issue.
|
||||
|
||||
.. include:: troubleshooting-common.rst
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
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
|
||||
:file:`.tmux.conf` to solve this issue::
|
||||
|
||||
set -g default-terminal "screen-256color"
|
||||
|
||||
* If you're using iTerm2, make sure that you have enabled the setting
|
||||
:guilabel:`Set locale variables automatically` in :menuselection:`Profiles
|
||||
--> Terminal --> Environment`.
|
||||
|
||||
My vim statusline has strange characters like ``^B`` in it!
|
||||
-----------------------------------------------------------
|
||||
|
||||
* Please add ``set encoding=utf-8`` to your :file:`vimrc`.
|
||||
|
||||
My vim 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
|
||||
:file:`vimrc` to solve this issue:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
set fillchars+=stl:\ ,stlnc:\
|
||||
|
||||
My vim statusline is hidden/only appears in split windows!
|
||||
----------------------------------------------------------
|
||||
|
||||
* Make sure that you have ``set laststatus=2`` in your :file:`vimrc`.
|
||||
|
|
@ -9,8 +9,8 @@ Powerline requires Python 3.3 or 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.
|
||||
font or a patched font on your system (details in installation
|
||||
instructions).
|
||||
|
||||
Vim plugin requirements
|
||||
-----------------------
|
||||
|
|
@ -41,82 +41,16 @@ recommended for optimal performance and extra features:
|
|||
Installation
|
||||
============
|
||||
|
||||
Installing with ``pip``
|
||||
-----------------------
|
||||
|
||||
To install Powerline system-wide, run the following command as root::
|
||||
|
||||
pip install git+git://github.com/Lokaltog/powerline
|
||||
|
||||
If you don't have root access or don't want to install Powerline
|
||||
system-wide, install with ``pip install --user`` instead.
|
||||
|
||||
.. note:: This project is currently unavailable on the PyPI due to a naming
|
||||
conflict with an unrelated project.
|
||||
|
||||
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/>`_
|
||||
* Gentoo Live ebuild (:file:`packages/gentoo/app-misc/powerline/`)
|
||||
|
||||
.. _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
|
||||
<https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf>`_
|
||||
and the `latest version of the fontconfig file
|
||||
<https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf>`_.
|
||||
2. Move :file:`PowerlineSymbols.otf` to :file:`~/.fonts/`.
|
||||
3. Run ``fc-cache -vf ~/.fonts`` to update your font cache.
|
||||
4. Move :file:`10-powerline-symbols.conf` to either :file:`~/.fonts.conf.d/`
|
||||
or :file:`~/.config/fontconfig/conf.d/`, depending on your fontconfig
|
||||
version.
|
||||
5. If you 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. If you *still* don't see the arrow symbols, please submit
|
||||
an issue on GitHub.
|
||||
|
||||
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.
|
||||
* :ref:`installation-linux`
|
||||
* :ref:`installation-osx`
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
.. note:: 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 use the absolute path to the scripts in the
|
||||
examples below.
|
||||
|
||||
Vim statusline
|
||||
--------------
|
||||
|
||||
Regular installation
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
**The recommended way of installing Powerline is as a Python package.**
|
||||
You can then enable the vim plugin by adding the following line to your
|
||||
:file:`vimrc`:
|
||||
Add the following line to your :file:`vimrc`:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
|
|
@ -137,15 +71,6 @@ to the main Powerline project directory:
|
|||
|
||||
source {path}/powerline/bindings/vim/plugin/source_plugin.vim
|
||||
|
||||
Vundle installation
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you're using Vundle you can add the following line to your :file:`vimrc`:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
Bundle 'Lokaltog/powerline', {'rtp': 'powerline/bindings/vim/'}
|
||||
|
||||
Shell prompts
|
||||
-------------
|
||||
|
||||
|
|
|
|||
|
|
@ -1,133 +0,0 @@
|
|||
:tocdepth: 2
|
||||
|
||||
***************
|
||||
Troubleshooting
|
||||
***************
|
||||
|
||||
.. contents::
|
||||
|
||||
General issues
|
||||
==============
|
||||
|
||||
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.
|
||||
|
||||
If you're using iTerm2, please update to `this revision
|
||||
<https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_
|
||||
or newer.
|
||||
|
||||
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 look 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.
|
||||
|
||||
The colors look weird in iTerm2!
|
||||
--------------------------------
|
||||
|
||||
Please disable background transparency to resolve this issue.
|
||||
|
||||
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
|
||||
:file:`.tmux.conf` to solve this issue::
|
||||
|
||||
set -g default-terminal "screen-256color"
|
||||
|
||||
If you use iTerm2, make sure that you have enabled the setting
|
||||
:guilabel:`Set locale variables automatically` in :menuselection:`Profiles
|
||||
--> Terminal --> Environment`.
|
||||
|
||||
I'm using PuTTY and I get huge gaps around the arrow glyphs!
|
||||
------------------------------------------------------------
|
||||
|
||||
Please uncheck :guilabel:`Treat CJK ambiguous characters as wide` in
|
||||
:menuselection:`Window --> Translation`.
|
||||
|
||||
Vim-specific issues
|
||||
===================
|
||||
|
||||
The statusline has strange characters like ``^B`` in it!
|
||||
--------------------------------------------------------
|
||||
|
||||
Please add ``set encoding=utf-8`` to your :file:`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 :file:`vimrc`
|
||||
to solve this issue:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
set fillchars+=stl:\ ,stlnc:\
|
||||
|
||||
The statusline is hidden/only appears in split windows!
|
||||
-------------------------------------------------------
|
||||
|
||||
Make sure that you have ``set laststatus=2`` in your :file:`vimrc`.
|
||||
|
||||
I'm using gVim for Windows, and ``cmd`` windows keep popping up when working in git repos!
|
||||
------------------------------------------------------------------------------------------
|
||||
|
||||
Either install ``libgit2`` and ``pygit2``, or disable the VCS segment in
|
||||
your user configuration to resolve this issue.
|
||||
|
||||
I receive a ``NameError`` when trying to use Powerline with MacVim!
|
||||
-------------------------------------------------------------------
|
||||
|
||||
Please install MacVim using this command::
|
||||
|
||||
brew install macvim --env-std --override-system-vim
|
||||
|
||||
Then install Powerline locally with ``pip install --user``, or by
|
||||
running these commands in the ``powerline`` directory::
|
||||
|
||||
./setup.py build
|
||||
./setup.py install --user
|
||||
|
||||
I receive an ``ImportError`` when trying to use Powerline on OS X!
|
||||
------------------------------------------------------------------
|
||||
|
||||
This is caused by an invalid ``sys.path`` when using system vim and system
|
||||
Python. Please try to select another Python distribution::
|
||||
|
||||
sudo port select python python27-apple
|
||||
|
||||
See the `issue #39 <https://github.com/Lokaltog/powerline/issues/39>`_
|
||||
for a discussion and other possible solutions for this issue.
|
||||
Loading…
Reference in New Issue