Adding upstream version 2.8.1.upstream/2.8.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 470 insertions, 0 deletions

diff --git a/docs/source/usage/other.rst b/docs/source/usage/other.rst
new file mode 100644
index 0000000..ff0ccae
--- /dev/null
+++ b/docs/source/usage/other.rst
@@ -0,0 +1,224 @@
+*************
+Other plugins
+*************
+
+.. _vim-vimrc:
+
+Vim statusline
+==============
+
+If installed using pip just add
+
+.. code-block:: vim
+
+    python from powerline.vim import setup as powerline_setup
+    python powerline_setup()
+    python del powerline_setup
+
+(replace ``python`` with ``python3`` if appropriate) to the :file:`vimrc`.
+
+.. note::
+   Status line will not appear by default when there is only a single window
+   displayed. Run ``:h 'laststatus'`` in Vim for more information.
+
+If the repository was just cloned the following line needs to be added to the 
+:file:`vimrc`:
+
+.. code-block:: vim
+
+   set rtp+={repository_root}/powerline/bindings/vim
+
+where ``{repository_root}`` is the absolute path to the Powerline installation 
+directory (see :ref:`repository root <repository-root>`).
+
+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
+
+    Bundle 'powerline/powerline', {'rtp': 'powerline/bindings/vim/'}
+
+(NeoBundle users need ``NeoBundle`` in place of ``Bundle``, otherwise setup is 
+the same).
+
+Vim-addon-manager setup is even easier because it is not needed to write this 
+big path or install anything by hand: ``powerline`` can be installed and 
+activated just like any other plugin using
+
+.. code-block:: vim
+
+    call vam#ActivateAddons(['powerline'])
+
+.. warning::
+    *Never* install powerline with pathogen/VAM/Vundle/NeoBundle *and* with pip. 
+    If powerline functionality is needed in applications other then Vim then 
+    system-wide installation (in case used OS distribution has powerline 
+    package), pip-only or ``pip install --editable`` kind of installation 
+    performed on the repository installed by Vim plugin manager should be used.
+
+    No issues are accepted in powerline issue tracker for double pip/non-pip 
+    installations, especially if these issues occur after update.
+
+.. note::
+    If supplied :file:`powerline.vim` file is used 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 ``g:powerline_pyeval`` must also be set. Powerline will not check 
+    that Vim is compiled with Python support if ``g:powerline_pycmd`` is set to 
+    an unexpected value.
+
+    These values are to be used to specify the only Python that is to be loaded 
+    if both versions are present: Vim may disable loading one python version if 
+    other was already loaded. They should also be used if two python versions 
+    are able to load simultaneously, but powerline was installed only for 
+    python-3 version.
+
+Tmux statusline
+===============
+
+Add the following lines to :file:`.tmux.conf`, where ``{repository_root}`` is 
+the absolute path to the Powerline installation directory (see :ref:`repository 
+root <repository-root>`)::
+
+   source "{repository_root}/powerline/bindings/tmux/powerline.conf"
+
+.. note::
+    The availability of the ``powerline-config`` command is required for 
+    powerline support. The location of this script may be specified via 
+    the ``$POWERLINE_CONFIG_COMMAND`` environment variable.
+
+.. note::
+    It is advised to run ``powerline-daemon`` before adding the above line to 
+    tmux.conf. To do so add::
+
+        run-shell "powerline-daemon -q"
+
+    to :file:`.tmux.conf`.
+
+.. warning::
+    Segments which depend on current working directory (e.g. 
+    :py:func:`powerline.segments.common.vcs.branch`) require also setting up 
+    :ref:`shell bindings <usage-shell>`. It is not required to use powerline 
+    shell prompt, :ref:`components setting <config-ext-components>` allows to 
+    set up only powerline bindings for tmux without altering your prompt. 
+    Without setting up shell bindings powerline will use current working 
+    directory of *tmux server* which is probably not what you need.
+
+    Segments which depend on environment like 
+    :py:func:`powerline.segments.common.env.virtualenv` will not work at all 
+    (i.e. they will use environment of the tmux server), tracking environment 
+    changes is going to slow down shell a lot.
+
+    In any case it is suggested to avoid both kinds of segments in tmux 
+    :ref:`themes <config-themes>` because even support for tracking current 
+    directory is very limited:
+
+    #. It works only in shell. Should you e.g. run Vim and run ``:cd`` there you 
+       will get current working directory from shell.
+    #. It works only in local shell and requires configuring it.
+    #. Some shells are not supported at all.
+
+IPython prompt
+==============
+
+For IPython>=7.0, add the following line to
+:file:`~/.ipython/profile_default/ipython_config.py` file in the used profile:
+
+
+.. code-block:: Python
+
+    from powerline.bindings.ipython.since_7 import PowerlinePrompts
+    c.TerminalInteractiveShell.prompts_class = PowerlinePrompts
+
+.. note::
+    If certain graphical/colored elements are not showing, make sure `c.TerminalInteractiveShell.simple_prompt`
+    is set to `False` in your config. 
+    Setting ``simple_prompt`` to False after IPython-5.0 is required regardless 
+    of whether you use ``c.InteractiveShellApp.extensions`` setting or 
+    ``c.TerminalInteractiveShell.prompts_class``. But you probably already have 
+    this line because ``simple_prompt`` is set to ``False`` by default and IPython
+    is not very useful without it.
+
+For IPython>=5.0 and <7.0 it is suggested to use
+
+.. code-block:: Python
+
+    from powerline.bindings.ipython.since_5 import PowerlinePrompts
+    c = get_config()
+    c.TerminalInteractiveShell.simple_prompt = False
+    c.TerminalInteractiveShell.prompts_class = PowerlinePrompts
+    
+
+    
+For IPython>=5.0 and <7.0 you may use the below set up, but it is deprecated.    
+For IPython>=0.11 add the following line to
+:file:`~/.ipython/profile_default/ipython_config.py` file in the used profile:
+
+.. code-block:: Python
+
+    c = get_config()
+    c.InteractiveShellApp.extensions = [
+        'powerline.bindings.ipython.post_0_11'
+    ]
+
+For IPython<0.11 add the following lines to :file:`.ipython/ipy_user_conf.py`:
+
+.. code-block:: Python
+
+    # top
+    from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup
+
+    # main() function (assuming ipython was launched without configuration to 
+    # create skeleton ipy_user_conf.py file):
+    powerline_setup()
+
+
+IPython=0.11* is not supported and does not work. IPython<0.10 was not 
+tested (not installable by pip).
+
+.. _pdb-prompt:
+
+PDB prompt
+==========
+
+To use Powerline with PDB prompt you need to use custom class. Inherit your 
+class from :py:class:`pdb.Pdb` and decorate it with 
+:py:func:`powerline.bindings.pdb.use_powerline_prompt`:
+
+.. code-block:: Python
+
+   import pdb
+
+   from powerline.bindings.pdb import use_powerline_prompt
+
+   @use_powerline_prompt
+   class MyPdb(pdb.Pdb):
+       pass
+
+   MyPdb.run('some.code.to.debug()')
+
+. Alternatively you may use
+
+.. code-block:: bash
+
+   python -mpowerline.bindings.pdb path/to/script.py
+
+just like you used ``python -m pdb``.
+
+.. note:
+   If you are using Python-2.6 you need to use ``python 
+   -mpowerline.bindings.pdb.__main__``, not what is shown above.
+
+.. warning:
+   Using PyPy (not PyPy3) forces ASCII-only prompts. In other cases unicode 
+   characters are allowed, even if you use `pdbpp 
+   <https://pypi.python.org/pypi/pdbpp>`_.
diff --git a/docs/source/usage/shell-prompts.rst b/docs/source/usage/shell-prompts.rst
new file mode 100644
index 0000000..1ddb0a1
--- /dev/null
+++ b/docs/source/usage/shell-prompts.rst
@@ -0,0 +1,144 @@
+.. _usage-shell:
+
+*************
+Shell prompts
+*************
+
+.. note::
+    Powerline daemon is not run automatically by any of my bindings. It is 
+    advised to add
+
+    .. code-block:: bash
+
+        powerline-daemon -q
+
+    before any other powerline-related code in the shell configuration file.
+
+Bash prompt
+===========
+
+Add the following line to the :file:`bashrc`, where ``{repository_root}`` is the 
+absolute path to the Powerline installation directory (see :ref:`repository root 
+<repository-root>`):
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/bash/powerline.sh
+
+.. note::
+    Since without powerline daemon bash bindings are very slow PS2 
+    (continuation) and PS3 (select) prompts are not set up. Thus it is advised 
+    to use
+
+    .. code-block:: bash
+
+       powerline-daemon -q
+       POWERLINE_BASH_CONTINUATION=1
+       POWERLINE_BASH_SELECT=1
+       . {repository_root}/powerline/bindings/bash/powerline.sh
+
+    in the bash configuration file. Without ``POWERLINE_BASH_*`` variables PS2 
+    and PS3 prompts are computed exactly once at bash startup.
+
+.. warning::
+    At maximum bash continuation PS2 and select PS3 prompts are computed each 
+    time main PS1 prompt is computed. Thus putting e.g. current time into PS2 or 
+    PS3 prompt will not work as expected.
+
+    At minimum they are computed once on startup.
+
+Zsh prompt
+==========
+
+Add the following line to the :file:`zshrc`, where ``{repository_root}`` is the 
+absolute path to the Powerline installation directory (see :ref:`repository root 
+<repository-root>`):
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/zsh/powerline.zsh
+
+Fish prompt
+===========
+
+Add the following line to :file:`config.fish`, where ``{repository_root}`` is 
+the absolute path to the Powerline installation directory (see :ref:`repository 
+root <repository-root>`):
+
+.. code-block:: bash
+
+   set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish"
+   powerline-setup
+
+.. warning:: Fish is supported only starting from version 2.1.
+
+Rcsh prompt
+===========
+
+Powerline supports Plan9 rc reimplementation *by Byron Rakitzis* packaged by 
+many \*nix distributions. To use it add
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/rc/powerline.rc
+
+(``{repository_root}`` is the absolute path to the Powerline installation 
+directory, see :ref:`repository root <repository-root>`) to :file:`rcrc` file 
+(usually :file:`~/.rcrc`) and make sure ``rc`` is started as a login shell (with 
+``-l`` argument): otherwise this configuration file is not read.
+
+.. warning::
+   Original Plan9 shell and its \*nix port are not supported because they are 
+   missing ``prompt`` special function (it is being called once before each 
+   non-continuation prompt). Since powerline could not support shell without 
+   this or equivalent feature some other not-so-critical features of that port 
+   were used.
+
+Busybox (ash), mksh and dash prompt
+=====================================
+
+After launching busybox run the following command:
+
+.. code-block:: bash
+
+   . {repository_root}/powerline/bindings/shell/powerline.sh
+
+where ``{repository_root}`` is the absolute path to the Powerline installation 
+directory (see :ref:`repository root <repository-root>`).
+
+Mksh users may put this line into ``~/.mkshrc`` file. Dash users may use the 
+following in ``~/.profile``:
+
+.. code-block:: bash
+
+    if test "$0" != "${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::
+    Mksh users have to set ``$POWERLINE_SHELL_CONTINUATION`` and 
+    ``$POWERLINE_SHELL_SELECT`` to 1 to get PS2 and PS3 (continuation and 
+    select) prompts support respectively: as command substitution is not 
+    performed in these shells for these prompts they are updated once each time 
+    PS1 prompt is displayed which may be slow.
+
+    It is also known that while PS2 and PS3 update is triggered at PS1 update it 
+    is *actually performed* only *next* time PS1 is displayed which means that 
+    PS2 and PS3 prompts will be outdated and may be incorrect for this reason.
+
+    Without these variables PS2 and PS3 prompts will be set once at startup. 
+    This only touches mksh users: busybox and dash both have no such problem.
+
+.. 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.
diff --git a/docs/source/usage/wm-widgets.rst b/docs/source/usage/wm-widgets.rst
new file mode 100644
index 0000000..204c008
--- /dev/null
+++ b/docs/source/usage/wm-widgets.rst
@@ -0,0 +1,102 @@
+**********************
+Window manager widgets
+**********************
+
+Awesome widget
+==============
+
+.. note:: Powerline currently only supports awesome 3.5 and 4+.
+
+.. 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 :file:`rc.lua`, where ``{repository_root}`` is the absolute 
+path to Powerline installation directory (see :ref:`repository root 
+<repository-root>`):
+
+.. code-block:: lua
+
+   package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua'
+   require('powerline')
+
+Then add the ``powerline_widget`` to ``wibox``:
+
+.. code-block:: lua
+
+   -- awesome3.5
+   right_layout:add(powerline_widget)
+   
+   -- awesome4+
+   s.mywibox:setup {
+   ...
+     { -- Right widgets
+       ...
+       powerline_widget,
+     },
+   }
+
+Qtile widget
+============
+
+Add the following to :file:`~/.config/qtile/config.py`:
+
+.. code-block:: python
+
+   from libqtile.bar import Bar
+   from libqtile.config import Screen
+   from libqtile.widget import Spacer
+
+   from powerline.bindings.qtile.widget import PowerlineTextBox
+
+   screens = [
+       Screen(
+           top=Bar([
+                   PowerlineTextBox(update_interval=2, side='left'),
+                   Spacer(),
+                   PowerlineTextBox(update_interval=2, side='right'),
+               ],
+               35 # width
+           ),
+       ),
+   ]
+
+.. _lemonbar-usage:
+
+lemonbar (formerly bar-aint-recursive)
+======================================
+
+To run the bar simply start the binding script:
+
+    python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py
+
+You can specify options to be passed to ``lemonbar`` after ``--``, like so:
+
+    python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py --height 16 -- -f "Source Code Pro for Powerline-9"
+
+to run with i3, simply ``exec`` this in the i3 config file and set the ``--i3`` switch:
+
+    exec python /path/to/powerline/bindings/lemonbar/powerline-lemonbar.py --i3
+
+Running the binding in i3-mode will require `i3ipc <https://github.com/acrisci/i3ipc-python>`_
+(or the outdated `i3-py <https://github.com/ziberna/i3-py>`_).
+
+See the `lemonbar documentation <https://github.com/LemonBoy/bar>`_ for more 
+information and options.
+
+All ``powerline-lemonbar.py`` arguments:
+
+.. automan:: powerline.commands.lemonbar
+   :prog: powerline-lemonbar.py
+   :minimal: true
+
+I3 bar
+======
+
+Add the following to :file:`~/.config/i3/config`::
+
+    bar {
+        status_command python /path/to/powerline/bindings/i3/powerline-i3.py
+        font pango:PowerlineFont 12
+    }
+
+where ``PowerlineFont`` is any system font with powerline support.