Restructure docs slightly
The header levels have been switched to correspond more with the Sphinx suggested standards and the troubleshooting section has been restructured to make it easier to find solutions. Minor markup changes and other changes are also included in this commit.
This commit is contained in:
Kim Silkebækken
parent
40d542af12
commit
b86f79cf9e
|
|
@ -1,5 +1,6 @@
|
|||
*************
|
||||
Configuration
|
||||
=============
|
||||
*************
|
||||
|
||||
Powerline is configured with one main configuration file, and with separate
|
||||
configuration files for themes and colorschemes. All configuration files are
|
||||
|
|
@ -37,7 +38,7 @@ file. Example:
|
|||
colorscheme/theme!
|
||||
|
||||
Main configuration
|
||||
------------------
|
||||
==================
|
||||
|
||||
:Location: :file:`powerline/config.json`
|
||||
|
||||
|
|
@ -46,7 +47,7 @@ extensions, as well as some extension-specific options like themes and
|
|||
colorschemes.
|
||||
|
||||
Common configuration
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
--------------------
|
||||
|
||||
Common configuration is a subdictionary that is a value of ``common`` key in
|
||||
:file:`powerline/config.json` file.
|
||||
|
|
@ -68,7 +69,7 @@ Common configuration is a subdictionary that is a value of ``common`` key in
|
|||
have priority when searching for modules.
|
||||
|
||||
Extension-specific configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
--------------------------------
|
||||
|
||||
Common configuration is a subdictionary that is a value of ``ext`` key in
|
||||
:file:`powerline/config.json` file.
|
||||
|
|
@ -84,7 +85,7 @@ Common configuration is a subdictionary that is a value of ``ext`` key in
|
|||
buffer-specific statuslines in vim. Requires a custom matcher and theme.
|
||||
|
||||
Colorschemes
|
||||
------------
|
||||
============
|
||||
|
||||
:Location: :file:`powerline/colorschemes/{extension}/{name}.json`
|
||||
|
||||
|
|
@ -139,7 +140,7 @@ Colorschemes
|
|||
:ref:`groups <config-colorscheme-groups>` option.
|
||||
|
||||
Themes
|
||||
------
|
||||
======
|
||||
|
||||
:Location: :file:`powerline/themes/{extension}/{name}.json`
|
||||
|
||||
|
|
@ -243,7 +244,7 @@ Themes
|
|||
*not* included in any modes, *except* for the modes in this list.
|
||||
|
||||
Segments
|
||||
--------
|
||||
========
|
||||
|
||||
Segments are written in Python, and the default segments provided with
|
||||
Powerline are located in :file:`powerline/segments/{extension}.py`.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
.. _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
|
||||
|
|
@ -24,7 +25,7 @@ patched versions of some popular programming fonts.
|
|||
configuration.
|
||||
|
||||
Glyph table
|
||||
-----------
|
||||
===========
|
||||
|
||||
Powerline stores all special glyphs in the Unicode *Private Use Area*
|
||||
(``U+E000``-``U+F8FF``).
|
||||
|
|
@ -42,7 +43,7 @@ Code point Glyph Description
|
|||
========== ===== ===========
|
||||
|
||||
Usage
|
||||
-----
|
||||
=====
|
||||
|
||||
The font patcher is located at :file:`powerline/fontpatcher/fontpatcher.py`.
|
||||
It requires Python 2.7 and FontForge compiled with Python bindings to work.
|
||||
|
|
@ -57,7 +58,7 @@ option to disable font renaming.
|
|||
the glyphs manually using a tool like ``gbdfed``.
|
||||
|
||||
Linux
|
||||
^^^^^
|
||||
-----
|
||||
|
||||
1. Install fontforge with Python bindings. For Ubuntu users the required
|
||||
package is ``python-fontforge``, for Arch Linux users the required
|
||||
|
|
@ -89,7 +90,7 @@ Linux
|
|||
6. Open vim and enjoy your new statusline!
|
||||
|
||||
OS X
|
||||
^^^^
|
||||
----
|
||||
|
||||
1. Check if you have a FontForge version with Python support by running
|
||||
``fontforge -version``. You should see something like this::
|
||||
|
|
|
|||
|
|
@ -1,8 +1,9 @@
|
|||
*********
|
||||
Powerline
|
||||
=========
|
||||
*********
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:maxdepth: 2
|
||||
:glob:
|
||||
|
||||
introduction
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
************
|
||||
Introduction
|
||||
============
|
||||
************
|
||||
|
||||
This is the next version of Powerline, implemented in Python. It aims to
|
||||
resolve some of the "unresolvable" problems of the vimscript implementation,
|
||||
|
|
@ -10,7 +11,7 @@ The project is currently in beta, and most of the functionality in the old
|
|||
vimscript project is already implemented.
|
||||
|
||||
Screenshots
|
||||
-----------
|
||||
===========
|
||||
|
||||
**Mode-dependent highlighting**
|
||||
|
||||
|
|
@ -37,7 +38,7 @@ The font in the screenshots is `Pragmata Pro`_ by Fabrizio Schiavi.
|
|||
.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm
|
||||
|
||||
Feature highlights
|
||||
------------------
|
||||
==================
|
||||
|
||||
* **Better performance.** Python performs quite a bit better than vimscript,
|
||||
and by having most of the code in Python instead of vimscript it's also
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
*******************
|
||||
License and credits
|
||||
*******************
|
||||
|
||||
License
|
||||
=======
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,9 @@
|
|||
********
|
||||
Overview
|
||||
========
|
||||
********
|
||||
|
||||
Requirements
|
||||
------------
|
||||
============
|
||||
|
||||
Powerline requires Python 3.3 or Python 2.7 to work.
|
||||
|
||||
|
|
@ -12,15 +13,15 @@ font or a patched font on your system. See `Font installation`_ for more
|
|||
details.
|
||||
|
||||
Vim plugin requirements
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
-----------------------
|
||||
|
||||
The vim plugin requires a vim version with Python support compiled in. You
|
||||
can check if your vim supports Python by running ``vim --version | grep
|
||||
+python``.
|
||||
|
||||
If your vim version doesn't have support for Python, you'll have to compile
|
||||
it with the ``--enable-python3interp`` flag (``--enable-pythoninterp`` if
|
||||
you want Python 2 support instead). Note that this also requires the related
|
||||
it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if
|
||||
you want Python 3 support instead). Note that this also requires the related
|
||||
Python headers to be installed on your system. Please consult your
|
||||
distribution's documentation for details on how to compile and install
|
||||
packages.
|
||||
|
|
@ -28,20 +29,20 @@ packages.
|
|||
Vim version 7.3.661 or newer is recommended for performance reasons.
|
||||
|
||||
Optional dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
---------------------
|
||||
|
||||
The following Python packages are not required by all segments, but
|
||||
recommended for optimal performance:
|
||||
recommended for optimal performance and extra features:
|
||||
|
||||
* ``pygit2``
|
||||
* ``mercurial``
|
||||
* ``psutil``
|
||||
|
||||
Installation
|
||||
------------
|
||||
============
|
||||
|
||||
Installing with ``pip``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
-----------------------
|
||||
|
||||
To install Powerline system-wide, run the following command as root::
|
||||
|
||||
|
|
@ -54,7 +55,7 @@ system-wide, install with ``pip install --user`` instead.
|
|||
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:
|
||||
|
|
@ -65,10 +66,10 @@ they provide an easy way of installing and upgrading 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
|
||||
|
|
@ -94,13 +95,13 @@ font (see :ref:`font-patching` for details).
|
|||
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.
|
||||
|
||||
Usage
|
||||
-----
|
||||
=====
|
||||
|
||||
.. note:: If Powerline is installed somewhere other than Python's
|
||||
site-packages directories (e.g. by having the git repo in your dotfiles
|
||||
|
|
@ -108,14 +109,14 @@ Usage
|
|||
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
|
||||
``vimrc``:
|
||||
:file:`vimrc`:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
|
|
@ -129,40 +130,40 @@ If Powerline is installed somewhere other than Python's site-packages
|
|||
directories you'll either have to use a plugin manager like Vundle, or
|
||||
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 directory:
|
||||
Add the following line to your :file:`vimrc`, where ``{path}`` is the path
|
||||
to the main Powerline project directory:
|
||||
|
||||
.. code-block:: vim
|
||||
|
||||
source {path}/powerline/bindings/vim/plugin/source_plugin.vim
|
||||
|
||||
Vundle installation
|
||||
*******************
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you're using Vundle you can add the following line to your ``vimrc``:
|
||||
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
|
||||
^^^^^^^^^^^^^
|
||||
-------------
|
||||
|
||||
Bash prompt
|
||||
***********
|
||||
^^^^^^^^^^^
|
||||
|
||||
Add the following line to your ``.bashrc``, where ``{path}`` is the absolute
|
||||
path to your Powerline installation directory:
|
||||
Add the following line to your :file:`bashrc`, where ``{path}`` is the
|
||||
absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. {path}/powerline/bindings/bash/powerline.sh
|
||||
|
||||
Zsh prompt
|
||||
**********
|
||||
^^^^^^^^^^
|
||||
|
||||
Add the following line to your ``.zshrc``, where ``{path}`` is the absolute
|
||||
path to your Powerline installation directory:
|
||||
Add the following line to your :file:`zshrc`, where ``{path}`` is the
|
||||
absolute path to your Powerline installation directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -171,7 +172,7 @@ path to your Powerline installation directory:
|
|||
Tmux statusline
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Add the following line to your ``.tmux.conf``, where ``{path}`` is the
|
||||
Add the following line to your :file:`tmux.conf`, where ``{path}`` is the
|
||||
absolute path to your Powerline installation directory::
|
||||
|
||||
source '{path}/powerline/bindings/tmux/powerline.conf'
|
||||
|
|
|
|||
|
|
@ -1,96 +1,133 @@
|
|||
: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.
|
||||
Make sure that you've configured gvim or your terminal emulator to use
|
||||
a patched font (see :ref:`font-patching`).
|
||||
|
||||
If you're using rxvt-unicode, make sure that it's compiled with the
|
||||
``--enable-unicode3`` flag.
|
||||
Make sure that vim is compiled with the ``--with-features=big`` flag.
|
||||
|
||||
If you're using iTerm2, please update to `this revision
|
||||
<https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_
|
||||
or newer.
|
||||
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.
|
||||
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).
|
||||
---------------------------------------------
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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 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 the default OS X Terminal app!
|
||||
-------------------------------------------------------
|
||||
|
||||
The colors are weird in iTerm2!
|
||||
Please disable background transparency to resolve this issue.
|
||||
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::
|
||||
-----------------------------------------------------------
|
||||
|
||||
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 'Set
|
||||
locale variables automatically' in Profiles > Terminal > Environment.
|
||||
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`.
|
||||
------------------------------------------------------------
|
||||
|
||||
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`.
|
||||
--------------------------------------------------------
|
||||
|
||||
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::
|
||||
----------------------------------------------------------------
|
||||
|
||||
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`.
|
||||
-------------------------------------------------------
|
||||
|
||||
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.
|
||||
------------------------------------------------------------------------------------------
|
||||
|
||||
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::
|
||||
-------------------------------------------------------------------
|
||||
|
||||
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::
|
||||
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::
|
||||
------------------------------------------------------------------
|
||||
|
||||
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.
|
||||
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