Adding upstream version 2.7.upstream/2.7upstream

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

3 files changed, 309 insertions, 0 deletions

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
new file mode 100644
index 0000000..eb40ed0
--- /dev/null
+++ b/docs/source/installation.rst
@@ -0,0 +1,132 @@
+************
+Installation
+************
+
+Generic requirements
+====================
+
+* Python 2.6 or later, 3.2 or later, PyPy 2.0 or later, PyPy3 2.3 or later. It 
+  is the only non-optional requirement.
+
+  .. warning:
+     It is highly advised to use UCS-4 version of Python because UCS-2 version 
+     uses significantly slower text processing (length determination and 
+     non-printable character replacement) functions due to the need of 
+     supporting unicode characters above U+FFFF which are represented as 
+     surrogate pairs. This price will be paid even if configuration has no such 
+     characters.
+
+* C compiler. Required to build powerline client on linux. If it is not present 
+  then powerline will fall back to shell script or python client.
+* ``socat`` program. Required for shell variant of client which runs a bit 
+  faster than python version of the client, but still slower than C version.
+* ``psutil`` python package. Required for some segments like cpu_percent. Some 
+  segments have linux-only fallbacks for ``psutil`` functionality.
+* ``hglib`` python package *and* mercurial executable. Required to work with
+  mercurial repositories.
+* ``pygit2`` python package or ``git`` executable. Required to work with ``git`` 
+  repositories.
+* ``bzr`` python package (note: *not* standalone executable). Required to work 
+  with bazaar repositories.
+* ``pyuv`` python package. Required for :ref:`libuv-based watcher 
+  <config-common-watcher>` to work.
+* ``i3ipc`` python package. Required for i3wm bindings and segments.
+* ``xrandr`` program. Required for the multi-monitor lemonbar binding and the 
+  :py:func:`powerline.listers.i3wm.output_lister`.
+
+.. note::
+    Until bazaar supports Python-3 or PyPy powerline will not support
+    repository information when running in these interpreters.
+
+.. _repository-root:
+
+.. note::
+   When using ``pip``, the ``{repository_root}`` directory referenced in 
+   documentation may be found using ``pip show powerline-status``. In the output 
+   of ``pip show`` there is a line like ``Location: {path}``, that ``{path}`` is 
+   ``{repository_root}``. Unless it is ``--editable`` installation this is only 
+   applicable for ``{repository_root}/powerline/…`` paths: something like 
+   ``{repository_root}/scripts/powerline-render`` is not present.
+
+   When using other packages referenced paths may not exist, in this case refer 
+   to package documentation.
+
+Pip installation
+================
+
+Due to a naming conflict with an unrelated project powerline is available on 
+PyPI under the ``powerline-status`` name:
+
+.. code-block:: sh
+
+    pip install powerline-status
+
+is the preferred method because this will get the latest release. To get current 
+development version
+
+.. code-block:: sh
+
+    pip install --user git+git://github.com/powerline/powerline
+
+may be used. If powerline was already checked out into some directory
+
+.. code-block:: sh
+
+    pip install --user --editable={path_to_powerline}
+
+is useful, but note that in this case ``pip`` will not install ``powerline`` 
+executable and something like
+
+.. code-block:: sh
+
+    ln -s {path_to_powerline}/scripts/powerline ~/.local/bin
+
+will have to be done (:file:`~/.local/bin` should be replaced with some path 
+present in ``$PATH``).
+
+.. note::
+    If ISP blocks git protocol for some reason github also provides ``ssh`` 
+    (``git+ssh://git@github.com/powerline/powerline``) and ``https`` 
+    (``git+https://github.com/powerline/powerline``) protocols. ``git`` protocol 
+    should be the fastest, but least secure one though.
+
+Fonts installation
+==================
+
+Powerline uses several special glyphs to get the arrow effect and some custom 
+symbols for developers. This requires having either a symbol font or a patched 
+font installed in the system. The used application (e.g. terminal emulator) must 
+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.
+
+:ref:`24-bit color support <config-common-term_truecolor>` may be enabled if 
+used terminal emulator supports it (see :ref:`the terminal emulator support 
+matrix <usage-terminal-emulators>`).
+
+There are basically two ways to get powerline glyphs displayed: use 
+:file:`PowerlineSymbols.otf` font as a fallback for one of the existing fonts or 
+install a patched font.
+
+.. _installation-patched-fonts:
+
+Patched fonts
+-------------
+
+This method is the fallback method and works for every terminal.
+
+Download the font from `powerline-fonts`_. If preferred font can’t be found in 
+the `powerline-fonts`_ repo, then patching the preferred font is needed instead.
+
+.. _powerline-fonts: https://github.com/powerline/fonts
+
+After downloading this font refer to platform-specific instructions.
+
+Installation on various platforms
+=================================
+
+.. toctree::
+
+   Linux <installation/linux>
+   OS X <installation/osx>
diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst
new file mode 100644
index 0000000..15ec606
--- /dev/null
+++ b/docs/source/installation/linux.rst
@@ -0,0 +1,110 @@
+*********************
+Installation on Linux
+*********************
+
+The following distribution-specific packages are officially supported, and they 
+provide an easy way of installing and upgrading Powerline. The packages will 
+automatically do most of the configuration.
+
+* `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
+* Powerline package is available for Debian starting from Wheezy (via `backports 
+  <https://packages.debian.org/wheezy-backports/powerline>`_). Use `search 
+  <https://packages.debian.org/search?keywords=powerline&searchon=names&suite=all&section=all>`_ 
+  to get more information.
+
+If used distribution does not have an official package installation guide below 
+should be followed:
+
+1. Install Python 3.2+, Python 2.6+ or PyPy and ``pip`` with ``setuptools``. 
+   This step is distribution-specific, so no commands provided.
+2. Install Powerline using one of the following commands:
+
+   .. code-block:: sh
+
+      pip install --user powerline-status
+
+   will get the latest release version and
+
+   .. code-block:: sh
+
+      pip install --user git+git://github.com/powerline/powerline
+
+   will get the latest development version.
+
+   .. note:: Due to the naming conflict with an unrelated project powerline is
+      named ``powerline-status`` in PyPI.
+
+   .. note::
+      Powerline developers should be aware that``pip install --editable`` does 
+      not currently fully work. Installation performed this way are missing 
+      ``powerline`` executable that needs to be symlinked. It will be located in 
+      ``scripts/powerline``.
+
+Fonts installation
+==================
+
+Fontconfig
+----------
+
+This method only works on Linux. It’s the second recommended method if terminal 
+emulator supports it as patching fonts is not needed, and it generally works 
+with any coding font.
+
+#. Download the latest version of the symbol font and fontconfig file::
+
+      wget https://github.com/powerline/powerline/raw/develop/font/PowerlineSymbols.otf
+      wget https://github.com/powerline/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 ~/.local/share/fonts/
+
+#. Update font cache for the path the font was moved to (root priveleges may be 
+   needed to update cache for the system-wide paths)::
+
+      fc-cache -vf ~/.local/share/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 custom symbols still cannot be seen then try closing all instances of the 
+terminal emulator. Restarting X may be needed for the changes to take effect.
+
+If custom symbols *still* can’t be seen, double-check that the font have been 
+installed to a valid X font path, and that the fontconfig file was installed to 
+a valid fontconfig path. Alternatively try to install a :ref:`patched font 
+<installation-patched-fonts>`.
+
+Patched font installation
+-------------------------
+
+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 
+   listed with ``xset q``::
+
+      mv 'SomeFont for Powerline.otf' ~/.local/share/fonts/
+
+#. Update font cache for the path the font was moved to (root privileges may be 
+   needed for updating font cache for some paths)::
+
+      fc-cache -vf ~/.local/share/fonts/
+
+After installing patched font terminal emulator, GVim or whatever application 
+powerline should work with must be configured to use the patched font. The 
+correct font usually ends with *for Powerline*.
+
+If custom symbols cannot be seen then try closing all instances of the terminal 
+emulator. X server may need to be restarted for the changes to take effect.
+
+If custom symbols *still* can’t be seen then double-check that the font have 
+been installed to a valid X font path.
diff --git a/docs/source/installation/osx.rst b/docs/source/installation/osx.rst
new file mode 100644
index 0000000..e520348
--- /dev/null
+++ b/docs/source/installation/osx.rst
@@ -0,0 +1,67 @@
+********************
+Installation on OS X
+********************
+
+Python package
+==============
+
+1. Install a proper Python version (see `issue #39 
+   <https://github.com/powerline/powerline/issues/39>`_ for a discussion 
+   regarding the required Python version on OS X)::
+
+       sudo port select python python27-apple
+
+   Homebrew may be used here::
+
+       brew install python
+
+   .. note::
+      In case :file:`powerline.sh` as a client ``socat`` and ``coreutils`` need 
+      to be installed. ``coreutils`` may be installed using ``brew install 
+      coreutils``.
+
+2. Install Powerline using one of the following commands:
+
+   .. code-block:: sh
+
+       pip install --user powerline-status
+
+   will get current release version and
+
+   .. code-block:: sh
+
+       pip install --user git+git://github.com/powerline/powerline
+
+   will get latest development version.
+
+   .. warning::
+      When using ``brew install`` to install Python one must not supply
+      ``--user`` flag to ``pip``.
+
+   .. note::
+      Due to the naming conflict with an unrelated project powerline is named 
+      ``powerline-status`` in PyPI.
+
+   .. note::
+      Powerline developers should be aware that ``pip install --editable`` does 
+      not currently fully work. Installation performed this way are missing 
+      ``powerline`` executable that needs to be symlinked. 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 MacVim users need to install it using the following command::
+
+    brew install macvim --env-std --with-override-system-vim
+
+Fonts installation
+==================
+
+To install patched font double-click the font file in Finder, then click 
+:guilabel:`Install this font` in the preview window.
+
+After installing the patched font MacVim or terminal emulator (whatever 
+application powerline should work with) need to be configured to use the patched 
+font. The correct font usually ends with *for Powerline*.