tyler.durden/powerline
1
0
Fork 0
mirror of https://github.com/powerline/powerline.git synced 2025-07-24 22:36:01 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1260 from ZyX-I/doc-fixes

Browse Source 
Some documentation changes
This commit is contained in:
Nikolai Aleksandrovich Pavlov 2015-01-08 19:55:22 +03:00
commit 886c38c37b
18 changed files with 387 additions and 275 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
docs/source/configuration.rst
View File

@ -2,9 +2,10 @@
Configuration and customization Configuration and customization
******************************* *******************************
.. note:: **You DO NOT have to fork the main GitHub repo to personalize your .. note::
Powerline configuration!** Please read through the :ref:`quick-guide` for **Forking the main GitHub repo is not needed to personalize Powerline
a quick introduction to user configuration. 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 Powerline is configured with one main configuration file, and with separate
configuration files for themes and colorschemes. All configuration files are configuration files for themes and colorschemes. All configuration files are
@ -29,26 +30,27 @@ configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for
Linux users, and in :file:`~/.config/powerline` for OS X users. This usually Linux users, and in :file:`~/.config/powerline` for OS X users. This usually
corresponds to :file:`~/.config/powerline` on both platforms. corresponds to :file:`~/.config/powerline` on both platforms.
If you need per-instance configuration please refer to :ref:`Local configuration If per-instance configuration is needed please refer to :ref:`Local
overrides <local-configuration-overrides>`. configuration overrides <local-configuration-overrides>`.
.. note:: If you have multiple configuration files with the same name in .. note::
different directories then these files will be merged. Merging happens in Existing multiple configuration files that have the same name, but are placed
the following order: in different directories, will be merged. Merging happens in the following
order:
* :file:`{powerline_root}/powerline/config_files` is checked for * :file:`{powerline_root}/powerline/config_files` is checked for
configuration first. Configuration from this source has least priority. configuration first. Configuration from this source has least priority.
* :file:`$XDG_CONFIG_DIRS/powerline` directories are the next ones to check. * :file:`$XDG_CONFIG_DIRS/powerline` directories are the next ones to check.
Checking happens in the reversed order: directories mentioned last are Checking happens in the reversed order: directories mentioned last are
checked before directories mentioned first. Each new found file is merged checked before directories mentioned first. Each new found file is merged
with the result of previous merge. with the result of previous merge.
* :file:`$XDG_CONFIG_HOME/powerline` directory is the last to check. * :file:`$XDG_CONFIG_HOME/powerline` directory is the last to check.
Configuration from there has top priority. Configuration from there has top priority.
When merging configuration only dictionaries are merged and they are merged When merging configuration only dictionaries are merged and they are merged
recursively: keys from next file overrule those from the previous unless recursively: keys from next file overrule those from the previous unless
corresponding values are both dictionaries in which case these dictionaries corresponding values are both dictionaries in which case these dictionaries
are merged and key is assigned the result of the merge. are merged and key is assigned the result of the merge.
.. note:: Some configuration files (i.e. themes and colorschemes) have two level .. note:: Some configuration files (i.e. themes and colorschemes) have two level
of merging: first happens merging described above, second theme- or of merging: first happens merging described above, second theme- or

63
docs/source/configuration/local.rst
View File

