diff --git a/docs/source/configuration-and-customization.rst b/docs/source/configuration-and-customization.rst new file mode 100644 index 00000000..6d5e8c79 --- /dev/null +++ b/docs/source/configuration-and-customization.rst @@ -0,0 +1,15 @@ +******************************* +Configuration and customization +******************************* + +Quick setup guide +----------------- + +References +---------- + +.. toctree:: + :glob: + + configuration-reference + segment-reference diff --git a/docs/source/configuration-reference.rst b/docs/source/configuration-reference.rst new file mode 100644 index 00000000..1e4eef8b --- /dev/null +++ b/docs/source/configuration-reference.rst @@ -0,0 +1,3 @@ +*********************** +Configuration reference +*********************** diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst deleted file mode 100644 index 23a3022e..00000000 --- a/docs/source/configuration.rst +++ /dev/null @@ -1,636 +0,0 @@ -************* -Configuration -************* - -.. note:: **You DO NOT have to fork the main GitHub repo to personalize your - Powerline configuration!** Please read through the :ref:`quick-guide` for - a quick introduction to user configuration. - -Powerline is configured with one main configuration file, and with separate -configuration files for themes and colorschemes. All configuration files are -written in JSON, with the exception of segment definitions, which are -written in Python. - -Powerline provides default configurations in the following locations: - -`Main configuration`_ - :file:`powerline/config.json` -`Colorschemes`_ - :file:`powerline/colorschemes/{name}.json`, - :file:`powerline/colorscheme/__main__.json`, - :file:`powerline/colorschemes/{extension}/{name}.json` -`Themes`_ - :file:`powerline/themes/{extension}/default.json` - -The default configuration files are stored in the main package. User -configuration files are stored in :file:`$XDG_CONFIG_HOME/powerline` for -Linux users, and in :file:`~/.config/powerline` for OS X users. This usually -corresponds to :file:`~/.config/powerline` on both platforms. - -.. _quick-guide: - -Quick setup guide -================= - -This guide will help you with the initial configuration of Powerline. - -Start by copying the entire set of default configuration files to the -corresponding path in your user config directory: - -.. code-block:: sh - - mkdir ~/.config/powerline - cp -R /path/to/powerline/config_files/* ~/.config/powerline - -Each extension (vim, tmux, etc.) has its own theme, and they are located in -:file:`{config directory}/themes/{extension}/default.json`. - -If you want to move, remove or customize any of the provided segments, you -can do that by updating the segment dictionary in the theme you want to -customize. A segment dictionary looks like this: - -.. code-block:: javascript - - { - "name": "segment_name" - ... - } - -You can move the segment dictionaries around to change the segment -positions, or remove the entire dictionary to remove the segment from the -prompt or statusline. - -.. note:: It's essential that the contents of all your configuration files - is valid JSON! It's strongly recommended that you run your configuration - files through ``jsonlint`` after changing them. - -Some segments need a user configuration to work properly. Here's a couple of -segments that you may want to customize right away: - -**E-mail alert segment** - You have to set your username and password (and possibly server/port) - for the e-mail alert segment. If you're using GMail it's recommended - that you `generate an application-specific password - `_ for this purpose. - - Open a theme file, scroll down to the ``email_imap_alert`` segment and - set your ``username`` and ``password``. The server defaults to GMail's - IMAP server, but you can set the server/port by adding a ``server`` and - a ``port`` argument. -**Weather segment** - The weather segment will try to find your location using a GeoIP lookup, - so unless you're on a VPN you probably won't have to change the location - query. - - If you want to change the location query or the temperature unit you'll - have to update the segment arguments. Open a theme file, scroll down to - the weather segment and update it to include unit/location query - arguments: - - .. code-block:: javascript - - { - "name": "weather", - "priority": 50, - "args": { - "unit": "F", - "location_query": "oslo, norway" - } - }, - -.. _config-main: - -Main configuration -================== - -:Location: :file:`powerline/config.json` - -The main configuration file defines some common options that applies to all -extensions, as well as some extension-specific options like themes and -colorschemes. - -Common configuration --------------------- - -Common configuration is a subdictionary that is a value of ``common`` key in -:file:`powerline/config.json` file. - -.. _config-common-term_truecolor: - -``term_truecolor`` - Defines whether to output cterm indices (8-bit) or RGB colors (24-bit) - to the terminal emulator. See the :ref:`term-feature-support-matrix` for - information on whether your terminal emulator supports 24-bit colors. - -.. _config-common-ambiwidth: - -``ambiwidth`` - Tells powerline what to do with characters with East Asian Width Class - Ambigious (such as Euro, Registered Sign, Copyright Sign, Greek - letters, Cyrillic letters). Valid values: any positive integer; it is - suggested that you only set it to 1 (default) or 2. - -``watcher`` - Select filesystem watcher. Variants are - - ======= =================================== - Variant Description - ======= =================================== - auto Selects most performant watcher. - inotify Select inotify watcher. Linux only. - stat Select stat-based polling watcher. - ======= =================================== - - Default is ``auto``. - -.. _config-common-additional_escapes: - -``additional_escapes`` - Valid for shell extensions, makes sense only if :ref:`term_truecolor - ` is enabled. Is to be set from command-line - (unless you are sure you always need it). Controls additional escaping that - is needed for tmux/screen to work with terminal true color escape codes: - normally tmux/screen prevent terminal emulator from receiving these control - codes thus rendering powerline prompt colorless. Valid values: ``"tmux"``, - ``"screen"``, ``null`` (default). - -``dividers`` - Defines the dividers used in all Powerline extensions. This option - should usually only be changed if you don't have a patched font, or if - you use a font patched with the legacy font patcher. - - The ``hard`` dividers are used to divide segments with different - background colors, while the ``soft`` dividers are used to divide - segments with the same background color. - -.. _config-common-paths: - -``paths`` - Defines additional paths which will be searched for modules when using - :ref:`module segment option `. Paths defined here - have priority when searching for modules. - -``log_file`` - Defines path which will hold powerline logs. If not present, logging will be - done to stderr. - -``log_level`` - String, determines logging level. Defaults to ``WARNING``. - -``log_format`` - String, determines format of the log messages. Defaults to - ``'%(asctime)s:%(level)s:%(message)s'``. - -``interval`` - Number, determines time (in seconds) between checks for changed - configuration. Checks are done in a seprate thread. Use ``null`` to check - for configuration changes on ``.render()`` call in main thread. - Defaults to ``None``. - -``reload_config`` - Boolean, determines whether configuration should be reloaded at all. - Defaults to ``True``. - -Extension-specific configuration --------------------------------- - -Common configuration is a subdictionary that is a value of ``ext`` key in -:file:`powerline/config.json` file. - -``colorscheme`` - Defines the colorscheme used for this extension. - -``theme`` - .. _config-ext-theme: - - Defines the theme used for this extension. - -``local_themes`` - .. _config-ext-local_themes: - - Defines themes used when certain conditions are met, e.g. for - buffer-specific statuslines in vim. Value depends on extension used. For vim - it is a dictionary ``{matcher_name : theme_name}``, where ``matcher_name`` - is either ``matcher_module.module_attribute`` or ``module_attribute`` - (``matcher_module`` defaults to ``powerline.matchers.vim``) and - ``module_attribute`` should point to a function that returns boolean value - indicating that current buffer has (not) matched conditions. - -.. _config-colors: - -Color definitions -================= - -:Location: :file:`powerline/colors.json` - -.. _config-colors-colors: - -``colors`` - Color definitions, consisting of a dict where the key is the name of the - color, and the value is one of the following: - - * A cterm color index. - * A list with a cterm color index and a hex color string (e.g. ``[123, - "aabbcc"]``). This is useful for colorschemes that use colors that - aren't available in color terminals. - -``gradients`` - Gradient definitions, consisting of a dict where the key is the name of the - gradient, and the value is a list containing one or two items, second item - is optional: - - * A list of cterm color indicies. - * A list of hex color strings. - - It is expected that you define gradients from least alert color to most - alert or use non-alert colors. - -.. _config-colorschemes: - -Colorschemes -============ - -:Location: :file:`powerline/colorschemes/{name}.json`, - :file:`powerline/colorscheme/__main__.json`, - :file:`powerline/colorschemes/{extension}/{name}.json` - -Colorscheme files are processed in order given: definitions from each next file -override those from each previous file. It is required that either -:file:`powerline/colorschemes/{name}.json`, or -:file:`powerline/colorschemes/{extension}/{name}.json` exists. - -``name`` - Name of the colorscheme. - -.. _config-colorschemes-groups: - -``groups`` - Segment highlighting groups, consisting of a dict where the key is the - name of the highlighting group (usually the function name for function - segments), and the value is either - - #) a dict that defines the foreground color, background color and - attributes: - - ``fg`` - Foreground color. Must be defined in :ref:`colors - `. - - ``bg`` - Background color. Must be defined in :ref:`colors - `. - - ``attr`` - List of attributes. Valid values are one or more of ``bold``, - ``italic`` and ``underline``. Note that some attributes may be - unavailable in some applications or terminal emulators. If you do not - need any attributes leave this empty. - - #) a string (an alias): a name of existing group. This group’s definition - will be used when this color is requested. - -``mode_translations`` - Mode-specific highlighting for extensions that support it (e.g. the vim - extension). It's an easy way of changing a color in a specific mode. - Consists of a dict where the key is the mode and the value is a dict - with the following options: - - ``colors`` - A dict where the key is the color to be translated in this mode, and - the value is the new color. Both the key and the value must be defined - in :ref:`colors `. - - ``groups`` - Segment highlighting groups for this mode. Same syntax as the main - :ref:`groups ` option. - -.. _config-themes: - -Themes -====== - -:Location: :file:`powerline/themes/{extension}/{name}.json` - -``name`` - Name of the theme. - -.. _config-themes-default_module: - -``default_module`` - Python module where segments will be looked by default. - -.. _config-themes-segment_data: - -``segment_data`` - A dict where keys are segment names or strings ``{module}.{name}``. Used to - specify default values for various keys: - :ref:`after `, - :ref:`args ` (only for function segments), - :ref:`before `, - :ref:`contents ` (only for string segments - if :ref:`name ` is defined), - :ref:`display ` values of these - keys are first searched in the segment description, then in ``segment_data`` - key of a local theme, then in ``segment_data`` key of a :ref:`default theme - `. For the :ref:`default theme ` itself - step 2 is obviously avoided. - -``segments`` - A dict with a ``left`` and a ``right`` lists, consisting of segment - dictionaries. Shell themes may also contain ``above`` list of dictionaries. - Each item in ``above`` list may have ``left`` and ``right`` keys like this - dictionary, but no ``above`` key. - - .. _config-themes-above: - - ``above`` list is used for multiline shell configurations. - - ``left`` and ``right`` lists are used for segments that should be put on the - left or right side in the output. Actual mechanizm of putting segments on - the left or the right depends on used renderer, but most renderers require - one to specify segment with :ref:`width ` ``auto`` - on either side to make generated line fill all of the available width. - - Each segment dictionary has the following options: - - ``type`` - The segment type. Can be one of ``function`` (default), ``string`` - or ``filler``: - - ``function`` - The segment contents is the return value of the function defined - in the :ref:`name option `. - - ``string`` - A static string segment where the contents is defined in the - :ref:`contents option `, and the - highlighting group is defined in the :ref:`highlight_group - option `. - - ``module`` - .. _config-themes-seg-module: - - Function module, only required for function segments. Defaults to - ``powerline.segments.{extension}``. Default is overriden by - :ref:`default_module theme option `. - - ``name`` - .. _config-themes-seg-name: - - Function name, only required for function segments. - - ``highlight_group`` - .. _config-themes-seg-highlight_group: - - Highlighting group for this segment. Consists of a prioritized list - of highlighting groups, where the first highlighting group that is - available in the colorscheme is used. - - Ignored for segments that have ``function`` type. - - ``before`` - .. _config-themes-seg-before: - - A string which will be prepended to the segment contents. - - ``after`` - .. _config-themes-seg-after: - - A string which will be appended to the segment contents. - - ``contents`` - .. _config-themes-seg-contents: - - Segment contents, only required for ``string`` segments. - - ``args`` - .. _config-themes-seg-args: - - A dict of arguments to be passed to a ``function`` segment. - - ``align`` - Aligns the segments contents to the left (``l``), center (``c``) or - right (``r``). - - ``width`` - .. _config-themes-seg-width: - - Enforces a specific width for this segment. - - This segment will work as a spacer if the width is set to ``auto``. - Several spacers may be used, and the space will be distributed - equally among all the spacer segments. Spacers may have contents, - either returned by a function or a static string, and the contents - can be aligned with the ``align`` property. - - ``priority`` - Optional segment priority. Segments with priority ``None`` (the default - priority, represented by ``null`` in json) will always be included, - regardless of the width of the prompt/statusline. - - If the priority is any number, the segment may be removed if the - prompt/statusline width is too small for all the segments to be - rendered. A lower number means that the segment has a higher priority. - - Segments are removed according to their priority, with low priority - segments being removed first. - - ``draw_hard_divider``, ``draw_soft_divider`` - Whether to draw a divider between this and the adjacent segment. The - adjacent segment is to the *right* for segments on the *left* side, and - vice versa. Hard dividers are used between segments with different - background colors, soft ones are used between segments with same - background. Both options default to ``True``. - - ``draw_inner_divider`` - Determines whether inner soft dividers are to be drawn for function - segments. Only applicable for functions returning multiple segments. - Defaults to ``False``. - - ``exclude_modes`` - A list of modes where this segment will be excluded: The segment is - included in all modes, *except* for the modes in this list. - - ``include_modes`` - A list of modes where this segment will be included: The segment is - *not* included in any modes, *except* for the modes in this list. - - ``display`` - .. _config-themes-seg-display: - - Boolean. If false disables displaying of the segment. - Defaults to ``True``. - -Segments -======== - -Segments are written in Python, and the default segments provided with -Powerline are located in :file:`powerline/segments/{extension}.py`. -User-defined segments can be defined in any module in ``sys.path`` or -:ref:`paths common configuration option `, import is -always absolute. - -Segments are regular Python functions, and they may accept arguments. All -arguments should have a default value which will be used for themes that -don't provide an ``args`` dict. - -A segment function must return one of the following values: - -* ``None``, which will remove the segment from the prompt/statusline. -* A string, which will be the segment contents. -* A list of dicts consisting of a ``contents`` string, and - a ``highlight_group`` list. This is useful for providing a particular - highlighting group depending on the segment contents. - -Local configuration -=================== - -Depending on the application used it is possible to override configuration. Here -is the list: - -Vim overrides -------------- - -Vim configuration can be overridden using the following options: - -``g:powerline_config_overrides`` - Dictionary, recursively merged with contents of - :file:`powerline/config.json`. - -``g:powerline_theme_overrides__{theme_name}`` - Dictionary, recursively merged with contents of - :file:`powerline/themes/vim/{theme_name}.json`. Note that this way you can’t - redefine some value (e.g. segment) in list, only the whole list itself: only - dictionaries are merged recursively. - -``g:powerline_config_path`` - Path (must be expanded, ``~`` shortcut is not supported). Points to the - directory which will be searched for configuration. When this option is - present, none of the other locations are searched. - -``g:powerline_no_python_error`` - If this variable is set to a true value it will prevent Powerline from reporting - an error when loaded in a copy of vim without the necessary Python support. - -Powerline script overrides --------------------------- - -Powerline script has a number of options controlling powerline behavior. Here -``VALUE`` always means “some JSON object”. - -``-c KEY.NESTED_KEY=VALUE`` or ``--config=KEY.NESTED_KEY=VALUE`` - Overrides options from :file:`powerline/config.json`. - ``KEY.KEY2.KEY3=VALUE`` is a shortcut for ``KEY={"KEY2": {"KEY3": VALUE}}``. - Multiple options (i.e. ``-c K1=V1 -c K2=V2``) are allowed, result (in the - example: ``{"K1": V1, "K2": V2}``) is recursively merged with the contents - of the file. - - If ``VALUE`` is omitted then corresponding key will be removed from the - configuration (if it was present). - -``-t THEME_NAME.KEY.NESTED_KEY=VALUE`` or ``--theme_option=THEME_NAME.KEY.NESTED_KEY=VALUE`` - Overrides options from :file:`powerline/themes/{ext}/{THEME_NAME}.json`. - ``KEY.NESTED_KEY=VALUE`` is processed like described above, ``{ext}`` is the - first argument to powerline script. May be passed multiple times. - - If ``VALUE`` is omitted then corresponding key will be removed from the - configuration (if it was present). - -``-p PATH`` or ``--config_path=PATH`` - Sets directory where configuration should be read from. If present, no - default locations are searched for configuration. No expansions are - performed by powerline script itself, but ``-p ~/.powerline`` will likely be - expanded by the shell to something like ``-p /home/user/.powerline``. - -Zsh/zpython overrides ---------------------- - -Here overrides are controlled by similarly to the powerline script, but values -are taken from zsh variables. - -``POWERLINE_CONFIG`` - Overrides options from :file:`powerline/config.json`. Should be a zsh - associative array with keys equal to ``KEY.NESTED_KEY`` and values being - JSON strings. Pair ``KEY.KEY1 VALUE`` is equivalent to ``{"KEY": {"KEY1": - VALUE}}``. All pairs are then recursively merged into one dictionary and - this dictionary is recursively merged with the contents of the file. - -``POWERLINE_THEME_CONFIG`` - Overrides options from :file:`powerline/themes/shell/*.json`. Should be - a zsh associative array with keys equal to ``THEME_NAME.KEY.NESTED_KEY`` and - values being JSON strings. Is processed like the above ``POWERLINE_CONFIG``, - but only subdictionaries for ``THEME_NAME`` key are merged with theme - configuration when theme with given name is requested. - -``POWERLINE_CONFIG_PATH`` - Sets directory where configuration should be read from. If present, no - default locations are searched for configuration. No expansions are - performed by powerline script itself, but zsh usually performs them on its - own if you set variable without quotes: ``POWERLINE_CONFIG_PATH=~/example``. - Expansion depends on zsh configuration. - -Ipython overrides ------------------ - -Ipython overrides depend on ipython version. Before ipython-0.11 you should pass -additional keyword arguments to setup() function. After ipython-0.11 you should -use ``c.Powerline.KEY``. Supported ``KEY`` strings or keyword argument names: - -``config_overrides`` - Overrides options from :file:`powerline/config.json`. Should be a dictionary - that will be recursively merged with the contents of the file. - -``theme_overrides`` - Overrides options from :file:`powerline/themes/ipython/*.json`. Should be - a dictionary where keys are theme names and values are dictionaries which - will be recursively merged with the contents of the given theme. - -``path`` - Sets directory where configuration should be read from. If present, no - default locations are searched for configuration. No expansions are - performed thus you cannot use paths starting with ``~/``. - -Prompt command --------------- - -In addition to the above configuration options you can use -``$POWERLINE_COMMAND`` environment variable to tell shell or tmux to use -specific powerline implementation. This is mostly useful for putting powerline -into different directory or replacing ``powerline`` script with -``powerline-client`` for performance reasons. - -.. note:: - - ``$POWERLINE_COMMAND`` appears in shell scripts without quotes thus you can - specify additional parameters in bash. In zsh you will have to make - ``$POWERLINE_COMMAND`` an array parameter to achieve the same result. In - tmux it is passed to ``eval`` and depends on the shell used. - POSIX-compatible shells, zsh, bash and fish will split this variable in this - case. - -If you want to disable prompt in shell, but still have tmux support or if you -want to disable tmux support you can use variables -``$POWERLINE_NO_{SHELL}_PROMPT``/``$POWERLINE_NO_SHELL_PROMPT`` and -``$POWERLINE_NO_{SHELL}_TMUX_SUPPORT``/``$POWERLINE_NO_SHELL_TMUX_SUPPORT`` -(substitute ``{SHELL}`` with the name of the shell (all-caps) you want to -disable support for (e.g. ``BASH``) or use all-inclusive ``SHELL`` that will -disable support for all shells). These variables have no effect after -configuration script was sourced (in fish case: after ``powerline-setup`` -function was run). To disable specific feature support set one of these -variables to some non-empty value. - -If you do not want to disable prompt in shell, but yet do not want to launch -python twice to get :ref:`above ` lines you do not use in -tcsh you should set ``$POWERLINE_NO_TCSH_ABOVE`` or -``$POWERLINE_NO_SHELL_ABOVE`` variable. - -If you do not want to see additional space which is added to the right prompt in -fish in order to support multiline prompt you should set -``$POWERLINE_NO_FISH_ABOVE`` or ``$POWERLINE_NO_SHELL_ABOVE`` variables. - -.. note:: - - Most supported shells’ configuration scripts check for additional - configuration variables being empty. But tcsh configuration script checks - for variables being *defined*, not empty. diff --git a/docs/source/font-installation.rst b/docs/source/font-installation.rst deleted file mode 100644 index d4d6b173..00000000 --- a/docs/source/font-installation.rst +++ /dev/null @@ -1,142 +0,0 @@ -*********************************** -Font installation and configuration -*********************************** - -Powerline uses several special glyphs to get the arrow effect and some -custom symbols for developers. This requires that you either have a symbol -font or a patched font on your system. Your terminal emulator must also -support either patched fonts or fontconfig for Powerline to work properly. - -You can also enable :ref:`24-bit color support ` -if your terminal emulator supports it. - -.. table:: Application/terminal emulator feature support matrix - :name: term-feature-support-matrix - - ===================== ======= =================================== ===================== ===================== ===================== - Name OS Recommended installation method Patched font support Fontconfig support 24-bit color support - ===================== ======= =================================== ===================== ===================== ===================== - Gnome Terminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no| - Gvim Linux `Patched font`_ |i_yes| |i_no| |i_yes| - Konsole Linux `Fontconfig`_ |i_yes| |i_yes| |i_yes| - lxterminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no| - rxvt-unicode Linux `rxvt-unicode`_ or `Patched font`_ |i_partial| [#]_ |i_no| |i_no| - st Linux `Fontconfig`_ |i_yes| |i_yes| |i_no| - Xfce Terminal Linux `Fontconfig`_ |i_yes| |i_yes| |i_no| - xterm Linux `Patched font`_ |i_yes| |i_no| |i_partial| [#]_ - iTerm2 OS X `Patched font`_ |i_yes| |i_no| |i_no| - MacVim OS X `Patched font`_ |i_yes| |i_no| |i_yes| - Terminal.app OS X `Patched font`_ |i_yes| |i_no| |i_no| - ===================== ======= =================================== ===================== ===================== ===================== - -.. |i_yes| image:: _static/img/icons/tick.png -.. |i_no| image:: _static/img/icons/cross.png -.. |i_partial| image:: _static/img/icons/error.png - -.. [#] Must be compiled with ``--enable-unicode3`` for the - patched font to work. -.. [#] Uses nearest color from 8-bit palette. - -Fontconfig -========== - -This method only works on Linux. It's the recommended method if your -terminal emulator supports it as you don't have to patch any fonts, and it -generally works well with any coding font. - -#. Download the latest version of the symbol font and fontconfig file:: - - wget https://github.com/Lokaltog/powerline/raw/develop/font/PowerlineSymbols.otf - wget https://github.com/Lokaltog/powerline/raw/develop/font/10-powerline-symbols.conf - -#. Move the symbol font to a valid X font path. Valid font paths can be - listed with ``xset q``:: - - mv PowerlineSymbols.otf ~/.fonts/ - -#. Update font cache for the path you moved the font to (you may need to be - root to update the cache for system-wide paths):: - - fc-cache -vf ~/.fonts/ - -#. Install the fontconfig file. For newer versions of fontconfig the config - path is ``~/.config/fontconfig/conf.d/``, for older versions it's - ``~/.fonts.conf.d/``:: - - mv 10-powerline-symbols.conf ~/.config/fontconfig/conf.d/ - -If you can't see the custom symbols, please close all instances of your -terminal emulator. You may need to restart X for the changes to take -effect. - -If you *still* can't see the custom symbols, double-check that you have -installed the font to a valid X font path, and that you have installed the -fontconfig file to a valid fontconfig path. Alternatively try to install -a `Patched font`_. - -Patched font -============ - -This method is the fallback method and works for every terminal emulator and -OS, with the exception of `rxvt-unicode`_. - -Download the font of your choice from `powerline-fonts`_. If you can't find -your preferred font in the `powerline-fonts`_ repo, you'll have to patch -your own font instead. See :ref:`font-patching` for instructions. - -.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts - -Installation on Linux ---------------------- - -#. Move the patched font to a valid X font path. Valid font paths can be - listed with ``xset q``:: - - mv 'MyFont for Powerline.otf' ~/.fonts/ - -#. Update font cache for the path you moved the font to (you may need to be - root to update the cache for system-wide paths):: - - fc-cache -vf ~/.fonts/ - -After installing the patched font you need to update Gvim or your terminal -emulator to use the patched font. The correct font usually ends with *for -Powerline*. - -If you can't see the custom symbols, please close all instances of your -terminal emulator. You may need to restart X for the changes to take -effect. - -If you *still* can't see the custom symbols, double-check that you have -installed the font to a valid X font path. - -Installation on OS X --------------------- - -Install your patched font by double-clicking the font file in Finder, then -clicking :guilabel:`Install this font` in the preview window. - -After installing the patched font you need to update MacVim or your terminal -emulator to use the patched font. The correct font usually ends with *for -Powerline*. - -Special cases -============= - -rxvt-unicode ------------- - -.. note:: Symbol font support generally doesn't work well in - rxvt-unicode. It's recommended that you either disable the symbols or - switch to a better terminal emulator if you want to use Powerline. - -rxvt-unicode allows using a `Patched font`_ only if it's compiled with the -``--enable-unicode3`` flag. - -For unsupported fonts (e.g. bitmap fonts like Terminus), you can't use -``PowerlineSymbols.otf`` as a fallback since rxvt-unicode has trouble -determining the font's metrics. A solution to this issue is to get -a `Patched font`_ and add this as a fallback font to your -``.Xresources``/``.Xdefaults``:: - - URxvt*font: xft:Terminus:pixelsize=12,xft:Inconsolata\ for\ Powerline:pixelsize=12 diff --git a/docs/source/fontpatching.rst b/docs/source/fontpatching.rst deleted file mode 100644 index fcba993a..00000000 --- a/docs/source/fontpatching.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. _font-patching: - -************* -Font patching -************* - -Powerline provides a font patcher for custom glyphs like the segment -dividers (arrows), branch symbol, padlock symbol, etc. The font patcher -requires FontForge with Python bindings to work. - -Check out the `powerline-fonts -`_ repository on GitHub for -patched versions of some popular programming fonts. - -.. warning:: The code points have changed in this version of Powerline! This - means that you either have to patch your font again, or change the glyphs - Powerline uses in your user configuration. - -.. note:: Powerline no longer works with rxvt-unicode unless you either use - rxvt-unicode compiled with ``--enable-unicode3``, or you use fonts patched - with the legacy font patcher and change the glyphs in your user - configuration. - -Glyph table -=========== - -Powerline stores all special glyphs in the Unicode *Private Use Area* -(``U+E000``-``U+F8FF``). - -========== ===== =========== -Code point Glyph Description -========== ===== =========== -``U+E0A0``  Version control branch -``U+E0A1``  LN (line) symbol -``U+E0A2``  Closed padlock -``U+E0B0``  Rightwards black arrowhead -``U+E0B1``  Rightwards arrowhead -``U+E0B2``  Leftwards black arrowhead -``U+E0B3``  Leftwards arrowhead -========== ===== =========== - -Usage -===== - -The font patcher, :file:`fontpatcher.py` is located in the `powerline-fontpatcher -`_ repository on GitHub. -It requires Python 2.7 and FontForge compiled with Python bindings to work. - -Patched fonts are renamed by default (" for Powerline" is added to the font -name) so they don't conflict with existing fonts. Use the ``--no-rename`` -option to disable font renaming. - -.. note:: Bitmap fonts are not supported, and will probably never be - supported officially due to difficulty creating a font patcher that works - for bitmap fonts. The recommended method of patching bitmap fonts is to draw - the glyphs manually using a tool like ``gbdfed``. - -Linux ------ - -1. Install fontforge with Python bindings. For Ubuntu users the required - package is ``python-fontforge``, for Arch Linux users the required - package is ``fontforge``. It should be something similar for other - distros. - -2. Run the font patcher:: - - $ /path/to/fontpatcher.py MyFontFile.ttf - -3. Copy the font file into :file:`~/.fonts` (or another X font directory):: - - $ cp "MyFontFile for Powerline.otf" ~/.fonts - -4. Update your font cache:: - - $ fc-cache -vf ~/.fonts - - If you're using vim in a terminal you may need to close all open terminal - windows after updating the font cache. - -5. **Gvim users:** Update the GUI font in your :file:`vimrc` file:: - - set guifont=MyFont\ for\ Powerline - - **Terminal users:** Update your terminal configuration to use the patched - font. - -6. Open vim and enjoy your new statusline! - -OS X ----- - -1. Check if you have a FontForge version with Python support by running - ``fontforge -version``. You should see something like this:: - - $ fontforge -version - Copyright (c) 2000-2011 by George Williams. - Executable based on sources from 13:48 GMT 22-Feb-2011-D. - Library based on sources from 13:48 GMT 22-Feb-2011. - fontforge 20110222 - libfontforge 20110222 - - Make sure that the executable version number doesn't have ``NoPython`` in - it. If everything looks OK, skip ahead to step 4. - -2. If you have FontForge but with ``NoPython`` in the version number, please - try to update to a later version:: - - $ brew uninstall fontforge - $ brew update - $ brew install fontforge - - **Note:** You may have to use ``--use-clang`` instead of ``--use-gcc`` - when compiling FontForge. - -3. If you don't have FontForge, install it with Homebrew:: - - $ brew update - $ brew install fontforge - -4. Patch your fonts by passing the ``fontpatcher`` script as a parameter to - FontForge:: - - $ fontforge -script /path/to/fontpatcher.py MyFontFile.ttf - -5. Install the font by double-clicking the font file in Finder and click - "Install this font" from the preview window. - -6. **Gvim users:** Update the GUI font in your :file:`vimrc` file:: - - set guifont=MyFont\ for\ Powerline - - **Terminal users:** Update your terminal configuration to use the patched - font. - -7. Open vim and enjoy your new statusline! diff --git a/docs/source/index.rst b/docs/source/index.rst index 2afd8241..5a502249 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,20 +6,13 @@ Powerline :maxdepth: 2 :glob: - introduction overview - configuration - tipstricks - fontpatching - license-credits - -Segments -======== - -.. toctree:: - segments/common - segments/shell - segments/vim + installation + usage + configuration-and-customization + troubleshooting + tips-and-tricks + license-and-credits Indices and tables ================== diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 00000000..3696e7c0 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,8 @@ +************ +Installation +************ + +.. toctree:: + + Linux + OS X diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst index e8ff6d72..377770a3 100644 --- a/docs/source/installation/linux.rst +++ b/docs/source/installation/linux.rst @@ -1,106 +1,9 @@ -:tocdepth: 2 - -.. _installation-linux: - ********************* 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 for you, but you should -still skim through this guide so you know how the plugin works. - -* `Arch Linux (AUR), Python 2 version `_ -* `Arch Linux (AUR), Python 3 version `_ -* Gentoo Live ebuild in `raiagent `_ overlay - -If you're running a distribution without an official package you'll have to -follow the installation guide below: - -Plugin installation -=================== - -1. Install Python 3.2+ or Python 2.6+. -2. Install Powerline using the following command:: - - pip install --user git+git://github.com/Lokaltog/powerline - -.. note:: You need to use the GitHub URI when installing Powerline! This - project is currently unavailable on the PyPI due to a naming conflict - with an unrelated project. - -.. note:: If you are powerline developer you should be aware that ``pip install - --editable`` does not currently fully work. If you - install powerline this way you will be missing ``powerline`` executable and - need to symlink it. It will be located in ``scripts/powerline``. - -Font installation -================= - -Powerline provides two ways of installing the required fonts on Linux. The -recommended method is using ``fontconfig`` if your terminal emulator -supports it. See the :ref:`term-feature-support-matrix` for details about -what features your terminal emulator supports. - -Fontconfig ----------- - -1. Download the `latest version of PowerlineSymbols - `_ - and the `latest version of the fontconfig file - `_. -2. Move :file:`PowerlineSymbols.otf` to :file:`~/.fonts/` (or another X font - directory). -3. Run ``fc-cache -vf ~/.fonts`` to update your font cache. -4. Move :file:`10-powerline-symbols.conf` to either :file:`~/.fonts.conf.d/` - or :file:`~/.config/fontconfig/conf.d/`, depending on your fontconfig - version. -5. If you don't see the arrow symbols, please close all instances of your - terminal emulator or gvim. You may also have to restart X for the changes - to take effect. If you *still* don't see the arrow symbols, please submit - an issue on GitHub. - -Patched font +Requirements ------------ -1. Download the font of your choice from `powerline-fonts`_. If you can't - find your preferred font in the `powerline-fonts`_ repo, you'll have to - patch your own font instead. See :ref:`font-patching` for instructions. -2. Move your patched font to :file:`~/.fonts/` (or another X font - directory). -3. Run ``fc-cache -vf ~/.fonts`` to update your font cache. -4. Update Gvim or your terminal emulator to use the patched font. (the - correct font usually ends with *for Powerline*). -5. If you don't see the arrow symbols, please close all instances of your - terminal emulator or gvim. You may also have to restart X for the changes - to take effect. If you *still* don't see the arrow symbols, please submit - an issue on GitHub. - -.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts - -Troubleshooting -=============== - -.. contents:: - :local: - -I can't see any fancy symbols, what's wrong? --------------------------------------------- - -* Make sure that you've configured gvim or your terminal emulator to use - a patched font (see :ref:`font-patching`). -* You need to set your ``LANG`` and ``LC_*`` environment variables to - a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's - documentation for information about setting these variables correctly. -* Make sure that vim is compiled with the ``--with-features=big`` flag. -* If you're using rxvt-unicode, make sure that it's compiled with the - ``--enable-unicode3`` flag. - -The fancy symbols look a bit blurry or "off"! ---------------------------------------------- - -* Make sure that you have patched all variants of your font (i.e. both the - regular and the bold font files). - -.. include:: troubleshooting-common.rst +Installation +------------ diff --git a/docs/source/installation/osx.rst b/docs/source/installation/osx.rst index c991eac7..b44f5529 100644 --- a/docs/source/installation/osx.rst +++ b/docs/source/installation/osx.rst @@ -1,125 +1,9 @@ -:tocdepth: 2 - -.. _installation-osx: - ******************** Installation on OS X ******************** -Plugin installation -=================== +Requirements +------------ -Python package --------------- - -1. Install a proper Python version (see `issue #39 - `_ for a discussion - regarding the required Python version on OS X):: - - sudo port select python python27-apple - -2. Install Powerline using the following command:: - - pip install --user git+git://github.com/Lokaltog/powerline - -.. note:: You need to use the GitHub URI when installing Powerline! This - project is currently unavailable on the PyPI due to a naming conflict - with an unrelated project. - -.. note:: If you are powerline developer you should be aware that ``pip install - --editable`` does not currently fully work. If you - install powerline this way you will be missing ``powerline`` executable and - need to symlink it. It will be located in ``scripts/powerline``. - -Vim installation ----------------- - -Any terminal vim version with Python 3.2+ or Python 2.6+ support should work, -but if you're using MacVim you need to install it using the following command:: - - brew install macvim --env-std --override-system-vim - -Font installation -================= - -You need a patched font for Powerline to work on OS X. Check out the -`powerline-fonts`_ repository on GitHub for patched versions of some popular -programming fonts. - -1. Download the font of your choice and install it by double-clicking the - font file in Finder and then click :guilabel:`Install this font` in the - preview window. - - If you can't find your preferred font in the `powerline-fonts`_ repo, - you'll have to patch your own font instead. See :ref:`font-patching` for - instructions. -2. Configure MacVim or your terminal emulator to use the patched font (the - correct font usually ends with *for Powerline*). - -.. _powerline-fonts: https://github.com/Lokaltog/powerline-fonts - -Troubleshooting -=============== - -.. contents:: - :local: - -I can't see any fancy symbols, what's wrong? --------------------------------------------- - -* If you're using iTerm2, please update to `this revision - `_ - or newer. -* You need to set your ``LANG`` and ``LC_*`` environment variables to - a UTF-8 locale (e.g. ``LANG=en_US.utf8``). Consult your Linux distro's - documentation for information about setting these variables correctly. - -The colors look weird in the default OS X Terminal app! -------------------------------------------------------- - -* The arrows may have the wrong colors if you have changed the "minimum - contrast" slider in the color tab of your OS X settings. -* The default OS X Terminal app is known to have some issues with the - Powerline colors. Please use another terminal emulator. iTerm2 should work - fine. - -The colors look weird in iTerm2! --------------------------------- - -* The arrows may have the wrong colors if you have changed the "minimum - contrast" slider in the color tab of your OS X settings. -* Please disable background transparency to resolve this issue. - -Statusline is getting wrapped to the next line in iTerm2 --------------------------------------------------------- - -* Turn off “Treat ambigious-width characters as double width” in `Preferences - --> Text`. -* Alternative: remove fancy dividers (they suck in this case), set - :ref:`ambiwidth ` 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 `_ for - a discussion and other possible solutions for this issue. - -.. include:: troubleshooting-common.rst +Installation +------------ diff --git a/docs/source/installation/troubleshooting-common.rst b/docs/source/installation/troubleshooting-common.rst deleted file mode 100644 index 55345394..00000000 --- a/docs/source/installation/troubleshooting-common.rst +++ /dev/null @@ -1,136 +0,0 @@ -I'm using tmux and Powerline looks like crap, what's wrong? ------------------------------------------------------------ - -* You need to tell tmux that it has 256-color capabilities. Add this to your - :file:`.tmux.conf` to solve this issue:: - - set -g default-terminal "screen-256color" - -* If you're using iTerm2, make sure that you have enabled the setting - :guilabel:`Set locale variables automatically` in :menuselection:`Profiles - --> Terminal --> Environment`. - -I’m using tmux/screen and Powerline is colorless ------------------------------------------------- - -* If the above advices do not help, then you need to disable - :ref:`term_truecolor `. -* Alternative: set :ref:`additional_escapes ` - to ``"tmux"`` or ``"screen"``. Note that it is known to work perfectly in - screen, but in tmux it may produce ugly spaces. - - -After an update something stopped working ------------------------------------------ - -Assuming powerline was working before update and stopped only after there are -two possible explanations: - -* You have more then one powerline installation (e.g. ``pip`` and ``Vundle`` - installations) and you have updated only one. -* Update brought some bug to powerline. - -In the second case you, of course, should report the bug to `powerline bug -tracker `_. In the first you should make -sure you either have only one powerline installation or you update all of them -simultaneously (beware that in the second case you are not supported). To -diagnose this problem you may do the following: - -#) If this problem is observed within the shell make sure that - - .. code-block:: shell - - python -c 'import powerline; print (powerline.__file__)' - - which should report something like - :file:`/usr/lib64/python2.7/site-packages/powerline/__init__.pyc` (if - powerline is installed system-wide) or - :file:`/home/USER/.../powerline/__init__.pyc` (if powerline was cloned - somewhere, e.g. in :file:`/home/USER/.vim/bundle/powerline`) reports the same - location you use to source in your shell configuration: in first case it - should be some location in :file:`/usr` (e.g. - :file:`/usr/share/zsh/site-contrib/powerline.zsh`), in the second it should - be something like - :file:`/home/USER/.../powerline/bindings/zsh/powerline.zsh`. If this is true - it may be a powerline bug, but if locations do not match you should not - report the bug until you observe it on configuration where locations do - match. -#) If this problem is observed within the vim instance you should check out the - output of the following Ex mode commands - - .. code-block:: vim - - python import powerline as pl ; print (pl.__file__) - python3 import powerline as pl ; print (pl.__file__) - - One (but not both) of them will most likely error out, this is OK. The same - rules apply as in the 1), but in place of sourcing you should seek for the - place where you modify `runtimepath` vim option. If you install powerline - using `VAM `_ then no - explicit modifications of runtimpath were performed in your vimrc - (runtimepath is modified by VAM in this case), but powerline will be placed - in :file:`{plugin_root_dir}/powerline` where `{plugin_root_dir}` is stored in - VAM settings dictionary: do `echo g:vim_addon_manager.plugin_root_dir`. - -There is a hint if you want to place powerline repository somewhere, but still -make powerline package importable anywhere: use - - .. code-block:: shell - - pip install --user --editable path/to/powerline - -My vim statusline has strange characters like ``^B`` in it! ------------------------------------------------------------ - -* Please add ``set encoding=utf-8`` to your :file:`vimrc`. - -My vim statusline has a lot of ``^`` or underline characters in it! -------------------------------------------------------------------- - -* You need to configure the ``fillchars`` setting to disable statusline - fillchars (see ``:h fillchars`` for details). Add this to your - :file:`vimrc` to solve this issue: - - .. code-block:: vim - - set fillchars+=stl:\ ,stlnc:\ - -My vim statusline is hidden/only appears in split windows! ----------------------------------------------------------- - -* Make sure that you have ``set laststatus=2`` in your :file:`vimrc`. - -My vim statusline is not displayed completely and has too much spaces ---------------------------------------------------------------------- - -* Be sure you have ``ambiwidth`` option set to ``single``. -* Alternative: set :ref:`ambiwidth ` to 2, remove fancy - dividers (they suck when ``ambiwidth`` is set to double). - -When using z powerline shows wrong number of jobs -------------------------------------------------- - -This happens because `z `_ is launching some jobs in -the background from ``$POWERLINE_COMMAND`` and these jobs fail to finish before -powerline prompt is run. - -Solution to this problem is simple: be sure that :file:`z.sh` is sourced -strictly after :file:`powerline/bindings/bash/powerline.sh`. This way background -jobs are spawned by `z `_ after powerline has done -its job. - -I am suffering bad lags before displaying shell prompt ------------------------------------------------------- - -To get rid of these lags there currently are two options: - -* Run ``powerline-daemon``. Powerline does not automatically start it for you. -* Compile and install ``libzpython`` module that lives in - https://bitbucket.org/ZyX_I/zpython. This variant is zsh-specific. - -Prompt is spoiled after completing files in ksh ------------------------------------------------ - -This is exactly why powerline has official mksh support, but not official ksh -support. If you know the solution feel free to share it in `powerline bug -tracker `_. diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst deleted file mode 100644 index f030aec3..00000000 --- a/docs/source/introduction.rst +++ /dev/null @@ -1,65 +0,0 @@ -************ -Introduction -************ - -This is the next version of Powerline, implemented in Python. It aims to -resolve some of the "unresolvable" problems of the vimscript implementation, -as well as providing a common code base for all projects that use Powerline -in some way (e.g. shell prompts and tmux themes). - -The project is currently in beta, and most of the functionality in the old -vimscript project is already implemented. - -Screenshots -=========== - -**Mode-dependent highlighting** - -* .. image:: _static/img/pl-mode-normal.png - :alt: Normal mode -* .. image:: _static/img/pl-mode-insert.png - :alt: Insert mode -* .. image:: _static/img/pl-mode-visual.png - :alt: Visual mode -* .. image:: _static/img/pl-mode-replace.png - :alt: Replace mode - -**Automatic truncation of segments in small windows** - -* .. image:: _static/img/pl-truncate1.png - :alt: Truncation illustration -* .. image:: _static/img/pl-truncate2.png - :alt: Truncation illustration -* .. image:: _static/img/pl-truncate3.png - :alt: Truncation illustration - -The font in the screenshots is `Pragmata Pro`_ by Fabrizio Schiavi. - -.. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm - -Feature highlights -================== - -* **Better performance.** Python performs quite a bit better than vimscript, - and by having most of the code in Python instead of vimscript it's also - much easier to profile the code and eliminate bottlenecks. -* **A much leaner code base.** With most of the functionality of the old - project implemented the new version consists of less than half the amount - of code. -* **Automatic removal of less important segments in small windows.** Not all - information is equally important to have in the statusline, and segments - with e.g. encoding and file format information are automatically removed - in smaller windows. -* **Dynamic statusline evaluation in Python.** Statuslines are dynamically - rendered in Python instead of relying on vim's statusline flags, which - allows much more flexibility when creating statuslines. -* **The possibility of adding more segments.** Because of vim's hardcoded - limitation of 80 statusline options, the vimscript implementation - triggered an error when adding more segments to the default theme. Since - segment contents are now rendered as plain text in Python it's possible to - add many more segments in the statusline before reaching this limit. -* **New and improved theme and colorscheme syntax.** Themes and colorschemes - are now written in JSON, with a much cleaner syntax that's easier to learn - and work with. Themes and colorschemes are also much more configurable, - and it's easy to write your own and store them in your home config - directory. diff --git a/docs/source/license-credits.rst b/docs/source/license-and-credits.rst similarity index 76% rename from docs/source/license-credits.rst rename to docs/source/license-and-credits.rst index 8fafc92c..bdd7ede8 100644 --- a/docs/source/license-credits.rst +++ b/docs/source/license-and-credits.rst @@ -2,28 +2,22 @@ License and credits ******************* -License -======= - -Powerline is licensed under the `MIT license +Powerline is licensed under the `MIT license `_. -Credits -======= - Authors ------- * `Kim Silkebækken `_ -* `ZyX-I `_ +* `Nikolay Pavlov `_ * `Kovid Goyal `_ Contributors ------------ -* `List of contributors +* `List of contributors `_ -* The glyphs in the font patcher are created by Fabrizio Schiavi, creator of +* The glyphs in the font patcher are created by Fabrizio Schiavi, creator of the excellent coding font `Pragmata Pro`_. .. _`Pragmata Pro`: http://www.fsd.it/fonts/pragmatapro.htm diff --git a/docs/source/overview.rst b/docs/source/overview.rst index f50940a6..ed2abefd 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -2,332 +2,66 @@ Overview ******** -Requirements -============ +**Powerline is a statusline plugin for vim, and provides statuslines and +prompts for several other applications, including zsh, bash, tmux, IPython, +Awesome and Qtile.** -Powerline requires Python 3.3 or Python 2.7 to work. +Features +-------- -Vim plugin requirements ------------------------ +* **Extensible and feature rich, written in Python.** Powerline was + completely rewritten in Python to get rid of as much vimscript as + possible. This has allowed much better extensibility, leaner and better + config files, and a structured, object-oriented codebase with no mandatory + third-party dependencies other than a Python interpreter. +* **Stable and testable code base.** Using Python has allowed unit testing + of all the project code. The code is tested to work in Python 2.6+ and + Python 3. +* **Support for prompts and statuslines in many applications.** Originally + created exclusively for vim statuslines, the project has evolved to + provide statuslines in tmux and several WMs, and prompts for shells like + bash/zsh and other applications. It's simple to write renderers for any + other applications that Powerline doesn't yet support. +* **Configuration and colorschemes written in JSON.** JSON is + a standardized, simple and easy to use file format that allows for easy + user configuration across all of Powerline's supported applications. +* **Fast and lightweight, with daemon support for even better performance.** + Although the code base spans a couple of thousand lines of code with no + goal of "less than X lines of code", the main focus is on good performance + and as little code as possible while still providing a rich set of + features. The new daemon also ensures that only one Python instance is + launched for prompts and statuslines, which provides excellent + performance. -The vim plugin requires a vim version with Python support compiled in. You -can check if your vim supports Python by running ``vim --version | grep -+python``. +*But I hate Python / I don't need shell prompts / this is just too much +hassle for me / what happened to the original vim-powerline project / …* -If your vim version doesn't have support for Python, you'll have to compile -it with the ``--enable-pythoninterp`` flag (``--enable-python3interp`` if -you want Python 3 support instead). Note that this also requires the related -Python headers to be installed on your system. Please consult your -distribution's documentation for details on how to compile and install -packages. +You should check out some of the Powerline derivatives. The most lightweight +and feature-rich alternative is currently Bailey Ling's `vim-airline +`_ project. -Vim version 7.3.661 or newer is recommended for performance reasons. - -Terminal emulator requirements ------------------------------- - -Powerline uses several special glyphs to get the arrow effect and some -custom symbols for developers. This requires that you either have a symbol -font or a patched font on your system. Your terminal emulator must also -support either patched fonts or fontconfig for Powerline to work properly. - -You can also enable :ref:`24-bit color support ` -if your terminal emulator supports it. - -.. table:: Application/terminal emulator feature support matrix - :name: term-feature-support-matrix - - ===================== ======= ===================== ===================== ===================== - Name OS Patched font support Fontconfig support 24-bit color support - ===================== ======= ===================== ===================== ===================== - Gnome Terminal Linux |i_yes| |i_yes| |i_no| - Gvim Linux |i_yes| |i_no| |i_yes| - iTerm2 OS X |i_yes| |i_no| |i_no| - Konsole Linux |i_yes| |i_yes| |i_yes| - lxterminal Linux |i_yes| |i_yes| |i_no| - MacVim OS X |i_yes| |i_no| |i_yes| - rxvt-unicode Linux |i_partial| [#]_ |i_no| |i_no| - st Linux |i_yes| |i_yes| |i_no| - Terminal.app OS X |i_yes| |i_no| |i_no| - Xfce Terminal Linux |i_yes| |i_yes| |i_no| - xterm Linux |i_yes| |i_no| |i_partial| [#]_ - ===================== ======= ===================== ===================== ===================== - -.. |i_yes| image:: _static/img/icons/tick.png -.. |i_no| image:: _static/img/icons/cross.png -.. |i_partial| image:: _static/img/icons/error.png - -.. [#] Must be compiled with ``--enable-unicode3`` for the - patched font to work. -.. [#] Uses nearest color from 8-bit palette. - -Optional dependencies ---------------------- - -The following software is not required by all segments, but recommended for -optimal performance and extra features: - -Python packages -^^^^^^^^^^^^^^^ - -* ``pygit2`` -* ``mercurial`` -* ``psutil`` -* ``i3-py``, `available on github `_. Only used with i3wm bindings and segments. - -Other applications -^^^^^^^^^^^^^^^^^^ - -* ``git`` version 1.7.2 and later. Not needed if you have ``pygit2``. - -Installation -============ - -.. note:: This project is currently unavailable from PyPI due to a naming conflict - with an unrelated project. Please read the detailed instructions for your platform - below. - -* :ref:`installation-linux` -* :ref:`installation-osx` - -Usage -===== - -.. _vim-vimrc: +Screenshots +----------- 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 your :file:`vimrc`. - -If you just cloned the repository add the following line to your :file:`vimrc`, -where ``{repository_root}`` is the absolute path to your Powerline installation -directory: - -.. code-block:: vim - - set rtp+={repository_root}/powerline/bindings/vim - -If you're using Vundle or Pathogen and don't want Powerline functionality in -any other applications, simply add Powerline as a bundle and point the path -above to the Powerline bundle directory, e.g. -``~/.vim/bundle/powerline/powerline/bindings/vim``. For vim-addon-manager it is -even easier since you don’t need to write this big path or install anything by -hand: ``powerline`` is installed and run just like any other plugin using - -.. code-block:: vim - - call vam#ActivateAddons(['powerline']) - -.. note:: - If you use supplied :file:`powerline.vim` file to load powerline there are - additional configuration variables available: ``g:powerline_pycmd`` and - ``g:powerline_pyeval``. First sets command used to load powerline: expected - values are ``"py"`` and ``"py3"``. Second sets function used in statusline, - expected values are ``"pyeval"`` and ``"py3eval"``. - - If ``g:powerline_pycmd`` is set to the one of the expected values then - ``g:powerline_pyeval`` will be set accordingly. If it is set to some other - value then you must also set ``g:powerline_pyeval``. Powerline will not - check that Vim is compiled with Python support if you set - ``g:powerline_pycmd`` to an unexpected value. - - These values are to be used to specify the only Python that is to be loaded - if you have both versions: Vim may disable loading one python version if - other was already loaded. They should also be used if you have two python - versions able to load simultaneously, but with powerline installed only for - python-3 version. - -Shell prompts -------------- - -.. note:: - It is advised that you run ``powerline-daemon`` before using any of the - below solutions. To do this add - - .. code-block:: bash - - powerline-daemon -q - - just before sourcing powerline bindings script or running - ``powerline-setup``. Use ``|| true`` or equivalent if you run your - configuration with ``set -e`` because ``powerline-daemon`` will exit with - ``1`` if daemon is already running. - -Bash prompt -^^^^^^^^^^^ - -Add the following line to your :file:`bashrc`, where ``{repository_root}`` is -the absolute path to your Powerline installation directory: - -.. code-block:: bash - - . {repository_root}/powerline/bindings/bash/powerline.sh - -Zsh prompt -^^^^^^^^^^ - -Add the following line to your :file:`zshrc`, where ``{repository_root}`` is the -absolute path to your Powerline installation directory: - -.. code-block:: bash - - . {repository_root}/powerline/bindings/zsh/powerline.zsh - -Fish prompt -^^^^^^^^^^^ - -Add the following line to your :file:`config.fish`, where ``{repository_root}`` -is the absolute path to your Powerline installation directory: - -.. code-block:: bash - - set fish_function_path $fish_function_path "{repository_root}/powerline/bindings/fish" - powerline-setup - -.. _tmux-statusline: - -Busybox (ash), mksh and dash prompt -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -After launching busybox run the following command: - -.. code-block:: bash - - . {repository_root}/powerline/bindings/shell/powerline.sh - -Mksh users may put this line into ``~/.mkshrc`` file. Dash users may use the -following in ``~/.profile``: - -.. code-block:: bash - - if test "x$0" != "x${0#dash}" ; then - export ENV={repository_root}/powerline/bindings/shell/powerline.sh - fi - -.. note:: - Dash users that already have ``$ENV`` defined should either put the ``. - …/shell/powerline.sh`` line in the ``$ENV`` file or create a new file which - will source (using ``.`` command) both former ``$ENV`` file and - :file:`powerline.sh` files and set ``$ENV`` to the path of this new file. - -.. warning:: - Job count is using some weird hack that uses signals and temporary files for - interprocess communication. It may be wrong sometimes. Not the case in mksh. - -.. warning:: - Busybox has two shells: ``ash`` and ``hush``. Second is known to segfault in - busybox 1.22.1 when using :file:`powerline.sh` script. - -Tmux statusline ---------------- - -Add the following lines to your :file:`.tmux.conf`, where ``{repository_root}`` -is the absolute path to your Powerline installation directory:: - - source "{repository_root}/powerline/bindings/tmux/powerline.conf" - -.. note:: - The availability of the ``powerline-config`` command is required for - powerline support. You may specify location of this script via - ``$POWERLINE_CONFIG_COMMAND`` environment variable. - -.. note:: - It is advised that you run ``powerline-daemon`` before adding the above line - to tmux.conf. To do so add:: - - run-shell "powerline-daemon -q" - - to :file:`.tmux.conf`. - -IPython prompt --------------- - -For IPython<0.11 add the following lines to your -:file:`.ipython/ipy_user_conf.py`:: - - # top - from powerline.bindings.ipython.pre_0_11 import setup as powerline_setup - - # main() function (assuming you launched ipython without configuration to - # create skeleton ipy_user_conf.py file): - powerline_setup() - -For IPython>=0.11 add the following line to your :file:`ipython_config.py` -file in the profile you are using:: - - c.InteractiveShellApp.extensions = [ - 'powerline.bindings.ipython.post_0_11' - ] - -IPython=0.11* is not supported and does not work. IPython<0.10 was not -tested (not installable by pip). - -Awesome widget --------------- - -.. note:: Powerline currently only supports awesome 3.5. - -.. note:: The Powerline widget will spawn a shell script that runs in the - background and updates the statusline with ``awesome-client``. - -Add the following to your :file:`rc.lua`, where ``{repository_root}`` is the -absolute path to your Powerline installation directory: - -.. code-block:: lua - - package.path = package.path .. ';{repository_root}/powerline/bindings/awesome/?.lua' - require('powerline') - -Then add the ``powerline_widget`` to your ``wibox``: - -.. code-block:: lua - - right_layout:add(powerline_widget) - -Qtile widget ------------- - -Add the following to your :file:`~/.config/qtile/config.py`: - -.. code-block:: python - - from powerline.bindings.qtile.widget import Powerline - - screens = [ - Screen( - top=bar.Bar([ - # ... - Powerline(timeout=2), - # ... - ], - ), - ), - ] - -I3 bar ------- - -.. note:: Until the patch is done in i3, you will need a custom ``i3bar`` build - called ``i3bgbar``. The source is available `here - `_. - -Add the following to your :file:`~/.i3/config`:: - - bar { - i3bar_command i3bgbar - - status_command python /path/to/powerline/bindings/i3/powerline-i3.py - font pango:PowerlineFont 12 - } - -where ``i3bgbar`` may be replaced with the path to the custom i3bar binary and -``PowerlineFont`` is any system font with powerline support. +^^^^^^^^^^^^^^ + +**Mode-dependent highlighting** + +* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-normal.png + :alt: Normal mode +* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-insert.png + :alt: Insert mode +* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-visual.png + :alt: Visual mode +* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-mode-replace.png + :alt: Replace mode + +**Automatic truncation of segments in small windows** + +* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate1.png + :alt: Truncation illustration +* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate2.png + :alt: Truncation illustration +* .. image:: https://raw.github.com/Lokaltog/powerline/develop/docs/source/_static/img/pl-truncate3.png + :alt: Truncation illustration diff --git a/docs/source/segment-reference.rst b/docs/source/segment-reference.rst new file mode 100644 index 00000000..83b20b12 --- /dev/null +++ b/docs/source/segment-reference.rst @@ -0,0 +1,8 @@ +***************** +Segment reference +***************** + +.. toctree:: + :glob: + + segment-reference/* diff --git a/docs/source/segments/common.rst b/docs/source/segment-reference/common.rst similarity index 100% rename from docs/source/segments/common.rst rename to docs/source/segment-reference/common.rst diff --git a/docs/source/segments/shell.rst b/docs/source/segment-reference/shell.rst similarity index 100% rename from docs/source/segments/shell.rst rename to docs/source/segment-reference/shell.rst diff --git a/docs/source/segments/vim.rst b/docs/source/segment-reference/vim.rst similarity index 100% rename from docs/source/segments/vim.rst rename to docs/source/segment-reference/vim.rst diff --git a/docs/source/tipstricks.rst b/docs/source/tips-and-tricks.rst similarity index 93% rename from docs/source/tipstricks.rst rename to docs/source/tips-and-tricks.rst index 91cbb6ee..59db85cd 100644 --- a/docs/source/tipstricks.rst +++ b/docs/source/tips-and-tricks.rst @@ -1,6 +1,6 @@ -************* -Tips & Tricks -************* +*************** +Tips and tricks +*************** Vim === @@ -8,10 +8,10 @@ Vim Fix terminal timeout when pressing escape ----------------------------------------- -When you're pressing :kbd:`Escape` to leave insert mode in the terminal, it -will by default take a second or another keystroke to leave insert mode -completely and update the statusline. If you find this annoying, you can add -the following snippet to your :file:`vimrc` to escape insert mode +When you're pressing :kbd:`Escape` to leave insert mode in the terminal, it +will by default take a second or another keystroke to leave insert mode +completely and update the statusline. If you find this annoying, you can add +the following snippet to your :file:`vimrc` to escape insert mode immediately: .. code-block:: vim @@ -28,11 +28,11 @@ immediately: Useful settings --------------- -You may find the following vim settings useful when using the Powerline +You may find the following vim settings useful when using the Powerline statusline: .. code-block:: vim - + set laststatus=2 " Always display the statusline in all windows set noshowmode " Hide the default mode text (e.g. -- INSERT -- below the statusline) diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 00000000..31c5fc80 --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,8 @@ +*************** +Troubleshooting +*************** + +.. toctree:: + + Linux + OS X diff --git a/docs/source/troubleshooting/linux.rst b/docs/source/troubleshooting/linux.rst new file mode 100644 index 00000000..70bd739d --- /dev/null +++ b/docs/source/troubleshooting/linux.rst @@ -0,0 +1,3 @@ +************************ +Troubleshooting on Linux +************************ diff --git a/docs/source/troubleshooting/osx.rst b/docs/source/troubleshooting/osx.rst new file mode 100644 index 00000000..e4fd024b --- /dev/null +++ b/docs/source/troubleshooting/osx.rst @@ -0,0 +1,3 @@ +*********************** +Troubleshooting on OS X +*********************** diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 00000000..a03340bf --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,15 @@ +***** +Usage +***** + +Application support matrix +-------------------------- + +Plugins +------- + +.. toctree:: + + usage/shell-prompts + usage/wm-widgets + usage/other diff --git a/docs/source/usage/other.rst b/docs/source/usage/other.rst new file mode 100644 index 00000000..40e3b686 --- /dev/null +++ b/docs/source/usage/other.rst @@ -0,0 +1,6 @@ +************* +Other plugins +************* + +tmux statusline +--------------- diff --git a/docs/source/usage/shell-prompts.rst b/docs/source/usage/shell-prompts.rst new file mode 100644 index 00000000..56da391c --- /dev/null +++ b/docs/source/usage/shell-prompts.rst @@ -0,0 +1,15 @@ +************* +Shell prompts +************* + +bash +---- + +zsh +--- + +fish +---- + +IPython +------- diff --git a/docs/source/usage/wm-widgets.rst b/docs/source/usage/wm-widgets.rst new file mode 100644 index 00000000..f661199d --- /dev/null +++ b/docs/source/usage/wm-widgets.rst @@ -0,0 +1,9 @@ +********************** +Window manager widgets +********************** + +Awesome +------- + +Qtile +-----