diff options
Diffstat (limited to 'docs/source/troubleshooting')
| -rw-r--r-- | docs/source/troubleshooting/linux.rst | 78 | ||||
| -rw-r--r-- | docs/source/troubleshooting/osx.rst | 71 |
2 files changed, 149 insertions, 0 deletions
diff --git a/docs/source/troubleshooting/linux.rst b/docs/source/troubleshooting/linux.rst new file mode 100644 index 0000000..e0493c6 --- /dev/null +++ b/docs/source/troubleshooting/linux.rst @@ -0,0 +1,78 @@ +************************ +Troubleshooting on Linux +************************ + +I can’t see any fancy symbols, what’s wrong? +-------------------------------------------- + +* Make sure that you’ve configured gvim or your terminal emulator to use + a patched font. +* You need to set your ``LANG`` and ``LC_*`` environment variables to + a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro’s + documentation for information about setting these variables correctly. +* Make sure that vim is compiled with the ``--with-features=big`` flag. +* If you’re using rxvt-unicode make sure that it’s compiled with the + ``--enable-unicode3`` flag. +* If you’re using xterm make sure you have told it to work with unicode. You may + need ``-u8`` command-line argument, ``uxterm`` shell wrapper that is usually + shipped with xterm for this or ``xterm*utf8`` property set to ``1`` or ``2`` + in ``~/.Xresources`` (applied with ``xrdb``). Note that in case ``uxterm`` is + used configuration is done via ``uxterm*…`` properties and not ``xterm*…``. + + In any case the only absolute requirement is launching xterm with UTF-8 + locale. +* If you are using bitmap font make sure that + :file:`/etc/fonts/conf.d/70-no-bitmaps.conf` does not exist. If it does check + out your distribution documentation to find a proper way to remove it (so that + it won’t reappear after update). E.g. in Gentoo this is:: + + eselect fontconfig disable 70-no-bitmaps.conf + + (currently this only removes the symlink from :file:`/etc/fonts/conf.d`). Also + check out that no other fontconfig file does not have ``rejectfont`` tag that + tells fontconfig to disable bitmap fonts (they are referenced as not + scalable). + +The fancy symbols look a bit blurry or “off”! +--------------------------------------------- + +* Make sure that you have patched all variants of your font (i.e. both the + regular and the bold font files). + +I am seeing strange blocks in place of playing/paused/stopped signs +------------------------------------------------------------------- + +If you are using ``powerline_unicode7`` :ref:`top-level theme +<config-common-default_top_theme>` then symbols for player segments are taken +from U+23F4–U+23FA range which is missing from most fonts. You may fix the issue +by using `Symbola <http://users.teilar.gr/~g1951d/>`_ font (or any other font +which contains these glyphs). + +If your terminal emulator is using fontconfig library then you can create +a fontconfig configuration file with the following contents: + +.. code-block:: xml + + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + + <fontconfig> + <alias> + <family>Terminus</family> + <prefer><family>Symbola</family></prefer> + </alias> + </fontconfig> + +(replace ``Terminus`` with the name of the font you are using). Exact sequence +of actions you need to perform is different across distributions, most likely it +will work if you put the above xml into +:file:`/etc/fonts/conf.d/99-prefer-symbola.conf`. On Gentoo you need to put it +into :file:`/etc/fonts/conf.d/99-prefer-symbola.conf` and run:: + + eselect fontconfig enable 99-prefer-symbola + +. + +.. warning:: + This answer is only applicable if you use ``powerline_unicode7`` theme or if + you configured powerline to use the same characters yourself. diff --git a/docs/source/troubleshooting/osx.rst b/docs/source/troubleshooting/osx.rst new file mode 100644 index 0000000..b61063e --- /dev/null +++ b/docs/source/troubleshooting/osx.rst @@ -0,0 +1,71 @@ +*********************** +Troubleshooting on OS X +*********************** + +I can’t see any fancy symbols, what’s wrong? +-------------------------------------------- + +* If you’re using iTerm2, please update to `this revision + <https://github.com/gnachman/iTerm2/commit/8e3ad6dabf83c60b8cf4a3e3327c596401744af6>`_ + or newer. Also make sure that Preferences>Profiles>Text>Non-ASCII Font is the same as + your main Font. +* You need to set your ``LANG`` and ``LC_*`` environment variables to + a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro’s + documentation for information about setting these variables correctly. + +The colors look weird in the default OS X Terminal app! +------------------------------------------------------- + +* The arrows may have the wrong colors if you have changed the “minimum + contrast” slider in the color tab of your OS X settings. +* The default OS X Terminal app is known to have some issues with the + Powerline colors. Please use another terminal emulator. iTerm2 should work + fine. + +The colors look weird in iTerm2! +-------------------------------- + +* The arrows may have the wrong colors if you have changed the “minimum + contrast” slider in the color tab of your OS X settings. +* If you're using transparency, check “Keep background colors opaque”. + +Statusline is getting wrapped to the next line in iTerm2 +-------------------------------------------------------- + +* Turn off “Treat ambigious-width characters as double width” in `Preferences + --> Text`. +* Alternative: remove fancy dividers (they suck in this case), set + :ref:`ambiwidth <config-common-ambiwidth>` to 2. + +I receive a ``NameError`` when trying to use Powerline with MacVim! +------------------------------------------------------------------- + +* Please install MacVim using this command:: + + brew install macvim --env-std --override-system-vim + + Then install Powerline locally with ``pip install --user``, or by + running these commands in the ``powerline`` directory:: + + ./setup.py build + ./setup.py install --user + +I receive an ``ImportError`` when trying to use Powerline on OS X! +------------------------------------------------------------------ + +* This is caused by an invalid ``sys.path`` when using system vim and system + Python. Please try to select another Python distribution:: + + sudo port select python python27-apple + +* See `issue #39 <https://github.com/powerline/powerline/issues/39>`_ for + a discussion and other possible solutions for this issue. + +I receive “FSEventStreamStart: register_with_server: ERROR” with status_colors +------------------------------------------------------------------------------ + +This is `a known <https://github.com/joyent/node/issues/5463>`_ libuv issue that +happens if one is trying to watch too many files. It should be fixed in +libuv-0.12. Until then it is suggested to either disable ``status_colors`` (from +:py:func:`powerline.segments.common.vcs.branch`) or choose stat-based watcher +(will have effectively the same effect as disabling ``status_colors``). |