tyler.durden
/
powerline
mirror of https://github.com/powerline/powerline.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove old docs and update documentation structure 

Most of the files are empty and need to be copied or rewritten from the
old docs. Font patching docs have been removed entirely and will be
moved to the powerline-fontpatcher repo.

Ref #769
This commit is contained in:
Kim Silkebækken 2014-01-25 16:19:47 +01:00 committed by ZyX
parent ecb3b690db
commit c2379df50a
25 changed files with 175 additions and 1689 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/source/configuration-and-customization.rst Normal file
View File

@ -0,0 +1,15 @@
*******************************
Configuration and customization
*******************************
Quick setup guide
-----------------
References
----------
.. toctree::
:glob:
configuration-reference
segment-reference

3
docs/source/configuration-reference.rst Normal file
View File

@ -0,0 +1,3 @@
***********************
Configuration reference
***********************

636
docs/source/configuration.rst
View File

@ -1,636 +0,0 @@
*************
Configuration
*************
.. note:: **You DO NOT have to fork the main GitHub repo to personalize your
Powerline configuration!** Please read through the :ref:`quick-guide` for
a quick introduction to user 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 exception of segment definitions, which are
written in Python.
Powerline provides default configurations in the following locations:
`Main configuration`_
:file:`powerline/config.json`
`Colorschemes`_
:file:`powerline/colorschemes/{name}.json`,
:file:`powerline/colorscheme/__main__.json`,
:file:`powerline/colorschemes/{extension}/{name}.json`
`Themes`_
:file:`powerline/themes/{extension}/default.json`
The default configuration files are stored in the main package. User
configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for
Linux users, and in :file:`~/.config/powerline` for OS X users. This usually
corresponds to :file:`~/.config/powerline` on both platforms.
.. _quick-guide:
Quick setup guide
=================
This guide will help you with the initial configuration of Powerline.
Start by copying the entire set of default configuration files to the
corresponding path in your user config directory:
.. code-block:: sh
mkdir ~/.config/powerline
cp -R /path/to/powerline/config_files/* ~/.config/powerline
Each extension (vim, tmux, etc.) has its own theme, and they are located in
:file:`{config directory}/themes/{extension}/default.json`.
If you want to move, remove or customize any of the provided segments, you
can do that by updating the segment dictionary in the theme you want to
customize. A segment dictionary looks like this:
.. code-block:: javascript
{
"name": "segment_name"
...
}
You can move the segment dictionaries around to change the segment
positions, or remove the entire dictionary to remove the segment from the
prompt or statusline.
.. note:: It's essential that the contents of all your configuration files
is valid JSON! It's strongly recommended that you run your configuration
files through ``jsonlint`` after changing them.
Some segments need a user configuration to work properly. Here's a couple of
segments that you may want to customize right away:
**E-mail alert segment**
You have to set your username and password (and possibly server/port)
for the e-mail alert segment. If you're using GMail it's recommended
that you `generate an application-specific password
<https://accounts.google.com/IssuedAuthSubTokens>`_ for this purpose.
Open a theme file, scroll down to the ``email_imap_alert`` segment and
set your ``username`` and ``password``. The server defaults to GMail's
IMAP server, but you can set the server/port by adding a ``server`` and
a ``port`` argument.
**Weather segment**
The weather segment will try to find your location using a GeoIP lookup,
so unless you're on a VPN you probably won't have to change the location
query.
If you want to change the location query or the temperature unit you'll
have to update the segment arguments. Open a theme file, scroll down to
the weather segment and update it to include unit/location query
arguments:
.. code-block:: javascript
{
"name": "weather",
"priority": 50,
"args": {
"unit": "F",
"location_query": "oslo, norway"
}
},
.. _config-main:
Main configuration
==================
:Location: :file:`powerline/config.json`
The main configuration file defines some common options that applies to all
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.
.. _config-common-term_truecolor:
``term_truecolor``
Defines whether to output cterm indices (8-bit) or RGB colors (24-bit)
to the terminal emulator. See the :ref:`term-feature-support-matrix` for
information on whether your terminal emulator supports 24-bit colors.
.. _config-common-ambiwidth:
``ambiwidth``
Tells powerline what to do with characters with East Asian Width Class
Ambigious (such as Euro, Registered Sign, Copyright Sign, Greek
letters, Cyrillic letters). Valid values: any positive integer; it is
suggested that you only set it to 1 (default) or 2.
``watcher``
Select filesystem watcher. Variants are
======= ===================================
Variant Description
======= ===================================
auto Selects most performant watcher.
inotify Select inotify watcher. Linux only.
stat Select stat-based polling watcher.
======= ===================================
Default is ``auto``.
.. _config-common-additional_escapes:
``additional_escapes``
Valid for shell extensions, makes sense only if :ref:`term_truecolor
<config-common-term_truecolor>` is enabled. Is to be set from command-line
(unless you are sure you always need it). Controls additional escaping that
is needed for tmux/screen to work with terminal true color escape codes:
normally tmux/screen prevent terminal emulator from receiving these control
codes thus rendering powerline prompt colorless. Valid values: ``"tmux"``,
``"screen"``, ``null`` (default).
``dividers``
Defines the dividers used in all Powerline extensions. This option
should usually only be changed if you don't have a patched font, or if
you use a font patched with the legacy font patcher.
The ``hard`` dividers are used to divide segments with different
background colors, while the ``soft`` dividers are used to divide
segments with the same background color.
.. _config-common-paths:
``paths``
Defines additional paths which will be searched for modules when using
:ref:`module segment option <config-themes-seg-module>`. Paths defined here
have priority when searching for modules.
``log_file``
Defines path which will hold powerline logs. If not present, logging will be
done to stderr.
``log_level``
String, determines logging level. Defaults to ``WARNING``.
``log_format``
String, determines format of the log messages. Defaults to
``'%(asctime)s:%(level)s:%(message)s'``.
``interval``
Number, determines time (in seconds) between checks for changed
configuration. Checks are done in a seprate thread. Use ``null`` to check
for configuration changes on ``.render()`` call in main thread.
Defaults to ``None``.
``reload_config``
Boolean, determines whether configuration should be reloaded at all.
Defaults to ``True``.
Extension-specific configuration
--------------------------------
Common configuration is a subdictionary that is a value of ``ext`` key in
:file:`powerline/config.json` file.
``colorscheme``
Defines the colorscheme used for this extension.
``theme``
.. _config-ext-theme:
Defines the theme used for this extension.
``local_themes``
.. _config-ext-local_themes:
Defines themes used when certain conditions are met, e.g. for
buffer-specific statuslines in vim. Value depends on extension used. For vim
it is a dictionary ``{matcher_name : theme_name}``, where ``matcher_name``
is either ``matcher_module.module_attribute`` or ``module_attribute``
(``matcher_module`` defaults to ``powerline.matchers.vim``) and
``module_attribute`` should point to a function that returns boolean value
indicating that current buffer has (not) matched conditions.
.. _config-colors:
Color definitions
=================
:Location: :file:`powerline/colors.json`
.. _config-colors-colors:
``colors``
Color definitions, consisting of a dict where the key is the name of the
color, and the value is one of the following:
* A cterm color index.
* A list with a cterm color index and a hex color string (e.g. ``[123,
"aabbcc"]``). This is useful for colorschemes that use colors that
aren't available in color terminals.
``gradients``
Gradient definitions, consisting of a dict where the key is the name of the
gradient, and the value is a list containing one or two items, second item
is optional:
* A list of cterm color indicies.
* A list of hex color strings.
It is expected that you define gradients from least alert color to most
alert or use non-alert colors.
.. _config-colorschemes:
Colorschemes
============
:Location: :file:`powerline/colorschemes/{name}.json`,
:file:`powerline/colorscheme/__main__.json`,
:file:`powerline/colorschemes/{extension}/{name}.json`
Colorscheme files are processed in order given: definitions from each next file
override those from each previous file. It is required that either
:file:`powerline/colorschemes/{name}.json`, or
:file:`powerline/colorschemes/{extension}/{name}.json` exists.
``name``
Name of the colorscheme.
.. _config-colorschemes-groups:
``groups``
Segment highlighting groups, consisting of a dict where the key is the
name of the highlighting group (usually the function name for function
segments), and the value is either
#) a dict that defines the foreground color, background color and
attributes:
``fg``
Foreground color. Must be defined in :ref:`colors
<config-colors-colors>`.
``bg``
Background color. Must be defined in :ref:`colors
<config-colors-colors>`.
``attr``
List of attributes. Valid values are one or more of ``bold``,
``italic`` and ``underline``. Note that some attributes may be
unavailable in some applications or terminal emulators. If you do not
need any attributes leave this empty.
#) a string (an alias): a name of existing group. This group’s definition
will be used when this color is requested.
``mode_translations``
Mode-specific highlighting for extensions that support it (e.g. the vim
extension). It's an easy way of changing a color in a specific mode.
Consists of a dict where the key is the mode and the value is a dict
with the following options:
``colors``
A dict where the key is the color to be translated in this mode, and
the value is the new color. Both the key and the value must be defined
in :ref:`colors <config-colors-colors>`.
``groups``
Segment highlighting groups for this mode. Same syntax as the main
:ref:`groups <config-colorschemes-groups>` option.
.. _config-themes:
Themes
======
:Location: :file:`powerline/themes/{extension}/{name}.json`
``name``
Name of the theme.
.. _config-themes-default_module:
``default_module``
Python module where segments will be looked by default.
.. _config-themes-segment_data:
``segment_data``
A dict where keys are segment names or strings ``{module}.{name}``. Used to
specify default values for various keys:
:ref:`after <config-theme-seg-after>`,
:ref:`args <config-themes-seg-args>` (only for function segments),
:ref:`before <config-theme-seg-before>`,
:ref:`contents <config-theme-seg-contents>` (only for string segments
if :ref:`name <config-themes-seg-name>` is defined),
:ref:`display <config-theme-seg-display`.
When using :ref:`local themes <config-ext-local_themes>` values of these
keys are first searched in the segment description, then in ``segment_data``
key of a local theme, then in ``segment_data`` key of a :ref:`default theme
<config-ext-theme>`. For the :ref:`default theme <config-ext-theme>` itself
step 2 is obviously avoided.
``segments``
A dict with a ``left`` and a ``right`` lists, consisting of segment
dictionaries. Shell themes may also contain ``above`` list of dictionaries.
Each item in ``above`` list may have ``left`` and ``right`` keys like this
dictionary, but no ``above`` key.
.. _config-themes-above:
``above`` list is used for multiline shell configurations.
``left`` and ``right`` lists are used for segments that should be put on the
left or right side in the output. Actual mechanizm of putting segments on
the left or the right depends on used renderer, but most renderers require
one to specify segment with :ref:`width <config-themes-seg-width>` ``auto``
on either side to make generated line fill all of the available width.
Each segment dictionary has the following options:
``type``
The segment type. Can be one of ``function`` (default), ``string``
or ``filler``:
``function``
The segment contents is the return value of the function defined
in the :ref:`name option <config-themes-seg-name>`.
``string``
A static string segment where the contents is defined in the
:ref:`contents option <config-themes-seg-contents>`, and the
highlighting group is defined in the :ref:`highlight_group
option <config-themes-seg-highlight_group>`.
``module``
.. _config-themes-seg-module:
Function module, only required for function segments. Defaults to
``powerline.segments.{extension}``. Default is overriden by
:ref:`default_module theme option <config-themes-default_module>`.
``name``
.. _config-themes-seg-name:
Function name, only required for function segments.
``highlight_group``
.. _config-themes-seg-highlight_group:
Highlighting group for this segment. Consists of a prioritized list
of highlighting groups, where the first highlighting group that is
available in the colorscheme is used.
Ignored for segments that have ``function`` type.
``before``
.. _config-themes-seg-before:
A string which will be prepended to the segment contents.
``after``
.. _config-themes-seg-after:
A string which will be appended to the segment contents.
``contents``
.. _config-themes-seg-contents:
Segment contents, only required for ``string`` segments.
``args``
.. _config-themes-seg-args:
A dict of arguments to be passed to a ``function`` segment.
``align``
Aligns the segments contents to the left (``l``), center (``c``) or
right (``r``).
``width``
.. _config-themes-seg-width:
Enforces a specific width for this segment.
This segment will work as a spacer if the width is set to ``auto``.
Several spacers may be used, and the space will be distributed
equally among all the spacer segments. Spacers may have contents,
either returned by a function or a static string, and the contents
can be aligned with the ``align`` property.
``priority``
Optional segment priority. Segments with priority ``None`` (the default
priority, represented by ``null`` in json) will always be included,
regardless of the width of the prompt/statusline.
If the priority is any number, the segment may be removed if the
prompt/statusline width is too small for all the segments to be
rendered. A lower number means that the segment has a higher priority.
Segments are removed according to their priority, with low priority
segments being removed first.
``draw_hard_divider``, ``draw_soft_divider``
Whether to draw a divider between this and the adjacent segment. The
adjacent segment is to the *right* for segments on the *left* side, and
vice versa. Hard dividers are used between segments with different
background colors, soft ones are used between segments with same
background. Both options default to ``True``.
``draw_inner_divider``
Determines whether inner soft dividers are to be drawn for function
segments. Only applicable for functions returning multiple segments.
Defaults to ``False``.
``exclude_modes``
A list of modes where this segment will be excluded: The segment is
included in all modes, *except* for the modes in this list.
``include_modes``
A list of modes where this segment will be included: The segment is
*not* included in any modes, *except* for the modes in this list.
``display``
.. _config-themes-seg-display:
Boolean. If false disables displaying of the segment.
Defaults to ``True``.
Segments
========
Segments are written in Python, and the default segments provided with
Powerline are located in :file:`powerline/segments/{extension}.py`.
User-defined segments can be defined in any module in ``sys.path`` or
:ref:`paths common configuration option <config-common-paths>`, import is
always absolute.
Segments are regular Python functions, and they may accept arguments. All
arguments should have a default value which will be used for themes that
don't provide an ``args`` dict.
A segment function must return one of the following values:
* ``None``, which will remove the segment from the prompt/statusline.
* A string, which will be the segment contents.
* A list of dicts consisting of a ``contents`` string, and
a ``highlight_group`` list. This is useful for providing a particular
highlighting group depending on the segment contents.
Local configuration
===================
Depending on the application used it is possible to override configuration. Here
is the list:
Vim overrides
-------------
Vim configuration can be overridden using the following options:
``g:powerline_config_overrides``
Dictionary, recursively merged with contents of
:file:`powerline/config.json`.
``g:powerline_theme_overrides__{theme_name}``
Dictionary, recursively merged with contents of
:file:`powerline/themes/vim/{theme_name}.json`. Note that this way you can’t
redefine some value (e.g. segment) in list, only the whole list itself: only
dictionaries are merged recursively.
``g:powerline_config_path``
Path (must be expanded, ``~`` shortcut is not supported). Points to the
directory which will be searched for configuration. When this option is
present, none of the other locations are searched.
``g:powerline_no_python_error``
If this variable is set to a true value it will prevent Powerline from reporting
an error when loaded in a copy of vim without the necessary Python support.
Powerline script overrides
--------------------------
Powerline script has a number of options controlling powerline behavior. Here
``VALUE`` always means “some JSON object”.
``-c KEY.NESTED_KEY=VALUE`` or ``--config=KEY.NESTED_KEY=VALUE``
Overrides options from :file:`powerline/config.json`.
``KEY.KEY2.KEY3=VALUE`` is a shortcut for ``KEY={"KEY2": {"KEY3": VALUE}}``.
Multiple options (i.e. ``-c K1=V1 -c K2=V2``) are allowed, result (in the
example: ``{"K1": V1, "K2": V2}``) is recursively merged with the contents
of the file.
If ``VALUE`` is omitted then corresponding key will be removed from the
configuration (if it was present).
``-t THEME_NAME.KEY.NESTED_KEY=VALUE`` or ``--theme_option=THEME_NAME.KEY.NESTED_KEY=VALUE``
Overrides options from :file:`powerline/themes/{ext}/{THEME_NAME}.json`.
``KEY.NESTED_KEY=VALUE`` is processed like described above, ``{ext}`` is the
first argument to powerline script. May be passed multiple times.
If ``VALUE`` is omitted then corresponding key will be removed from the
configuration (if it was present).
``-p PATH`` or ``--config_path=PATH``
Sets directory where configuration should be read from. If present, no
default locations are searched for configuration. No expansions are
performed by powerline script itself, but ``-p ~/.powerline`` will likely be
expanded by the shell to something like ``-p /home/user/.powerline``.
Zsh/zpython overrides
---------------------
Here overrides are controlled by similarly to the powerline script, but values
are taken from zsh variables.
``POWERLINE_CONFIG``
Overrides options from :file:`powerline/config.json`. Should be a zsh
associative array with keys equal to ``KEY.NESTED_KEY`` and values being
JSON strings. Pair ``KEY.KEY1 VALUE`` is equivalent to ``{"KEY": {"KEY1":
VALUE}}``. All pairs are then recursively merged into one dictionary and
this dictionary is recursively merged with the contents of the file.
``POWERLINE_THEME_CONFIG``
Overrides options from :file:`powerline/themes/shell/*.json`. Should be
a zsh associative array with keys equal to ``THEME_NAME.KEY.NESTED_KEY`` and
values being JSON strings. Is processed like the above ``POWERLINE_CONFIG``,
but only subdictionaries for ``THEME_NAME`` key are merged with theme
configuration when theme with given name is requested.
``POWERLINE_CONFIG_PATH``
Sets directory where configuration should be read from. If present, no
default locations are searched for configuration. No expansions are
performed by powerline script itself, but zsh usually performs them on its
own if you set variable without quotes: ``POWERLINE_CONFIG_PATH=~/example``.
Expansion depends on zsh configuration.
Ipython overrides
-----------------
Ipython overrides depend on ipython version. Before ipython-0.11 you should pass
additional keyword arguments to setup() function. After ipython-0.11 you should
use ``c.Powerline.KEY``. Supported ``KEY`` strings or keyword argument names:
``config_overrides``
Overrides options from :file:`powerline/config.json`. Should be a dictionary
that will be recursively merged with the contents of the file.
``theme_overrides``
Overrides options from :file:`powerline/themes/ipython/*.json`. Should be
a dictionary where keys are theme names and values are dictionaries which
will be recursively merged with the contents of the given theme.
``path``
Sets directory where configuration should be read from. If present, no
default locations are searched for configuration. No expansions are
performed thus you cannot use paths starting with ``~/``.
Prompt command
--------------
In addition to the above configuration options you can use
``$POWERLINE_COMMAND`` environment variable to tell shell or tmux to use
specific powerline implementation. This is mostly useful for putting powerline
into different directory or replacing ``powerline`` script with
``powerline-client`` for performance reasons.
.. note::
``$POWERLINE_COMMAND`` appears in shell scripts without quotes thus you can
specify additional parameters in bash. In zsh you will have to make
``$POWERLINE_COMMAND`` an array parameter to achieve the same result. In
tmux it is passed to ``eval`` and depends on the shell used.
POSIX-compatible shells, zsh, bash and fish will split this variable in this
case.
If you want to disable prompt in shell, but still have tmux support or if you
want to disable tmux support you can use variables
``$POWERLINE_NO_{SHELL}_PROMPT``/``$POWERLINE_NO_SHELL_PROMPT`` and
``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT``/``$POWERLINE_NO_SHELL_TMUX_SUPPORT``
(substitute ``{SHELL}`` with the name of the shell (all-caps) you want to
disable support for (e.g. ``BASH``) or use all-inclusive ``SHELL`` that will
disable support for all shells). These variables have no effect after
configuration script was sourced (in fish case: after ``powerline-setup``
function was run). To disable specific feature support set one of these
variables to some non-empty value.
If you do not want to disable prompt in shell, but yet do not want to launch
python twice to get :ref:`above <config-themes-above>` lines you do not use in
tcsh you should set ``$POWERLINE_NO_TCSH_ABOVE`` or
``$POWERLINE_NO_SHELL_ABOVE`` variable.
If you do not want to see additional space which is added to the right prompt in
fish in order to support multiline prompt you should set
``$POWERLINE_NO_FISH_ABOVE`` or ``$POWERLINE_NO_SHELL_ABOVE`` variables.
.. note::
Most supported shells’ configuration scripts check for additional
configuration variables being empty. But tcsh configuration script checks
for variables being *defined*, not empty.

142
docs/source/font-installation.rst
View File

@ -1,142 +0,0 @@
***********************************
Font installation and configuration
***********************************
Powerline uses several special glyphs to get the arrow effect and some
custom symbols for developers. This requires that you either have a symbol
font or a patched font on your system. Your terminal emulator must also
support either patched fonts or fontconfig for Powerline to work properly.
You can also enable :ref:`24-bit color support <config-common-term_truecolor>`
if your terminal emulator supports it.
.. table:: Application/terminal emulator feature support matrix
:name: term-feature-support-matrix
===================== ======= =================================== ===================== ===================== =====================
Name OS Recommended installation method Patched font support Fontconfig support 24-bit color support
===================== ======= =================================== ===================== ===================== =====================
Gnome Terminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no|
Gvim Linux `Patched font`_ |i_yes| |i_no| |i_yes|
Konsole Linux `Fontconfig`_ |i_yes| |i_yes| |i_yes|
lxterminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no|
rxvt-unicode Linux `rxvt-unicode`_ or `Patched font`_ |i_partial| [#]_ |i_no| |i_no|
st Linux `Fontconfig`_ |i_yes| |i_yes| |i_no|
Xfce Terminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no|
xterm Linux `Patched font`_ |i_yes| |i_no| |i_partial| [#]_
iTerm2 OS X `Patched font`_ |i_yes| |i_no| |i_no|
MacVim OS X `Patched font`_ |i_yes| |i_no| |i_yes|
Terminal.app OS X `Patched font`_ |i_yes| |i_no| |i_no|
===================== ======= =================================== ===================== ===================== =====================
.. |i_yes| image:: _static/img/icons/tick.png
.. |i_no| image:: _static/img/icons/cross.png
.. |i_partial| image:: _static/img/icons/error.png
.. [#] Must be compiled with ``--enable-unicode3`` for the
patched font to work.
.. [#] Uses nearest color from 8-bit palette.
Fontconfig
==========
This method only works on Linux. It's the recommended method if your
terminal emulator supports it as you don't have to patch any fonts, and it
generally works well with any coding font.
#. Download the latest version of the symbol font and fontconfig file::
wget https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf
wget https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf
#. Move the symbol font to a valid X font path. Valid font paths can be
listed with ``xset q``::
mv PowerlineSymbols.otf ~/.fonts/
#. Update font cache for the path you moved the font to (you may need to be
root to update the cache for system-wide paths)::
fc-cache -vf ~/.fonts/
#. Install the fontconfig file. For newer versions of fontconfig the config
path is ``~/.config/fontconfig/conf.d/``, for older versions it's
``~/.fonts.conf.d/``::
mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/
If you can't see the custom symbols, please close all instances of your
terminal emulator. You may need to restart X for the changes to take
effect.
If you *still* can't see the custom symbols, double-check that you have
installed the font to a valid X font path, and that you have installed the
fontconfig file to a valid fontconfig path. Alternatively try to install
a `Patched font`_.
Patched font
============
This method is the fallback method and works for every terminal emulator and
OS, with the exception of `rxvt-unicode`_.
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.
.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts
Installation on Linux
---------------------
#. Move the patched font to a valid X font path. Valid font paths can be
listed with ``xset q``::
mv 'MyFont for Powerline.otf' ~/.fonts/
#. Update font cache for the path you moved the font to (you may need to be
root to update the cache for system-wide paths)::
fc-cache -vf ~/.fonts/
After installing the patched font you need to update Gvim or your terminal
emulator to use the patched font. The correct font usually ends with *for
Powerline*.
If you can't see the custom symbols, please close all instances of your
terminal emulator. You may need to restart X for the changes to take
effect.
If you *still* can't see the custom symbols, double-check that you have
installed the font to a valid X font path.
Installation on OS X
--------------------
Install your patched font by double-clicking the font file in Finder, then
clicking :guilabel:`Install this font` in the preview window.
After installing the patched font you need to update MacVim or your terminal
emulator to use the patched font. The correct font usually ends with *for
Powerline*.
Special cases
=============
rxvt-unicode
------------
.. note:: Symbol font support generally doesn't work well in
rxvt-unicode. It's recommended that you either disable the symbols or
switch to a better terminal emulator if you want to use Powerline.
rxvt-unicode allows using a `Patched font`_ only if it's compiled with the
``--enable-unicode3`` flag.
For unsupported fonts (e.g. bitmap fonts like Terminus), you can't use
``PowerlineSymbols.otf`` as a fallback since rxvt-unicode has trouble
determining the font's metrics. A solution to this issue is to get
a `Patched font`_ and add this as a fallback font to your
``.Xresources``/``.Xdefaults``::
URxvt*font: xft:Terminus:pixelsize=12,xft:Inconsolata\ for\ Powerline:pixelsize=12

136
docs/source/fontpatching.rst
View File

@ -1,136 +0,0 @@
.. _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.
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
Powerline uses in your user configuration.
.. note:: Powerline no longer works with rxvt-unicode unless you either use
rxvt-unicode compiled with ``--enable-unicode3``, or you use fonts patched
with the legacy font patcher and change the glyphs in your user
configuration.
Glyph table
===========
Powerline stores all special glyphs in the Unicode *Private Use Area*
(``U+E000``-``U+F8FF``).
========== ===== ===========
Code point Glyph Description
========== ===== ===========
``U+E0A0``  Version control branch
``U+E0A1``  LN (line) symbol
``U+E0A2``  Closed padlock
``U+E0B0``  Rightwards black arrowhead
``U+E0B1``  Rightwards arrowhead
``U+E0B2``  Leftwards black arrowhead
``U+E0B3``  Leftwards arrowhead
========== ===== ===========
Usage
=====
The font patcher, :file:`fontpatcher.py` is located in the `powerline-fontpatcher
<https://github.com/Lokaltog/powerline-fontpatcher>`_ repository on GitHub.
It requires Python 2.7 and FontForge compiled with Python bindings to work.
Patched fonts are renamed by default (" for Powerline" is added to the font
name) so they don't conflict with existing fonts. Use the ``--no-rename``
option to disable font renaming.
.. note:: Bitmap fonts are not supported, and will probably never be
supported officially due to difficulty creating a font patcher that works
for bitmap fonts. The recommended method of patching bitmap fonts is to draw
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
package is ``fontforge``. It should be something similar for other
distros.
2. Run the font patcher::
$ /path/to/fontpatcher.py MyFontFile.ttf
3. Copy the font file into :file:`~/.fonts` (or another X font directory)::
$ cp "MyFontFile for Powerline.otf" ~/.fonts
4. Update your font cache::
$ fc-cache -vf ~/.fonts
If you're using vim in a terminal you may need to close all open terminal
windows after updating the font cache.
5. **Gvim users:** Update the GUI font in your :file:`vimrc` file::
set guifont=MyFont\ for\ Powerline
**Terminal users:** Update your terminal configuration to use the patched
font.
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::
$ fontforge -version
Copyright (c) 2000-2011 by George Williams.
Executable based on sources from 13:48 GMT 22-Feb-2011-D.
Library based on sources from 13:48 GMT 22-Feb-2011.
fontforge 20110222
libfontforge 20110222
Make sure that the executable version number doesn't have ``NoPython`` in
it. If everything looks OK, skip ahead to step 4.
2. If you have FontForge but with ``NoPython`` in the version number, please
try to update to a later version::
$ brew uninstall fontforge
$ brew update
$ brew install fontforge
**Note:** You may have to use ``--use-clang`` instead of ``--use-gcc``
when compiling FontForge.
3. If you don't have FontForge, install it with Homebrew::
$ brew update
$ brew install fontforge
4. Patch your fonts by passing the ``fontpatcher`` script as a parameter to
FontForge::
$ fontforge -script /path/to/fontpatcher.py MyFontFile.ttf
5. Install the font by double-clicking the font file in Finder and click
"Install this font" from the preview window.
6. **Gvim users:** Update the GUI font in your :file:`vimrc` file::
set guifont=MyFont\ for\ Powerline
**Terminal users:** Update your terminal configuration to use the patched
font.
7. Open vim and enjoy your new statusline!

19
docs/source/index.rst
View File

@ -6,20 +6,13 @@ Powerline
:maxdepth: 2 :maxdepth: 2
:glob: :glob:
introduction
overview overview
configuration installation
tipstricks usage
fontpatching configuration-and-customization
license-credits troubleshooting
tips-and-tricks
Segments license-and-credits
========
.. toctree::
segments/common
segments/shell
segments/vim
Indices and tables Indices and tables
================== ==================

8
docs/source/installation.rst Normal file
View File

@ -0,0 +1,8 @@
************
Installation
************
.. toctree::
Linux <installation/linux>
OS X <installation/osx>

103
docs/source/installation/linux.rst
View File

@ -1,106 +1,9 @@
:tocdepth: 2
.. _installation-linux:
********************* *********************
Installation on Linux Installation on Linux
********************* *********************
The following distribution-specific packages are officially supported, and Requirements
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 in `raiagent <https://github.com/leycec/raiagent>`_ overlay
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.2+ or Python 2.6+.
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.
.. note:: If you are powerline developer you should be aware that ``pip install
--editable`` does not currently fully work. If you
install powerline this way you will be missing ``powerline`` executable and
need to symlink it. It will be located in ``scripts/powerline``.
Font installation
=================
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 :ref:`term-feature-support-matrix` for details about
what features your terminal emulator supports.
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 Installation
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

124
docs/source/installation/osx.rst
View File

@ -1,125 +1,9 @@
:tocdepth: 2
.. _installation-osx:
******************** ********************
Installation on OS X Installation on OS X
******************** ********************
Plugin installation Requirements
=================== ------------
Python package Installation
-------------- ------------
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.
.. note:: If you are powerline developer you should be aware that ``pip install
--editable`` does not currently fully work. If you
install powerline this way you will be missing ``powerline`` executable and
need to symlink it. It will be located in ``scripts/powerline``.
Vim installation
----------------
Any terminal vim version with Python 3.2+ or Python 2.6+ 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
=================
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.
Statusline is getting wrapped to the next line in iTerm2
--------------------------------------------------------
* Turn off “Treat ambigious-width characters as double width” in `Preferences
--> Text`.
* Alternative: remove fancy dividers (they suck in this case), set
:ref:`ambiwidth <config-common-ambiwidth>` to 2.
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

136
docs/source/installation/troubleshooting-common.rst
View File

@ -1,136 +0,0 @@
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`.
I’m using tmux/screen and Powerline is colorless
------------------------------------------------
* If the above advices do not help, then you need to disable
:ref:`term_truecolor <config-common-term_truecolor>`.
* Alternative: set :ref:`additional_escapes <config-common-additional_escapes>`
to ``"tmux"`` or ``"screen"``. Note that it is known to work perfectly in
screen, but in tmux it may produce ugly spaces.
After an update something stopped working
-----------------------------------------
Assuming powerline was working before update and stopped only after there are
two possible explanations:
* You have more then one powerline installation (e.g. ``pip`` and ``Vundle``
installations) and you have updated only one.
* Update brought some bug to powerline.
In the second case you, of course, should report the bug to `powerline bug
tracker <https://github.com/Lokaltog/powerline>`_. In the first you should make
sure you either have only one powerline installation or you update all of them
simultaneously (beware that in the second case you are not supported). To
diagnose this problem you may do the following:
#) If this problem is observed within the shell make sure that
.. code-block:: shell
python -c 'import powerline; print (powerline.__file__)'
which should report something like
:file:`/usr/lib64/python2.7/site-packages/powerline/__init__.pyc` (if
powerline is installed system-wide) or
:file:`/home/USER/.../powerline/__init__.pyc` (if powerline was cloned
somewhere, e.g. in :file:`/home/USER/.vim/bundle/powerline`) reports the same
location you use to source in your shell configuration: in first case it
should be some location in :file:`/usr` (e.g.
:file:`/usr/share/zsh/site-contrib/powerline.zsh`), in the second it should
be something like
:file:`/home/USER/.../powerline/bindings/zsh/powerline.zsh`. If this is true
it may be a powerline bug, but if locations do not match you should not
report the bug until you observe it on configuration where locations do
match.
#) If this problem is observed within the vim instance you should check out the
output of the following Ex mode commands
.. code-block:: vim
python import powerline as pl ; print (pl.__file__)
python3 import powerline as pl ; print (pl.__file__)
One (but not both) of them will most likely error out, this is OK. The same
rules apply as in the 1), but in place of sourcing you should seek for the
place where you modify `runtimepath` vim option. If you install powerline
using `VAM <https://github.com/MarcWeber/vim-addon-manager>`_ then no
explicit modifications of runtimpath were performed in your vimrc
(runtimepath is modified by VAM in this case), but powerline will be placed
in :file:`{plugin_root_dir}/powerline` where `{plugin_root_dir}` is stored in
VAM settings dictionary: do `echo g:vim_addon_manager.plugin_root_dir`.
There is a hint if you want to place powerline repository somewhere, but still
make powerline package importable anywhere: use
.. code-block:: shell
pip install --user --editable path/to/powerline
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`.
My vim statusline is not displayed completely and has too much spaces
---------------------------------------------------------------------
* Be sure you have ``ambiwidth`` option set to ``single``.
* Alternative: set :ref:`ambiwidth <config-common-ambiwidth>` to 2, remove fancy
dividers (they suck when ``ambiwidth`` is set to double).
When using z powerline shows wrong number of jobs
-------------------------------------------------
This happens because `z <https://github.com/rupa/z>`_ is launching some jobs in
the background from ``$POWERLINE_COMMAND`` and these jobs fail to finish before
powerline prompt is run.
Solution to this problem is simple: be sure that :file:`z.sh` is sourced
strictly after :file:`powerline/bindings/bash/powerline.sh`. This way background
jobs are spawned by `z <https://github.com/rupa/z>`_ after powerline has done
its job.
I am suffering bad lags before displaying shell prompt
------------------------------------------------------
To get rid of these lags there currently are two options:
* Run ``powerline-daemon``. Powerline does not automatically start it for you.
* Compile and install ``libzpython`` module that lives in
https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific.
Prompt is spoiled after completing files in ksh
-----------------------------------------------
This is exactly why powerline has official mksh support, but not official ksh
support. If you know the solution feel free to share it in `powerline bug
tracker <https://github.com/Lokaltog/powerline/issues/new>`_.

65
docs/source/introduction.rst
View File

@ -1,65 +0,0 @@
************
Introduction
************
This is the next version of Powerline, implemented in Python. It aims to
resolve some of the "unresolvable" problems of the vimscript implementation,
as well as providing a common code base for all projects that use Powerline
in some way (e.g. shell prompts and tmux themes).
The project is currently in beta, and most of the functionality in the old
vimscript project is already implemented.
Screenshots
===========
**Mode-dependent highlighting**
* .. image:: _static/img/pl-mode-normal.png
:alt: Normal mode
* .. image:: _static/img/pl-mode-insert.png
:alt: Insert mode
* .. image:: _static/img/pl-mode-visual.png
:alt: Visual mode
* .. image:: _static/img/pl-mode-replace.png
:alt: Replace mode
**Automatic truncation of segments in small windows**
* .. image:: _static/img/pl-truncate1.png
:alt: Truncation illustration
* .. image:: _static/img/pl-truncate2.png
:alt: Truncation illustration
* .. image:: _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
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
much easier to profile the code and eliminate bottlenecks.
* **A much leaner code base.** With most of the functionality of the old
project implemented the new version consists of less than half the amount
of code.
* **Automatic removal of less important segments in small windows.** Not all
information is equally important to have in the statusline, and segments
with e.g. encoding and file format information are automatically removed
in smaller windows.
* **Dynamic statusline evaluation in Python.** Statuslines are dynamically
rendered in Python instead of relying on vim's statusline flags, which
allows much more flexibility when creating statuslines.
* **The possibility of adding more segments.** Because of vim's hardcoded
limitation of 80 statusline options, the vimscript implementation
triggered an error when adding more segments to the default theme. Since
segment contents are now rendered as plain text in Python it's possible to
add many more segments in the statusline before reaching this limit.
* **New and improved theme and colorscheme syntax.** Themes and colorschemes
are now written in JSON, with a much cleaner syntax that's easier to learn
and work with. Themes and colorschemes are also much more configurable,
and it's easy to write your own and store them in your home config
directory.

14
docs/source/license-credits.rst → docs/source/license-and-credits.rst
View File

@ -2,28 +2,22 @@
License and credits License and credits
******************* *******************
License Powerline is licensed under the `MIT license
=======
Powerline is licensed under the `MIT license
<https://raw.github.com/Lokaltog/powerline/develop/LICENSE>`_. <https://raw.github.com/Lokaltog/powerline/develop/LICENSE>`_.
Credits
=======
Authors Authors
------- -------
* `Kim Silkebækken <https://github.com/Lokaltog>`_ * `Kim Silkebækken <https://github.com/Lokaltog>`_
* `ZyX-I <https://github.com/ZyX-I>`_ * `Nikolay Pavlov <https://github.com/ZyX-I>`_
* `Kovid Goyal <https://github.com/kovidgoyal>`_ * `Kovid Goyal <https://github.com/kovidgoyal>`_
Contributors Contributors
------------ ------------
* `List of contributors * `List of contributors
<https://github.com/Lokaltog/powerline/contributors>`_ <https://github.com/Lokaltog/powerline/contributors>`_
* The glyphs in the font patcher are created by Fabrizio Schiavi, creator of * The glyphs in the font patcher are created by Fabrizio Schiavi, creator of
the excellent coding font `Pragmata Pro`_. the excellent coding font `Pragmata Pro`_.
.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm .. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm

378
docs/source/overview.rst
View File

@ -2,332 +2,66 @@
Overview Overview
******** ********
Requirements **Powerline is a statusline plugin for vim, and provides statuslines and
============ prompts for several other applications, including zsh, bash, tmux, IPython,
Awesome and Qtile.**
Powerline requires Python 3.3 or Python 2.7 to work. Features
--------
Vim plugin requirements * **Extensible and feature rich, written in Python.** Powerline was
----------------------- completely rewritten in Python to get rid of as much vimscript as
possible. This has allowed much better extensibility, leaner and better
config files, and a structured, object-oriented codebase with no mandatory
third-party dependencies other than a Python interpreter.
* **Stable and testable code base.** Using Python has allowed unit testing
of all the project code. The code is tested to work in Python 2.6+ and
Python 3.
* **Support for prompts and statuslines in many applications.** Originally
created exclusively for vim statuslines, the project has evolved to
provide statuslines in tmux and several WMs, and prompts for shells like
bash/zsh and other applications. It's simple to write renderers for any
other applications that Powerline doesn't yet support.
* **Configuration and colorschemes written in JSON.** JSON is
a standardized, simple and easy to use file format that allows for easy
user configuration across all of Powerline's supported applications.
* **Fast and lightweight, with daemon support for even better performance.**
Although the code base spans a couple of thousand lines of code with no
goal of "less than X lines of code", the main focus is on good performance
and as little code as possible while still providing a rich set of
features. The new daemon also ensures that only one Python instance is
launched for prompts and statuslines, which provides excellent
performance.
The vim plugin requires a vim version with Python support compiled in. You *But I hate Python / I don't need shell prompts / this is just too much
can check if your vim supports Python by running ``vim --version | grep hassle for me / what happened to the original vim-powerline project / …*
+python``.
If your vim version doesn't have support for Python, you'll have to compile You should check out some of the Powerline derivatives. The most lightweight
it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if and feature-rich alternative is currently Bailey Ling's `vim-airline
you want Python 3 support instead). Note that this also requires the related <https://github.com/bling/vim-airline>`_ project.
Python headers to be installed on your system. Please consult your
distribution's documentation for details on how to compile and install
packages.
Vim version 7.3.661 or newer is recommended for performance reasons. Screenshots
-----------
Terminal emulator requirements
------------------------------
Powerline uses several special glyphs to get the arrow effect and some
custom symbols for developers. This requires that you either have a symbol
font or a patched font on your system. Your terminal emulator must also
support either patched fonts or fontconfig for Powerline to work properly.
You can also enable :ref:`24-bit color support <config-common-term_truecolor>`
if your terminal emulator supports it.
.. table:: Application/terminal emulator feature support matrix
:name: term-feature-support-matrix
===================== ======= ===================== ===================== =====================
Name OS Patched font support Fontconfig support 24-bit color support
===================== ======= ===================== ===================== =====================
Gnome Terminal Linux |i_yes| |i_yes| |i_no|
Gvim Linux |i_yes| |i_no| |i_yes|
iTerm2 OS X |i_yes| |i_no| |i_no|
Konsole Linux |i_yes| |i_yes| |i_yes|
lxterminal Linux |i_yes| |i_yes| |i_no|
MacVim OS X |i_yes| |i_no| |i_yes|
rxvt-unicode Linux |i_partial| [#]_ |i_no| |i_no|
st Linux |i_yes| |i_yes| |i_no|
Terminal.app OS X |i_yes| |i_no| |i_no|
Xfce Terminal Linux |i_yes| |i_yes| |i_no|
xterm Linux |i_yes| |i_no| |i_partial| [#]_
===================== ======= ===================== ===================== =====================
.. |i_yes| image:: _static/img/icons/tick.png
.. |i_no| image:: _static/img/icons/cross.png
.. |i_partial| image:: _static/img/icons/error.png
.. [#] Must be compiled with ``--enable-unicode3`` for the
patched font to work.
.. [#] Uses nearest color from 8-bit palette.
Optional dependencies
---------------------
The following software is not required by all segments, but recommended for
optimal performance and extra features:
Python packages
^^^^^^^^^^^^^^^
* ``pygit2``
* ``mercurial``
* ``psutil``
* ``i3-py``, `available on github <https://github.com/ziberna/i3-py>`_. Only used with i3wm bindings and segments.
Other applications
^^^^^^^^^^^^^^^^^^
* ``git`` version 1.7.2 and later. Not needed if you have ``pygit2``.
Installation
============
.. note:: This project is currently unavailable from PyPI due to a naming conflict
with an unrelated project. Please read the detailed instructions for your platform
below.
* :ref:`installation-linux`
* :ref:`installation-osx`
Usage
=====
.. _vim-vimrc:
Vim statusline Vim statusline
-------------- ^^^^^^^^^^^^^^
If installed using pip just add **Mode-dependent highlighting**
.. code-block:: vim * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-normal.png
:alt: Normal mode
python from powerline.vim import setup as powerline_setup * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-insert.png
python powerline_setup() :alt: Insert mode
python del powerline_setup * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-visual.png
:alt: Visual mode
(replace ``python`` with ``python3`` if appropriate) to your :file:`vimrc`. * .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-replace.png
:alt: Replace mode
If you just cloned the repository add the following line to your :file:`vimrc`,
where ``{repository_root}`` is the absolute path to your Powerline installation **Automatic truncation of segments in small windows**
directory:
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate1.png
.. code-block:: vim :alt: Truncation illustration
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate2.png
set rtp+={repository_root}/powerline/bindings/vim :alt: Truncation illustration
* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate3.png
If you're using Vundle or Pathogen and don't want Powerline functionality in :alt: Truncation illustration
any other applications, simply add Powerline as a bundle and point the path
above to the Powerline bundle directory, e.g.
``~/.vim/bundle/powerline/powerline/bindings/vim``. For vim-addon-manager it is
even easier since you don’t need to write this big path or install anything by
hand: ``powerline`` is installed and run just like any other plugin using
.. code-block:: vim
call vam#ActivateAddons(['powerline'])
.. note::
If you use supplied :file:`powerline.vim` file to load powerline there are
additional configuration variables available: ``g:powerline_pycmd`` and
``g:powerline_pyeval``. First sets command used to load powerline: expected
values are ``"py"`` and ``"py3"``. Second sets function used in statusline,
expected values are ``"pyeval"`` and ``"py3eval"``.
If ``g:powerline_pycmd`` is set to the one of the expected values then
``g:powerline_pyeval`` will be set accordingly. If it is set to some other
value then you must also set ``g:powerline_pyeval``. Powerline will not
check that Vim is compiled with Python support if you set
``g:powerline_pycmd`` to an unexpected value.
These values are to be used to specify the only Python that is to be loaded
if you have both versions: Vim may disable loading one python version if
other was already loaded. They should also be used if you have two python
versions able to load simultaneously, but with powerline installed only for
python-3 version.
Shell prompts
-------------
.. note::
It is advised that you run ``powerline-daemon`` before using any of the
below solutions. To do this add
.. code-block:: bash
powerline-daemon -q
just before sourcing powerline bindings script or running
``powerline-setup``. Use ``|| true`` or equivalent if you run your
configuration with ``set -e`` because ``powerline-daemon`` will exit with
``1`` if daemon is already running.
Bash prompt
^^^^^^^^^^^
Add the following line to your :file:`bashrc`, where ``{repository_root}`` is
the absolute path to your Powerline installation directory:
.. code-block:: bash
. {repository_root}/powerline/bindings/bash/powerline.sh
Zsh prompt
^^^^^^^^^^
Add the following line to your :file:`zshrc`, where ``{repository_root}`` is the
absolute path to your Powerline installation directory:
.. code-block:: bash
. {repository_root}/powerline/bindings/zsh/powerline.zsh
Fish prompt
^^^^^^^^^^^
Add the following line to your :file:`config.fish`, where ``{repository_root}``
is the absolute path to your Powerline installation directory:
.. code-block:: bash
set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
powerline-setup
.. _tmux-statusline:
Busybox (ash), mksh and dash prompt
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
After launching busybox run the following command:
.. code-block:: bash
. {repository_root}/powerline/bindings/shell/powerline.sh
Mksh users may put this line into ``~/.mkshrc`` file. Dash users may use the
following in ``~/.profile``:
.. code-block:: bash
if test "x$0" != "x${0#dash}" ; then
export ENV={repository_root}/powerline/bindings/shell/powerline.sh
fi
.. note::
Dash users that already have ``$ENV`` defined should either put the ``.
…/shell/powerline.sh`` line in the ``$ENV`` file or create a new file which
will source (using ``.`` command) both former ``$ENV`` file and
:file:`powerline.sh` files and set ``$ENV`` to the path of this new file.
.. warning::
Job count is using some weird hack that uses signals and temporary files for
interprocess communication. It may be wrong sometimes. Not the case in mksh.
.. warning::
Busybox has two shells: ``ash`` and ``hush``. Second is known to segfault in
busybox 1.22.1 when using :file:`powerline.sh` script.
Tmux statusline
---------------
Add the following lines to your :file:`.tmux.conf`, where ``{repository_root}``
is the absolute path to your Powerline installation directory::
source "{repository_root}/powerline/bindings/tmux/powerline.conf"
.. note::
The availability of the ``powerline-config`` command is required for
powerline support. You may specify location of this script via
``$POWERLINE_CONFIG_COMMAND`` environment variable.
.. note::
It is advised that you run ``powerline-daemon`` before adding the above line
to tmux.conf. To do so add::
run-shell "powerline-daemon -q"
to :file:`.tmux.conf`.
IPython prompt
--------------
For IPython<0.11 add the following lines to your
:file:`.ipython/ipy_user_conf.py`::
# top
from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup
# main() function (assuming you launched ipython without configuration to
# create skeleton ipy_user_conf.py file):
powerline_setup()
For IPython>=0.11 add the following line to your :file:`ipython_config.py`
file in the profile you are using::
c.InteractiveShellApp.extensions = [
'powerline.bindings.ipython.post_0_11'
]
IPython=0.11* is not supported and does not work. IPython<0.10 was not
tested (not installable by pip).
Awesome widget
--------------
.. note:: Powerline currently only supports awesome 3.5.
.. note:: The Powerline widget will spawn a shell script that runs in the
background and updates the statusline with ``awesome-client``.
Add the following to your :file:`rc.lua`, where ``{repository_root}`` is the
absolute path to your Powerline installation directory:
.. code-block:: lua
package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
require('powerline')
Then add the ``powerline_widget`` to your ``wibox``:
.. code-block:: lua
right_layout:add(powerline_widget)
Qtile widget
------------
Add the following to your :file:`~/.config/qtile/config.py`:
.. code-block:: python
from powerline.bindings.qtile.widget import Powerline
screens = [
Screen(
top=bar.Bar([
# ...
Powerline(timeout=2),
# ...
],
),
),
]
I3 bar
------
.. note:: Until the patch is done in i3, you will need a custom ``i3bar`` build
called ``i3bgbar``. The source is available `here
<https://github.com/S0lll0s/i3bgbar>`_.
Add the following to your :file:`~/.i3/config`::
bar {
i3bar_command i3bgbar
status_command python /path/to/powerline/bindings/i3/powerline-i3.py
font pango:PowerlineFont 12
}
where ``i3bgbar`` may be replaced with the path to the custom i3bar binary and
``PowerlineFont`` is any system font with powerline support.

8
docs/source/segment-reference.rst Normal file
View File

@ -0,0 +1,8 @@
*****************
Segment reference
*****************
.. toctree::
:glob:
segment-reference/*

0
docs/source/segments/common.rst → docs/source/segment-reference/common.rst
View File

0
docs/source/segments/shell.rst → docs/source/segment-reference/shell.rst
View File

0
docs/source/segments/vim.rst → docs/source/segment-reference/vim.rst
View File

18
docs/source/tipstricks.rst → docs/source/tips-and-tricks.rst
View File

@ -1,6 +1,6 @@
************* ***************
Tips & Tricks Tips and tricks
************* ***************
Vim Vim
=== ===
@ -8,10 +8,10 @@ Vim
Fix terminal timeout when pressing escape Fix terminal timeout when pressing escape
----------------------------------------- -----------------------------------------
When you're pressing :kbd:`Escape` to leave insert mode in the terminal, it When you're pressing :kbd:`Escape` to leave insert mode in the terminal, it
will by default take a second or another keystroke to leave insert mode will by default take a second or another keystroke to leave insert mode
completely and update the statusline. If you find this annoying, you can add completely and update the statusline. If you find this annoying, you can add
the following snippet to your :file:`vimrc` to escape insert mode the following snippet to your :file:`vimrc` to escape insert mode
immediately: immediately:
.. code-block:: vim .. code-block:: vim
@ -28,11 +28,11 @@ immediately:
Useful settings Useful settings
--------------- ---------------
You may find the following vim settings useful when using the Powerline You may find the following vim settings useful when using the Powerline
statusline: statusline:
.. code-block:: vim .. code-block:: vim
set laststatus=2 " Always display the statusline in all windows set laststatus=2 " Always display the statusline in all windows
set noshowmode " Hide the default mode text (e.g. -- INSERT -- below the statusline) set noshowmode " Hide the default mode text (e.g. -- INSERT -- below the statusline)

8
docs/source/troubleshooting.rst Normal file
View File

@ -0,0 +1,8 @@
***************
Troubleshooting
***************
.. toctree::
Linux <troubleshooting/linux>
OS X <troubleshooting/osx>

3
docs/source/troubleshooting/linux.rst Normal file
View File

@ -0,0 +1,3 @@
************************
Troubleshooting on Linux
************************

3
docs/source/troubleshooting/osx.rst Normal file
View File

@ -0,0 +1,3 @@
***********************
Troubleshooting on OS X
***********************

15
docs/source/usage.rst Normal file
View File

@ -0,0 +1,15 @@
*****
Usage
*****
Application support matrix
--------------------------
Plugins
-------
.. toctree::
usage/shell-prompts
usage/wm-widgets
usage/other

6
docs/source/usage/other.rst Normal file
View File

@ -0,0 +1,6 @@
*************
Other plugins
*************
tmux statusline
---------------

15
docs/source/usage/shell-prompts.rst Normal file
View File

@ -0,0 +1,15 @@
*************
Shell prompts
*************
bash
----
zsh
---
fish
----
IPython
-------

9
docs/source/usage/wm-widgets.rst Normal file
View File

@ -0,0 +1,9 @@
**********************
Window manager widgets
**********************
Awesome
-------
Qtile
-----