@ -18,8 +18,8 @@ Vim configuration can be overridden using the following options:
``g:powerline_theme_overrides`` ``g:powerline_theme_overrides``
Dictionary mapping theme names to theme overrides, recursively merged with Dictionary mapping theme names to theme overrides, recursively merged with
contents of :file:`powerline/themes/vim/{key}.json`. Note that this way you contents of :file:`powerline/themes/vim/{key}.json`. Note that this way some
can’t redefine some value (e.g. segment) in list, only the whole list value (e.g. segment) in a list cannot be redefined, only the whole list
itself: only dictionaries are merged recursively. itself: only dictionaries are merged recursively.
``g:powerline_config_paths`` ``g:powerline_config_paths``
@ -179,16 +179,17 @@ this variant is used.
Sets directories where configuration should be read from. If present, no Sets directories where configuration should be read from. If present, no
default locations are searched for configuration. No expansions are default locations are searched for configuration. No expansions are
performed by powerline script itself, but zsh usually performs them on its performed by powerline script itself, but zsh usually performs them on its
own if you set variable without quotes: ``POWERLINE_CONFIG_PATHS=( ~/example own if variable without is set without quotes: ``POWERLINE_CONFIG_PATHS=(
)``. You should use array parameter or the usual colon-separated ~/example )``. In addition to arrays usual colon-separated “array” string
``POWERLINE_CONFIG_PATHS=$HOME/path1:$HOME/path2``. can be used: ``POWERLINE_CONFIG_PATHS=$HOME/path1:$HOME/path2``.
Ipython overrides Ipython overrides
================= =================
Ipython overrides depend on ipython version. Before ipython-0.11 you should pass Ipython overrides depend on ipython version. Before ipython-0.11 additional
additional keyword arguments to setup() function. After ipython-0.11 you should keyword arguments should be passed to setup() function. After ipython-0.11
use ``c.Powerline.KEY``. Supported ``KEY`` strings or keyword argument names: ``c.Powerline.KEY`` should be used. Supported ``KEY`` strings or keyword
argument names:
``config_overrides`` ``config_overrides``
Overrides options from :file:`powerline/config.json`. Should be a dictionary Overrides options from :file:`powerline/config.json`. Should be a dictionary
@ -202,41 +203,39 @@ use ``c.Powerline.KEY``. Supported ``KEY`` strings or keyword argument names:
``config_paths`` ``config_paths``
Sets directories where configuration should be read from. If present, no Sets directories where configuration should be read from. If present, no
default locations are searched for configuration. No expansions are default locations are searched for configuration. No expansions are
performed thus you cannot use paths starting with ``~/``. performed thus paths starting with ``~/`` cannot be used: use
:py:func:`os.path.expanduser`.
Prompt command Prompt command
============== ==============
In addition to the above configuration options you can use In addition to the above configuration options ``$POWERLINE_COMMAND``
``$POWERLINE_COMMAND`` environment variable to tell shell or tmux to use environment variable can be used to tell shell or tmux to use specific powerline
specific powerline implementation and ``$POWERLINE_CONFIG_COMMAND`` to tell zsh implementation and ``$POWERLINE_CONFIG_COMMAND`` to tell zsh or tmux where
or tmux where ``powerline-config`` script is located. This is mostly useful for ``powerline-config`` script is located. This is mostly useful for putting
putting powerline into different directory. powerline into different directory.
.. note:: .. note::
``$POWERLINE_COMMAND`` is always treated as one path in shell bindings, so ``$POWERLINE_COMMAND`` is always treated as one path in shell bindings, so
you may use paths with spaces in it. To specify additional arguments one may path with spaces in it may be used. To specify additional arguments one may
use ``$POWERLINE_COMMAND_ARGS``, but note that this variable exists for use ``$POWERLINE_COMMAND_ARGS``, but note that this variable exists for
testing purposes only and may be removed. One should use :ref:`Environment testing purposes only and may be removed. One should use :ref:`Environment
variable overrides <local-configuration-overrides-env>` instead. variable overrides <local-configuration-overrides-env>` instead.
If you want to disable prompt in shell, but still have tmux support or if you To disable prompt in shell, but still have tmux support or to disable tmux
want to disable tmux support you can use variables support environment variables ``$POWERLINE_NO_{SHELL}_PROMPT`` and
``$POWERLINE_NO_{SHELL}_PROMPT``/``$POWERLINE_NO_SHELL_PROMPT`` and ``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT`` can be used (substitute ``{SHELL}`` with
``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT``/``$POWERLINE_NO_SHELL_TMUX_SUPPORT`` the name of the shell (all-caps) that should be affected (e.g. ``BASH``) or use
(substitute ``{SHELL}`` with the name of the shell (all-caps) you want to all-inclusive ``SHELL`` that will disable support for all shells). These
disable support for (e.g. ``BASH``) or use all-inclusive ``SHELL`` that will variables have no effect after configuration script was sourced (in fish case:
disable support for all shells). These variables have no effect after after ``powerline-setup`` function was run). To disable specific feature support
configuration script was sourced (in fish case: after ``powerline-setup`` set one of these variables to some non-empty value.
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 In order to keep shell prompt, but avoid launching Python twice to get unused
python twice to get :ref:`above <config-themes-above>` lines you do not use in :ref:`above <config-themes-above>` lines in tcsh ``$POWERLINE_NO_TCSH_ABOVE`` or
tcsh you should set ``$POWERLINE_NO_TCSH_ABOVE`` or ``$POWERLINE_NO_SHELL_ABOVE`` variable should be set.
``$POWERLINE_NO_SHELL_ABOVE`` variable.
If you do not want to see additional space which is added to the right prompt in In order to remove additional space from the end of the right prompt in fish
fish in order to support multiline prompt you should set that was added in order to support multiline prompt ``$POWERLINE_NO_FISH_ABOVE``
``$POWERLINE_NO_FISH_ABOVE`` or ``$POWERLINE_NO_SHELL_ABOVE`` variables. or ``$POWERLINE_NO_SHELL_ABOVE`` variable should be set.

27
docs/source/configuration/reference.rst
View File

@ -24,7 +24,7 @@ Common configuration is a subdictionary that is a value of ``common`` key in
``term_truecolor`` ``term_truecolor``
Defines whether to output cterm indices (8-bit) or RGB colors (24-bit) 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 to the terminal emulator. See the :ref:`term-feature-support-matrix` for
information on whether your terminal emulator supports 24-bit colors. information on whether used terminal emulator supports 24-bit colors.
This variable is forced to be ``false`` if :ref:`term_escape_style This variable is forced to be ``false`` if :ref:`term_escape_style
<config-common-term_escape_style>` option is set to ``"fbterm"`` or if it is <config-common-term_escape_style>` option is set to ``"fbterm"`` or if it is
@ -55,7 +55,7 @@ Common configuration is a subdictionary that is a value of ``common`` key in
Tells powerline what to do with characters with East Asian Width Class Tells powerline what to do with characters with East Asian Width Class
Ambigious (such as Euro, Registered Sign, Copyright Sign, Greek Ambigious (such as Euro, Registered Sign, Copyright Sign, Greek
letters, Cyrillic letters). Valid values: any positive integer; it is letters, Cyrillic letters). Valid values: any positive integer; it is
suggested that you only set it to 1 (default) or 2. suggested that this option is only set it to 1 (default) or 2.
.. _config-common-watcher: .. _config-common-watcher:
@ -77,12 +77,11 @@ Common configuration is a subdictionary that is a value of ``common`` key in
``additional_escapes`` ``additional_escapes``
Valid for shell extensions, makes sense only if :ref:`term_truecolor Valid for shell extensions, makes sense only if :ref:`term_truecolor
<config-common-term_truecolor>` is enabled. Is to be set from command-line <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 Controls additional escaping that is needed for tmux/screen to work with
is needed for tmux/screen to work with terminal true color escape codes: terminal true color escape codes: normally tmux/screen prevent terminal
normally tmux/screen prevent terminal emulator from receiving these control emulator from receiving these control codes thus rendering powerline prompt
codes thus rendering powerline prompt colorless. Valid values: ``"tmux"``, colorless. Valid values: ``"tmux"``, ``"screen"``, ``null`` (default).
``"screen"``, ``null`` (default).
.. _config-common-paths: .. _config-common-paths:
@ -212,8 +211,8 @@ Color definitions
* A list of cterm color indicies. * A list of cterm color indicies.
* A list of hex color strings. * A list of hex color strings.
It is expected that you define gradients from least alert color to most It is expected that gradients are defined from least alert color to most
alert or use non-alert colors. alert or non-alert colors are used.
.. _config-colorschemes: .. _config-colorschemes:
@ -253,8 +252,8 @@ override those from each previous file. It is required that either
``attrs`` ``attrs``
List of attributes. Valid values are one or more of ``bold``, List of attributes. Valid values are one or more of ``bold``,
``italic`` and ``underline``. Note that some attributes may be ``italic`` and ``underline``. Note that some attributes may be
unavailable in some applications or terminal emulators. If you do not unavailable in some applications or terminal emulators. If no
need any attributes leave this empty. attributes are needed this list should be left empty.
#) a string (an alias): a name of existing group. This group’s definition #) a string (an alias): a name of existing group. This group’s definition
will be used when this color is requested. will be used when this color is requested.
@ -333,9 +332,7 @@ ascii Theme without any unicode characters at all
``dividers`` ``dividers``
Defines the dividers used in all Powerline extensions. This option Defines the dividers used in all Powerline extensions.
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 The ``hard`` dividers are used to divide segments with different
background colors, while the ``soft`` dividers are used to divide background colors, while the ``soft`` dividers are used to divide

4
docs/source/develop/extensions.rst
View File

@ -24,8 +24,8 @@ segments in some set of applications. Specifically this means
computing text width. computing text width.
This subclass must be placed directly in :file:`powerline/renderers` This subclass must be placed directly in :file:`powerline/renderers`
directory (if you are creating powerline extension for a set of applications directory (for powerline extensions developed for a set of applications use
use :file:`powerline/renderers/{ext}/*.py`) and named like ``ExtRenderer`` or :file:`powerline/renderers/{ext}/*.py`) and named like ``ExtRenderer`` or
``AppPromptRenderer``. For technical reasons the class itself must be ``AppPromptRenderer``. For technical reasons the class itself must be
referenced in ``renderer`` module attribute thus allowing only one renderer referenced in ``renderer`` module attribute thus allowing only one renderer
per one module. per one module.

2
docs/source/develop/listers.rst
View File

@ -4,7 +4,7 @@
Writing listers Writing listers
*************** ***************
Listers allow you to show some segments multiple times: once per each entity Listers provide a way to show some segments multiple times: once per each entity
(buffer, tabpage, etc) lister knows. They are functions which receive the (buffer, tabpage, etc) lister knows. They are functions which receive the
following arguments: following arguments:

2
docs/source/develop/local-themes.rst
View File

@ -32,7 +32,7 @@ arguments: matcher name (same as in :ref:`local_themes
<config-ext-local_themes>`) and dictionary with theme. This dictionary is merged <config-ext-local_themes>`) and dictionary with theme. This dictionary is merged
with :ref:`top theme <config-ext-top_theme>` and with :ref:`top theme <config-ext-top_theme>` and
:file:`powerline/themes/vim/__main__.json`. Note that if user already specified :file:`powerline/themes/vim/__main__.json`. Note that if user already specified
your matcher in his configuration file ``KeyError`` is raised. the matcher in his configuration file ``KeyError`` is raised.
Other local themes Other local themes
================== ==================

116
docs/source/develop/segments.rst
View File

@ -12,7 +12,7 @@ object it should receive the following arguments:
``pl`` ``pl``
A :py:class:`powerline.PowerlineLogger` instance. It must be used every time A :py:class:`powerline.PowerlineLogger` instance. It must be used every time
you need to log something. something needs to be logged.
``segment_info`` ``segment_info``
A dictionary. It is only received if callable has A dictionary. It is only received if callable has
@ -32,20 +32,21 @@ And also any other argument(s) specified by user in :ref:`args key
.. note:: .. note::
For powerline-lint to work properly the following things may be needed: For powerline-lint to work properly the following things may be needed:
#. If your segment is a :py:class:`powerline.segments.Segment` and used #. If segment is a :py:class:`powerline.segments.Segment` instance and used
arguments are scattered over multiple methods arguments are scattered over multiple methods
:py:meth:`powerline.segments.Segment.argspecobjs` should be overridden in :py:meth:`powerline.segments.Segment.argspecobjs` should be overridden in
subclass to tell powerline-lint which objects should be inspected for subclass to tell powerline-lint which objects should be inspected for
arguments. arguments.
#. If your segment takes some arguments that are never listed, but accessed #. If segment takes some arguments that are never listed, but accessed via
via ``kwargs.get()`` or you cannot use previous function for whatever ``kwargs.get()`` or previous function cannot be used for whatever reason
reason :py:meth:`powerline.segments.Segment.additional_args` should be :py:meth:`powerline.segments.Segment.additional_args` should be
overridden in subclass. overridden in subclass.
#. If you are expecting user to use one :ref:`name <config-themes-seg-name>` #. If user is expected to use one :ref:`name <config-themes-seg-name>` for
for multiple segments which cannot be linked to the segment function multiple segments which cannot be linked to the segment function
automatically by powerline-lint (e.g. because there are no instances of automatically by powerline-lint (e.g. because there are no instances of
the segments in question in the default configuration) you should use the segments in question in the default configuration)
:py:func:`powerline.lint.checks.register_common_name`. :py:func:`powerline.lint.checks.register_common_name` function should be
used.
Object representing segment may have the following attributes used by Object representing segment may have the following attributes used by
powerline: powerline:
@ -110,7 +111,7 @@ powerline:
.. warning:: .. warning::
“Amount of display cells” is *not* number of Unicode codepoints, string “Amount of display cells” is *not* number of Unicode codepoints, string
length, or byte count. It is suggested that your function should look length, or byte count. It is suggested that this function should look
something like ``return (' ' * amount) + segment['contents']`` where something like ``return (' ' * amount) + segment['contents']`` where
``' '`` may be replaced with anything that is known to occupy exactly ``' '`` may be replaced with anything that is known to occupy exactly
one display cell. one display cell.
@ -172,22 +173,23 @@ Detailed description of used dictionary keys:
Defaults to the name of the segment. Defaults to the name of the segment.
.. note:: .. note::
If you want to include your segment in powerline you must specify all If target is inclusion of the segment in powerline upstream all used
highlighting groups used in the segment documentation in the form:: highlighting groups must be specified in the segment documentation in the
form::
Highlight groups used: ``g1``[ or ``g2``]*[, ``g3`` (gradient)[ or ``g4``]*]*. Highlight groups used: ``g1``[ or ``g2``]*[, ``g3`` (gradient)[ or ``g4``]*]*.
I.e. use:: I.e. use::
Highlight groups used: ``foo_gradient`` (gradient) or ``foo``, ``bar``. Highlight groups used: ``foo_gradient`` (gradient) or ``foo``, ``bar``.
to specify that your segment uses *either* ``foo_gradient`` group or to specify that the segment uses *either* ``foo_gradient`` group or
``foo`` group *and* ``bar`` group meaning that ``powerline-lint`` will ``foo`` group *and* ``bar`` group meaning that ``powerline-lint`` will
check that at least one of the first two groups is defined (and if check that at least one of the first two groups is defined (and if
``foo_gradient`` is defined it must use at least one gradient color) and ``foo_gradient`` is defined it must use at least one gradient color) and
third group is defined as well. third group is defined as well.
You must specify all groups on one line. All groups must be specified on one line.
``divider_highlight_group`` ``divider_highlight_group``
Determines segment divider highlight group. Only applicable for soft Determines segment divider highlight group. Only applicable for soft
@ -195,13 +197,14 @@ Detailed description of used dictionary keys:
segments. segments.
.. note:: .. note::
If you want to include your segment in powerline you must specify used If target is inclusion of the segment in powerline upstream used divider
groups in the segment documentation in the form:: highlight group must be specified in the segment documentation in the
form::
Divider highlight group used: ``group``. Divider highlight group used: ``group``.
This text must not wrap and you are supposed to end all divider This text must not wrap and all divider highlight group names are
highlight group names with ``:divider``: e.g. ``cwd:divider``. supposed to end with ``:divider``: e.g. ``cwd:divider``.
``gradient_level`` ``gradient_level``
First and the only key that may not be specified in user configuration. It First and the only key that may not be specified in user configuration. It
@ -330,16 +333,19 @@ keys:
have ``__getitem__`` and ``get`` methods and nothing more. have ``__getitem__`` and ``get`` methods and nothing more.
.. warning:: .. warning::
You must not ever use ``os.environ``. If your segment is run in daemon ``os.environ`` must not ever be used:
you will get daemon’s environment which is not correct. If your segment
is run in Vim or in zsh with libzpython you will get Vim or zsh * If segment is run in the daemon this way it will get daemon’s
environment at python startup. environment which is not correct.
* If segment is run in Vim or in zsh with libzpython ``os.environ`` will
contain Vim or zsh environ *at the moment Python interpreter was
loaded*.
``getcwd`` ``getcwd``
Function that returns current working directory being called with no Function that returns current working directory being called with no
arguments. You must not use ``os.getcwd`` for the same reasons you must not arguments. ``os.getcwd`` must not be used for the same reasons the use of
use ``os.environ``, except that current working directory is valid in Vim ``os.environ`` is forbidden, except that current working directory is valid
and zsh (but not in daemon). in Vim and zsh (but not in daemon).
``home`` ``home``
Current home directory. May be false. Current home directory. May be false.
@ -352,36 +358,36 @@ Vim
Vim ``segment_info`` argument is a dictionary with the following keys: Vim ``segment_info`` argument is a dictionary with the following keys:
``window`` ``window``
``vim.Window`` object. You may obtain one using ``vim.current.window`` or ``vim.Window`` object. ``vim.current.window`` or ``vim.windows[number - 1]``
``vim.windows[number - 1]``. May be a false object, in which case you should may be used to obtain such object. May be a false object, in which case any
not use any of this objects’ properties. of this object’s properties must not be used.
``winnr`` ``winnr``
Window number. Same as ``segment_info['window'].number`` *assuming* Vim is Window number. Same as ``segment_info['window'].number`` *assuming* Vim is
new enough for ``vim.Window`` object to have ``number`` attribute. new enough for ``vim.Window`` object to have ``number`` attribute.
``window_id`` ``window_id``
Internal powerline window id, unique for each newly created window. You Internal powerline window id, unique for each newly created window. It is
should assume that this ID is hashable and supports equality comparison, but safe to assume that this ID is hashable and supports equality comparison,
you must not use any other assumptions about it. Currently uses integer but no other assumptions about it should be used. Currently uses integer
numbers incremented each time window is created. numbers incremented each time window is created.
``buffer`` ``buffer``
``vim.Buffer`` object. You may obtain one using ``vim.current.buffer``, ``vim.Buffer`` object. One may be obtained using ``vim.current.buffer``,
``segment_info['window'].buffer`` or ``vim.buffers[some_number]``. Note that ``segment_info['window'].buffer`` or ``vim.buffers[some_number]``. Note that
in the latter case depending on vim version ``some_number`` may be ``bufnr`` in the latter case depending on vim version ``some_number`` may be ``bufnr``
or the internal Vim buffer index which is *not* buffer number. For this or the internal Vim buffer index which is *not* buffer number. For this
reason to get ``vim.Buffer`` object other then stored in ``segment_info`` reason to get ``vim.Buffer`` object other then stored in ``segment_info``
dictionary you must iterate over ``vim.buffers`` and check their ``number`` dictionary iteration over ``vim.buffers`` and checking their ``number``
attributes. attributes should be performed.
``bufnr`` ``bufnr``
Buffer number. Buffer number.
``tabpage`` ``tabpage``
``vim.Tabpage`` object. You may obtain one using ``vim.current.tabpage`` or ``vim.Tabpage`` object. One may be obtained using ``vim.current.tabpage`` or
``vim.tabpages[number - 1]``. May be a false object, in which case you ``vim.tabpages[number - 1]``. May be a false object, in which case no
should not use any of this objects’ properties. object’s properties can be used.
``tabnr`` ``tabnr``
Tabpage number. Tabpage number.
@ -394,18 +400,18 @@ Vim ``segment_info`` argument is a dictionary with the following keys:
should be used to convert return values. should be used to convert return values.
.. note:: .. note::
Your segment generally should not assume that it is run for the current Segment generally should not assume that it is run for the current window,
window, current buffer or current tabpage. “Current window” and “current current buffer or current tabpage. “Current window” and “current buffer”
buffer” restrictions may be ignored if you use ``window_cached`` decorator, restrictions may be ignored if ``window_cached`` decorator is used, “current
“current tabpage” restriction may be safely ignored if you do not plan to tabpage” restriction may be safely ignored if segment is not supposed to be
ever see your segment in the tabline. used in tabline.
.. warning:: .. warning::
Powerline is being tested with vim-7.2 and will be tested with it until Powerline is being tested with vim-7.0.112 (some minor sanity check) and
travis changes used vim version. This means that you may not use most of the latest Vim. This means that most of the functionality like
functionality like ``vim.Window.number``, ``vim.*.vars``, ``vim.*.options`` ``vim.Window.number``, ``vim.*.vars``, ``vim.*.options`` or even ``dir(vim
or even ``dir(vim object)`` if you want your segment to be included in object)`` should be avoided in segments that want to be included in the
powerline. upstream.
Shell Shell
----- -----
@ -431,7 +437,7 @@ Shell
``renderer_arg`` ``renderer_arg``
Dictionary containing some keys that are additional arguments used by Dictionary containing some keys that are additional arguments used by
shell bindings. *You must not use this attribute directly*: all shell bindings. *This attribute must not be used directly*: all
arguments from this dictionary are merged with ``segment_info`` arguments from this dictionary are merged with ``segment_info``
dictionary. Known to have at least the following keys: dictionary. Known to have at least the following keys:

24
docs/source/installation.rst
View File

@ -47,8 +47,8 @@ PyPI under the ``powerline-status`` name:
pip install powerline-status pip install powerline-status
is the preferred method because this will get you the latest release. To get is the preferred method because this will get the latest release. To get current
current development version development version
.. code-block:: sh .. code-block:: sh
@ -71,7 +71,7 @@ will have to be done (:file:`~/.local/bin` should be replaced with some path
present in ``$PATH``). present in ``$PATH``).
.. note:: .. note::
If your ISP blocks git protocol for some reason github also provides ``ssh`` If ISP blocks git protocol for some reason github also provides ``ssh``
(``git+ssh://git@github.com/powerline/powerline``) and ``https`` (``git+ssh://git@github.com/powerline/powerline``) and ``https``
(``git+https://github.com/powerline/powerline``) protocols. ``git`` protocol (``git+https://github.com/powerline/powerline``) protocols. ``git`` protocol
should be the fastest, but least secure one though. should be the fastest, but least secure one though.
@ -80,12 +80,15 @@ Fonts installation
================== ==================
Powerline uses several special glyphs to get the arrow effect and some custom 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 symbols for developers. This requires having either a symbol font or a patched
a patched font on your system. Your terminal emulator must also support either font installed in the system. Used application (e.g. terminal emulator) must
patched fonts or fontconfig for Powerline to work properly. also either be configured to use patched fonts (in some cases even support it
because custom glyphs live in private use area which some applications reserve
for themselves) or support fontconfig for powerline to work properly with
powerline-specific glyphs.
You can also enable :ref:`24-bit color support <config-common-term_truecolor>` :ref:`24-bit color support <config-common-term_truecolor>` may be enabled if
if your terminal emulator supports it (see :ref:`the terminal emulator support used terminal emulator supports it (see :ref:`the terminal emulator support
matrix <usage-terminal-emulators>`). matrix <usage-terminal-emulators>`).
There are basically two ways to get powerline glyphs displayed: use There are basically two ways to get powerline glyphs displayed: use
@ -100,9 +103,8 @@ Patched fonts
This method is the fallback method and works for every terminal, with the This method is the fallback method and works for every terminal, with the
exception of :ref:`rxvt-unicode <tips-and-tricks-urxvt>`. exception of :ref:`rxvt-unicode <tips-and-tricks-urxvt>`.
Download the font of your choice from `powerline-fonts`_. If you can’t find Download the font from `powerline-fonts`_. If preferred font can’t be found in
your preferred font in the `powerline-fonts`_ repo, you’ll have to patch your the `powerline-fonts`_ repo, then patching the preferred font is needed instead.
own font instead.
.. _powerline-fonts: https://github.com/powerline/fonts .. _powerline-fonts: https://github.com/powerline/fonts

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

@ -4,7 +4,7 @@ Installation on Linux
The following distribution-specific packages are officially supported, and they The following distribution-specific packages are officially supported, and they
provide an easy way of installing and upgrading Powerline. The packages will provide an easy way of installing and upgrading Powerline. The packages will
automatically do most of the configuration for you. automatically do most of the configuration.
* `Arch Linux (AUR), Python 2 version <https://aur.archlinux.org/packages/python2-powerline-git/>`_ * `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/>`_ * `Arch Linux (AUR), Python 3 version <https://aur.archlinux.org/packages/python-powerline-git/>`_
@ -14,11 +14,11 @@ automatically do most of the configuration for you.
<https://packages.debian.org/search?keywords=powerline&searchon=names&suite=all&section=all>`_ <https://packages.debian.org/search?keywords=powerline&searchon=names&suite=all&section=all>`_
to get more information. to get more information.
If you’re running a distribution without an official package you’ll have to If used distribution does not have an official package installation guide below
follow the installation guide below: should be followed:
1. Install Python 3.2+ or Python 2.6+ with ``pip``. This step is 1. Install Python 3.2+, Python 2.6+ or PyPy and ``pip`` with ``setuptools``.
distribution-specific, so no commands provided. This step is distribution-specific, so no commands provided.
2. Install Powerline using one of the following commands: 2. Install Powerline using one of the following commands:
.. code-block:: sh .. code-block:: sh
@ -36,10 +36,11 @@ follow the installation guide below:
.. note:: Due to the naming conflict with an unrelated project powerline is .. note:: Due to the naming conflict with an unrelated project powerline is
named ``powerline-status`` in PyPI. named ``powerline-status`` in PyPI.
.. note:: If you are powerline developer you should be aware that ``pip install .. note::
--editable`` does not currently fully work. If you Powerline developers should be aware that``pip install --editable`` does
install powerline this way you will be missing ``powerline`` executable and not currently fully work. Installation performed this way are missing
need to symlink it. It will be located in ``scripts/powerline``. ``powerline`` executable that needs to be symlinked. It will be located in
``scripts/powerline``.
Fonts installation Fonts installation
================== ==================
@ -47,9 +48,9 @@ Fonts installation
Fontconfig Fontconfig
---------- ----------
This method only works on Linux. It’s the recommended method if your This method only works on Linux. It’s the second recommended method if terminal
terminal emulator supports it as you don’t have to patch any fonts, and it emulator supports it as patching fonts is not needed, and it generally works
generally works well with any coding font. with any coding font.
#. Download the latest version of the symbol font and fontconfig file:: #. Download the latest version of the symbol font and fontconfig file::
@ -61,8 +62,8 @@ generally works well with any coding font.
mv PowerlineSymbols.otf ~/.fonts/ mv PowerlineSymbols.otf ~/.fonts/
#. Update font cache for the path you moved the font to (you may need to be #. Update font cache for the path the font was moved to (root priveleges may be
root to update the cache for system-wide paths):: needed to update cache for the system-wide paths)::
fc-cache -vf ~/.fonts/ fc-cache -vf ~/.fonts/
@ -72,37 +73,38 @@ generally works well with any coding font.
mv 10-powerline-symbols.conf ~/.config/fontconfig/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 If custom symbols still cannot be seen then try closing all instances of the
terminal emulator. You may need to restart X for the changes to take terminal emulator. Restarting X may be needed for the changes to take effect.
effect.
If you *still* can’t see the custom symbols, double-check that you have If custom symbols *still* can’t be seen, double-check that the font have been
installed the font to a valid X font path, and that you have installed the installed to a valid X font path, and that the fontconfig file was installed to
fontconfig file to a valid fontconfig path. Alternatively try to install a valid fontconfig path. Alternatively try to install a :ref:`patched font
a :ref:`patched font <installation-patched-fonts>`. <installation-patched-fonts>`.
Patched font installation Patched font installation
------------------------- -------------------------
After downloading font you should do the following: This is the preferred method, but it is not always available because not all
fonts were patched and not all fonts *can* be patched due to licensing issues.
After downloading font the following should be done:
#. Move the patched font to a valid X font path. Valid font paths can be #. Move the patched font to a valid X font path. Valid font paths can be
listed with ``xset q``:: listed with ``xset q``::
mv 'MyFont for Powerline.otf' ~/.fonts/ mv 'SomeFont for Powerline.otf' ~/.fonts/
#. Update font cache for the path you moved the font to (you may need to be #. Update font cache for the path the font was moved to (root priveleges may be
root to update the cache for system-wide paths):: needed for updating font cache for some paths)::
fc-cache -vf ~/.fonts/ fc-cache -vf ~/.fonts/
After installing the patched font you need to update Gvim or your terminal After installing patched font terminal emulator, GVim or whatever application
emulator to use the patched font. The correct font usually ends with *for powerline should work with must be configured to use the patched font. The
Powerline*. correct font usually ends with *for Powerline*.
If you can’t see the custom symbols, please close all instances of your If custom symbols cannot be seen then try closing all instances of the terminal
terminal emulator. You may need to restart X for the changes to take emulator. X server may need to be restarted for the changes to take effect.
effect.
If you *still* can’t see the custom symbols, double-check that you have If custom symbols *still* can’t be seen then double-check that the font have
installed the font to a valid X font path. been installed to a valid X font path.

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

@ -11,16 +11,16 @@ Python package
sudo port select python python27-apple sudo port select python python27-apple
. You may use homebrew for this:: . Homebrew may be used here::
brew install python brew install python
. .
.. note:: .. note::
In case you want or have to use ``powerline.sh`` socat-based client you In case :file:`powerline.sh` as a client ``socat`` and ``coreutils`` need
should also install GNU env named ``genv``. This may be achieved by to be installed. ``coreutils`` may be installed using ``brew install
running ``brew install coreutils``. coreutils``.
2. Install Powerline using one of the following commans: 2. Install Powerline using one of the following commans:
@ -45,16 +45,16 @@ Python package
``powerline-status`` in PyPI. ``powerline-status`` in PyPI.
.. note:: .. note::
If you are powerline developer you should be aware that ``pip install Powerline developers should be aware that``pip install --editable`` does
--editable`` does not currently fully work. If you install powerline this not currently fully work. Installation performed this way are missing
way you will be missing ``powerline`` executable and need to symlink it. ``powerline`` executable that needs to be symlinked. It will be located in
It will be located in ``scripts/powerline``. ``scripts/powerline``.
Vim installation Vim installation
================ ================
Any terminal vim version with Python 3.2+ or Python 2.6+ support should work, 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:: but MacVim users need to install it using the following command::
brew install macvim --env-std --override-system-vim brew install macvim --env-std --override-system-vim
@ -64,6 +64,6 @@ Fonts installation
Install downloaded patched font by double-clicking the font file in Finder, then Install downloaded patched font by double-clicking the font file in Finder, then
clicking :guilabel:`Install this font` in the preview window. clicking :guilabel:`Install this font` in the preview window.
After installing the patched font you need to update MacVim or your terminal After installing the patched font MacVim or terminal emulator (whatever
emulator to use the patched font. The correct font usually ends with *for application powerline should work with) need to be configured to use the patched
Powerline*. font. The correct font usually ends with *for Powerline*.

27
docs/source/usage.rst
View File

@ -8,16 +8,15 @@ Application-specific requirements
Vim plugin requirements Vim plugin requirements
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
The vim plugin requires a vim version with Python support compiled in. You The vim plugin requires a vim version with Python support compiled in. Presense
can check if your vim supports Python by running ``vim --version | grep of Python support in Vim can be checked by running ``vim --version | grep
+python``. +python``.
If your vim version doesn’t have support for Python, you’ll have to compile If Python support is absent then Vim needs to be compiled with it. To do this
it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if use ``--enable-pythoninterp`` :file:`./configure` flag (Python 3 uses
you want Python 3 support instead). Note that this also requires the related ``--enable-python3interp`` flag instead). Note that this also requires the
Python headers to be installed on your system. Please consult your related Python headers to be installed. Please consult distribution’s
distribution’s documentation for details on how to compile and install documentation for details on how to compile and install packages.
packages.
Vim version 7.4 or newer is recommended for performance reasons, but Powerline Vim version 7.4 or newer is recommended for performance reasons, but Powerline
is known to work on vim-7.0.112 (some segments may not work though as it was not is known to work on vim-7.0.112 (some segments may not work though as it was not
@ -28,13 +27,13 @@ actually tested).
Terminal emulator requirements Terminal emulator requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Powerline uses several special glyphs to get the arrow effect and some Powerline uses several special glyphs to get the arrow effect and some custom
custom symbols for developers. This requires that you either have a symbol symbols for developers. This requires either a symbol font or a patched font
font or a patched font on your system. Your terminal emulator must also installed. Used terminal emulator must also support either patched fonts or
support either patched fonts or fontconfig for Powerline to work properly. fontconfig for Powerline to work properly.
You can also enable :ref:`24-bit color support <config-common-term_truecolor>` :ref:`24-bit color support <config-common-term_truecolor>` can also be enabled
if your terminal emulator supports it. if terminal emulator supports it.
.. table:: Application/terminal emulator feature support matrix .. table:: Application/terminal emulator feature support matrix
:name: term-feature-support-matrix :name: term-feature-support-matrix

79
docs/source/usage/other.rst
View File

@ -15,32 +15,35 @@ If installed using pip just add
python powerline_setup() python powerline_setup()
python del powerline_setup python del powerline_setup
(replace ``python`` with ``python3`` if appropriate) to your :file:`vimrc`. (replace ``python`` with ``python3`` if appropriate) to the :file:`vimrc`.
If you just cloned the repository add the following line to your :file:`vimrc`, If the repository was just cloned the following line needs to be added to the
where ``{repository_root}`` is the absolute path to your Powerline installation :file:`vimrc`:
directory:
.. code-block:: vim .. code-block:: vim
set rtp+={repository_root}/powerline/bindings/vim set rtp+={repository_root}/powerline/bindings/vim
If you’re using pathogen and don’t want Powerline functionality in any other where ``{repository_root}`` is the absolute path to the Powerline installation
applications, simply add Powerline as a bundle and point the path above to the directory.
Powerline bundle directory, e.g.
``~/.vim/bundle/powerline/powerline/bindings/vim``.
With Vundle you may instead use If pathogen is used and Powerline functionality is not needed outside of Vim
then it is possible to simply add Powerline as a bundle and point the path above
to the Powerline bundle directory, e.g.
:file:`~/.vim/bundle/powerline/powerline/bindings/vim`.
Vundle and NeoBundle users may instead use
.. code-block:: vim .. code-block:: vim
Bundle 'powerline/powerline', {'rtp': 'powerline/bindings/vim/'} Bundle 'powerline/powerline', {'rtp': 'powerline/bindings/vim/'}
(replace ``Bundle`` with ``NeoBundle`` for NeoBundle). (NeoBundle users need ``NeoBundle`` in place of ``Bundle``, otherwise setup is
the same).
For vim-addon-manager it is even easier since you don’t need to write this big Vim-addon-manager setup is even easier because it is not needed to write this
path or install anything by hand: ``powerline`` is installed and run just like big path or install anything by hand: ``powerline`` can be installed and
any other plugin using activated just like any other plugin using
.. code-block:: vim .. code-block:: vim
@ -48,17 +51,16 @@ any other plugin using
.. warning:: .. warning::
*Never* install powerline with pathogen/VAM/Vundle/NeoBundle *and* with pip. *Never* install powerline with pathogen/VAM/Vundle/NeoBundle *and* with pip.
If you want powerline functionality in vim and other applications use If powerline functionality is needed in applications other then Vim then
system-wide installation if your system has powerline package, pip-only or system-wide installation (in case used OS distribution has powerline
``pip install --editable`` kind of installation performed on the repository package), pip-only or ``pip install --editable`` kind of installation
installed by Vim plugin manager. performed on the repository installed by Vim plugin manager should be used.
If you have installed powerline with pip and with some of Vim package No issues are accepted in powerline issue tracker for double pip/non-pip
managers do never report any errors to powerline bug tracker, especially installations, especially if these issues occur after update.
errors occurring after updates.
.. note:: .. note::
If you use supplied :file:`powerline.vim` file to load powerline there are If supplied :file:`powerline.vim` file is used to load powerline there are
additional configuration variables available: ``g:powerline_pycmd`` and additional configuration variables available: ``g:powerline_pycmd`` and
``g:powerline_pyeval``. First sets command used to load powerline: expected ``g:powerline_pyeval``. First sets command used to load powerline: expected
values are ``"py"`` and ``"py3"``. Second sets function used in statusline, values are ``"py"`` and ``"py3"``. Second sets function used in statusline,
@ -66,32 +68,32 @@ any other plugin using
If ``g:powerline_pycmd`` is set to the one of the expected values then 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 ``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 value then ``g:powerline_pyeval`` must also be set. Powerline will not check
check that Vim is compiled with Python support if you set that Vim is compiled with Python support if ``g:powerline_pycmd`` is set to
``g:powerline_pycmd`` to an unexpected value. an unexpected value.
These values are to be used to specify the only Python that is to be loaded 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 if both versions are present: Vim may disable loading one python version if
other was already loaded. They should also be used if you have two python other was already loaded. They should also be used if two python versions
versions able to load simultaneously, but with powerline installed only for are able to load simultaneously, but powerline was installed only for
python-3 version. python-3 version.
Tmux statusline Tmux statusline
=============== ===============
Add the following lines to your :file:`.tmux.conf`, where ``{repository_root}`` Add the following lines to :file:`.tmux.conf`, where ``{repository_root}`` is
is the absolute path to your Powerline installation directory:: the absolute path to the Powerline installation directory::
source "{repository_root}/powerline/bindings/tmux/powerline.conf" source "{repository_root}/powerline/bindings/tmux/powerline.conf"
.. note:: .. note::
The availability of the ``powerline-config`` command is required for The availability of the ``powerline-config`` command is required for
powerline support. You may specify location of this script via powerline support. DLlocation of this script may be specified via
``$POWERLINE_CONFIG_COMMAND`` environment variable. ``$POWERLINE_CONFIG_COMMAND`` environment variable.
.. note:: .. note::
It is advised that you run ``powerline-daemon`` before adding the above line It is advised to run ``powerline-daemon`` before adding the above line to
to tmux.conf. To do so add:: tmux.conf. To do so add::
run-shell "powerline-daemon -q" run-shell "powerline-daemon -q"
@ -100,18 +102,21 @@ is the absolute path to your Powerline installation directory::
IPython prompt IPython prompt
============== ==============
For IPython<0.11 add the following lines to your For IPython<0.11 add the following lines to :file:`.ipython/ipy_user_conf.py`:
:file:`.ipython/ipy_user_conf.py`::
.. code-block:: Python
# top # top
from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup
# main() function (assuming you launched ipython without configuration to # main() function (assuming ipython was launched without configuration to
# create skeleton ipy_user_conf.py file): # create skeleton ipy_user_conf.py file):
powerline_setup() powerline_setup()
For IPython>=0.11 add the following line to your :file:`ipython_config.py` For IPython>=0.11 add the following line to :file:`ipython_config.py` file in
file in the profile you are using:: the used profile:
.. code-block:: Python
c.InteractiveShellApp.extensions = [ c.InteractiveShellApp.extensions = [
'powerline.bindings.ipython.post_0_11' 'powerline.bindings.ipython.post_0_11'

30
docs/source/usage/shell-prompts.rst
View File

@ -4,19 +4,19 @@ Shell prompts
.. note:: .. note::
Powerline daemon is not run automatically by any of my bindings. It is Powerline daemon is not run automatically by any of my bindings. It is
advised that you add advised to add
.. code-block:: bash .. code-block:: bash
powerline-daemon -q powerline-daemon -q
before any other powerline-related code in your shell configuration file. before any other powerline-related code in the shell configuration file.
Bash prompt Bash prompt
=========== ===========
Add the following line to your :file:`bashrc`, where ``{repository_root}`` is Add the following line to the :file:`bashrc`, where ``{repository_root}`` is the
the absolute path to your Powerline installation directory: absolute path to the Powerline installation directory:
.. code-block:: bash .. code-block:: bash
@ -34,21 +34,21 @@ the absolute path to your Powerline installation directory:
POWERLINE_BASH_SELECT=1 POWERLINE_BASH_SELECT=1
. {repository_root}/powerline/bindings/bash/powerline.sh . {repository_root}/powerline/bindings/bash/powerline.sh
in your bash configuration file. Without ``POWERLINE_BASH_*`` variables PS2 in the bash configuration file. Without ``POWERLINE_BASH_*`` variables PS2
and PS3 prompts are computed exactly once at bash startup. and PS3 prompts are computed exactly once at bash startup.
.. warning:: .. warning::
At maximum bash continuation PS2 and select PS3 prompts are computed each At maximum bash continuation PS2 and select PS3 prompts are computed each
time main PS1 prompt is computed. Do not expect it to work properly if you time main PS1 prompt is computed. Thus putting e.g. current time into PS2 or
e.g. put current time there. PS3 prompt will not work as expected.
At minimum they are computed once on startup. At minimum they are computed once on startup.
Zsh prompt Zsh prompt
========== ==========
Add the following line to your :file:`zshrc`, where ``{repository_root}`` is the Add the following line to the :file:`zshrc`, where ``{repository_root}`` is the
absolute path to your Powerline installation directory: absolute path to the Powerline installation directory:
.. code-block:: bash .. code-block:: bash
@ -57,8 +57,8 @@ absolute path to your Powerline installation directory:
Fish prompt Fish prompt
=========== ===========
Add the following line to your :file:`config.fish`, where ``{repository_root}`` Add the following line to :file:`config.fish`, where ``{repository_root}`` is
is the absolute path to your Powerline installation directory: the absolute path to the Powerline installation directory:
.. code-block:: bash .. code-block:: bash
@ -73,13 +73,13 @@ Rcsh prompt
Powerline supports Plan9 rc reimplementation *by Byron Rakitzis* packaged by Powerline supports Plan9 rc reimplementation *by Byron Rakitzis* packaged by
many \*nix distributions. To use it add many \*nix distributions. To use it add
.. code-black:: bash .. code-block:: bash
. {repository_root}/powerline/bindings/rc/powerline.rc . {repository_root}/powerline/bindings/rc/powerline.rc
to your :file:`rcrc` file (usually :file:`~/.rcrc`) and make sure you start your to :file:`rcrc` file (usually :file:`~/.rcrc`) and make sure ``rc`` is startead
shell as a login shell (with ``-l`` argument): otherwise this configuration file as a login shell (with ``-l`` argument): otherwise this configuration file is
is not read. not read.
.. warning:: .. warning::
Original Plan9 shell and its \*nix port are not supported because they are Original Plan9 shell and its \*nix port are not supported because they are

17
docs/source/usage/wm-widgets.rst
View File

@ -10,15 +10,15 @@ Awesome widget
.. note:: The Powerline widget will spawn a shell script that runs in the .. note:: The Powerline widget will spawn a shell script that runs in the
background and updates the statusline with ``awesome-client``. background and updates the statusline with ``awesome-client``.
Add the following to your :file:`rc.lua`, where ``{repository_root}`` is the Add the following to :file:`rc.lua`, where ``{repository_root}`` is the absolute
absolute path to your Powerline installation directory: path to Powerline installation directory:
.. code-block:: lua .. code-block:: lua
package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua' package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
require('powerline') require('powerline')
Then add the ``powerline_widget`` to your ``wibox``: Then add the ``powerline_widget`` to ``wibox``:
.. code-block:: lua .. code-block:: lua
@ -27,7 +27,7 @@ Then add the ``powerline_widget`` to your ``wibox``:
Qtile widget Qtile widget
============ ============
Add the following to your :file:`~/.config/qtile/config.py`: Add the following to :file:`~/.config/qtile/config.py`:
.. code-block:: python .. code-block:: python
@ -47,11 +47,12 @@ Add the following to your :file:`~/.config/qtile/config.py`:
I3 bar I3 bar
====== ======
.. note:: Until the patch is done in i3, you will need a custom ``i3bar`` build .. note::
called ``i3bgbar``. The source is available `here Until the patch is done in i3 a custom ``i3bar`` build called ``i3bgbar`` is
<https://github.com/S0lll0s/i3bgbar>`_. needed. The source is available `in S0lll0s/i3bgbar github repository
<https://github.com/S0lll0s/i3bgbar>`_.
Add the following to your :file:`~/.i3/config`:: Add the following to :file:`~/.i3/config`::
bar { bar {
i3bar_command i3bgbar i3bar_command i3bgbar

22
powerline/commands/config.py
View File

@ -43,7 +43,12 @@ class ConfigArgParser(argparse.ArgumentParser):
def get_argparser(ArgumentParser=ConfigArgParser): def get_argparser(ArgumentParser=ConfigArgParser):
parser = ArgumentParser(description='Script used to obtain powerline configuration.') parser = ArgumentParser(description='Script used to obtain powerline configuration.')
parser.add_argument('-p', '--config-path', action='append', metavar='PATH', help='Path to configuration directory. If it is present then configuration files will only be seeked in the provided path. May be provided multiple times to search in a list of directories.') parser.add_argument(
'-p', '--config-path', action='append', metavar='PATH',
help='Path to configuration directory. If it is present '
'then configuration files will only be seeked in the provided path. '
'May be provided multiple times to search in a list of directories.'
)
subparsers = parser.add_subparsers() subparsers = parser.add_subparsers()
tmux_parser = subparsers.add_parser('tmux', help='Tmux-specific commands') tmux_parser = subparsers.add_parser('tmux', help='Tmux-specific commands')
tmux_parser.add_argument( tmux_parser.add_argument(
@ -51,7 +56,10 @@ def get_argparser(ArgumentParser=ConfigArgParser):
choices=tuple(TMUX_ACTIONS.values()), choices=tuple(TMUX_ACTIONS.values()),
metavar='ACTION', metavar='ACTION',
type=(lambda v: TMUX_ACTIONS.get(v)), type=(lambda v: TMUX_ACTIONS.get(v)),
help='If action is `source\' then version-specific tmux configuration files are sourced, if it is `setenv\' then special (prefixed with `_POWERLINE\') tmux global environment variables are filled with data from powerline configuration.' help='If action is `source\' then version-specific tmux configuration '
'files are sourced, if it is `setenv\' then special '
'(prefixed with `_POWERLINE\') tmux global environment variables '
'are filled with data from powerline configuration.'
) )
shell_parser = subparsers.add_parser('shell', help='Shell-specific commands') shell_parser = subparsers.add_parser('shell', help='Shell-specific commands')
@ -60,14 +68,20 @@ def get_argparser(ArgumentParser=ConfigArgParser):
choices=tuple(SHELL_ACTIONS.values()), choices=tuple(SHELL_ACTIONS.values()),
type=(lambda v: SHELL_ACTIONS.get(v)), type=(lambda v: SHELL_ACTIONS.get(v)),
metavar='ACTION', metavar='ACTION',
help='If action is `command\' then preferred powerline command is output, if it is `uses\' then powerline-config script will exit with 1 if specified component is disabled and 0 otherwise.', help='If action is `command\' then preferred powerline command is '
'output, if it is `uses\' then powerline-config script will exit '
'with 1 if specified component is disabled and 0 otherwise.',
) )
shell_parser.add_argument( shell_parser.add_argument(
'component', 'component',
nargs='?', nargs='?',
choices=('tmux', 'prompt'), choices=('tmux', 'prompt'),
metavar='COMPONENT', metavar='COMPONENT',
help='Only applicable for `uses\' subcommand: makes `powerline-config\' exit with 0 if specific component is enabled and with 1 otherwise. `tmux\' component stands for tmux bindings (e.g. those that notify tmux about current directory changes), `prompt\' component stands for shell prompt.' help='Only applicable for `uses\' subcommand: makes `powerline-config\' '
'exit with 0 if specific component is enabled and with 1 otherwise. '
'`tmux\' component stands for tmux bindings '
'(e.g. those that notify tmux about current directory changes), '
'`prompt\' component stands for shell prompt.'
) )
shell_parser.add_argument( shell_parser.add_argument(
'-s', '--shell', '-s', '--shell',

10
powerline/commands/daemon.py
View File

@ -6,7 +6,15 @@ import argparse
def get_argparser(ArgumentParser=argparse.ArgumentParser): def get_argparser(ArgumentParser=argparse.ArgumentParser):
parser = ArgumentParser(description='Daemon that improves powerline performance.') parser = ArgumentParser(description='Daemon that improves powerline performance.')
parser.add_argument('--quiet', '-q', action='store_true', help='Without other options: do not complain about already running powerline-daemon instance. Will still exit with 1. With `--kill\' and `--replace\': do not show any messages. With `--foreground\': ignored. Does not silence exceptions in any case.') parser.add_argument(
'--quiet', '-q', action='store_true',
help='Without other options: do not complain about already running '
'powerline-daemon instance. '
'Will still exit with 1. '
'With `--kill\' and `--replace\': do not show any messages. '
'With `--foreground\': ignored. '
'Does not silence exceptions in any case.'
)
parser.add_argument('--socket', '-s', help='Specify socket which will be used for connecting to daemon.') parser.add_argument('--socket', '-s', help='Specify socket which will be used for connecting to daemon.')
exclusive_group = parser.add_mutually_exclusive_group() exclusive_group = parser.add_mutually_exclusive_group()
exclusive_group.add_argument('--kill', '-k', action='store_true', help='Kill an already running instance.') exclusive_group.add_argument('--kill', '-k', action='store_true', help='Kill an already running instance.')

14
powerline/commands/lint.py
View File

@ -6,6 +6,16 @@ import argparse
def get_argparser(ArgumentParser=argparse.ArgumentParser): def get_argparser(ArgumentParser=argparse.ArgumentParser):
parser = ArgumentParser(description='Powerline configuration checker.') parser = ArgumentParser(description='Powerline configuration checker.')
parser.add_argument('-p', '--config-path', action='append', metavar='PATH', help='Paths where configuration should be checked, in order. You must supply all paths necessary for powerline to work, checking partial (e.g. only user overrides) configuration is not supported.') parser.add_argument(
parser.add_argument('-d', '--debug', action='store_const', const=True, help='Display additional information. Used for debugging `powerline-lint\' itself, not for debugging configuration.') '-p', '--config-path', action='append', metavar='PATH',
help='Paths where configuration should be checked, in order. You must '
'supply all paths necessary for powerline to work, '
'checking partial (e.g. only user overrides) configuration '
'is not supported.'
)
parser.add_argument(
'-d', '--debug', action='store_const', const=True,
help='Display additional information. Used for debugging '
'`powerline-lint\' itself, not for debugging configuration.'
)
return parser return parser

91
powerline/commands/main.py
View File

@ -65,21 +65,88 @@ def int_or_sig(s):
def get_argparser(ArgumentParser=argparse.ArgumentParser): def get_argparser(ArgumentParser=argparse.ArgumentParser):
parser = ArgumentParser(description='Powerline prompt and statusline script.') parser = ArgumentParser(description='Powerline prompt and statusline script.')
parser.add_argument('ext', nargs=1, help='Extension: application for which powerline command is launched (usually `shell\' or `tmux\').') parser.add_argument(
parser.add_argument('side', nargs='?', choices=('left', 'right', 'above', 'aboveleft'), help='Side: `left\' and `right\' represent left and right side respectively, `above\' emits lines that are supposed to be printed just above the prompt and `aboveleft\' is like concatenating `above\' with `left\' with the exception that only one Python instance is used in this case.') 'ext', nargs=1,
help='Extension: application for which powerline command is launched '
'(usually `shell\' or `tmux\').'
)
parser.add_argument(
'side', nargs='?', choices=('left', 'right', 'above', 'aboveleft'),
help='Side: `left\' and `right\' represent left and right side '
'respectively, `above\' emits lines that are supposed to be printed '
'just above the prompt and `aboveleft\' is like concatenating '
'`above\' with `left\' with the exception that only one Python '
'instance is used in this case.'
)
parser.add_argument( parser.add_argument(
'-r', '--renderer-module', metavar='MODULE', type=str, '-r', '--renderer-module', metavar='MODULE', type=str,
help='Renderer module. Usually something like `.bash\' or `.zsh\', is supposed to be set only in shell-specific bindings file.' help='Renderer module. Usually something like `.bash\' or `.zsh\' '
'(with leading dot) which is `powerline.renderers.{ext}{MODULE}\', '
'may also be full module name (must contain at least one dot or '
'end with a dot in case it is top-level module) or '
'`powerline.renderers\' submodule (in case there are no dots).'
)
parser.add_argument(
'-w', '--width', type=int,
help='Maximum prompt with. Triggers truncation of some segments.'
)
parser.add_argument(
'--last-exit-code', metavar='INT', type=int_or_sig,
help='Last exit code.'
)
parser.add_argument(
'--last-pipe-status', metavar='LIST', default='',
type=lambda s: [int_or_sig(status) for status in s.split()],
help='Like above, but is supposed to contain space-separated array '
'of statuses, representing exit statuses of commands in one pipe.'
)
parser.add_argument(
'--jobnum', metavar='INT', type=int,
help='Number of jobs.'
)
parser.add_argument(
'-c', '--config-override', metavar='KEY.KEY=VALUE', type=arg_to_unicode,
action='append',
help='Configuration overrides for `config.json\'. Is translated to a '
'dictionary and merged with the dictionary obtained from actual '
'JSON configuration: KEY.KEY=VALUE is translated to '
'`{"KEY": {"KEY": VALUE}}\' and then merged recursively. '
'VALUE may be any JSON value, values that are not '
'`null\', `true\', `false\', start with digit, `{\', `[\' '
'are treated like strings. If VALUE is omitted '
'then corresponding key is removed.'
)
parser.add_argument(
'-t', '--theme-override', metavar='THEME.KEY.KEY=VALUE', type=arg_to_unicode,
action='append',
help='Like above, but theme-specific. THEME should point to '
'an existing and used theme to have any effect, but it is fine '
'to use any theme here.'
)
parser.add_argument(
'-R', '--renderer-arg',
metavar='KEY=VAL', type=arg_to_unicode, action='append',
help='Like above, but provides argument for renderer. Is supposed '
'to be used only by shell bindings to provide various data like '
'last-exit-code or last-pipe-status (they are not using '
'`--renderer-arg\' for historical resons: `--renderer-arg\' '
'was added later).'
)
parser.add_argument(
'-p', '--config-path', action='append', metavar='PATH',
help='Path to configuration directory. If it is present then '
'configuration files will only be seeked in the provided path. '
'May be provided multiple times to search in a list of directories.'
)
parser.add_argument(
'--socket', metavar='ADDRESS', type=str,
help='Socket address to use in daemon clients. Is always UNIX domain '
'socket on linux and file socket on Mac OS X. Not used here, '
'present only for compatibility with other powerline clients. '
'This argument must always be the first one and be in a form '
'`--socket ADDRESS\': no `=\' or short form allowed '
'(in other powerline clients, not here).'
) )
parser.add_argument('-w', '--width', type=int, help='Maximum prompt with. Triggers truncation of some segments.')
parser.add_argument('--last-exit-code', metavar='INT', type=int_or_sig, help='Last exit code.')
parser.add_argument('--last-pipe-status', metavar='LIST', default='', type=lambda s: [int_or_sig(status) for status in s.split()], help='Like above, but is supposed to contain space-separated array of statuses, representing exit statuses of commands in one pipe.')
parser.add_argument('--jobnum', metavar='INT', type=int, help='Number of jobs.')
parser.add_argument('-c', '--config-override', metavar='KEY.KEY=VALUE', type=arg_to_unicode, action='append', help='Configuration overrides for `config.json\'. Is translated to a dictionary and merged with the dictionary obtained from actual JSON configuration: KEY.KEY=VALUE is translated to `{"KEY": {"KEY": VALUE}}\' and then merged recursively. VALUE may be any JSON value, values that are not `null\', `true\', `false\', start with digit, `{\', `[\' are treated like strings. If VALUE is omitted then corresponding key is removed.')
parser.add_argument('-t', '--theme-override', metavar='THEME.KEY.KEY=VALUE', type=arg_to_unicode, action='append', help='Like above, but theme-specific. THEME should point to an existing and used theme to have any effect, but it is fine to use any theme here.')
parser.add_argument('-R', '--renderer-arg', metavar='KEY=VAL', type=arg_to_unicode, action='append', help='Like above, but provides argument for renderer. Is supposed to be used only by shell bindings to provide various data like last-exit-code or last-pipe-status (they are not using `--renderer-arg\' for historical resons: `--renderer-arg\' was added later).')
parser.add_argument('-p', '--config-path', action='append', metavar='PATH', help='Path to configuration directory. If it is present then configuration files will only be seeked in the provided path. May be provided multiple times to search in a list of directories.')
parser.add_argument('--socket', metavar='ADDRESS', type=str, help='Socket address to use in daemon clients. Is always UNIX domain socket on linux and file socket on Mac OS X. Not used here, present only for compatibility with other powerline clients. This argument must always be the first one and be in a form `--socket ADDRESS\': no `=\' or short form allowed (in other powerline clients, not here).')
return parser return parser