Skip to content
Browse files

Update Powerline.txt help file.

1. Add usage paragraphs
2. Add option examples.
3. Fix capitalization of Unicode and Vim
  • Loading branch information...
1 parent 7f53b5c commit b3e0a46a882540e27389f20220ff091d8dc37a3c @dougireton dougireton committed Jul 9, 2012
Showing with 82 additions and 47 deletions.
  1. +82 −47 doc/Powerline.txt
View
129 doc/Powerline.txt
@@ -46,22 +46,28 @@ CONTENTS *Powerline-contents*
1. Introduction *Powerline* *Powerline-introduction*
Powerline is a utility plugin which allows you to create better-looking, more
-functional vim statuslines.
+functional Vim statuslines.
==============================================================================
2. Usage *Powerline-usage*
Powerline is automatically enabled when it's installed, either by unzipping
the provided archive or by adding it as a Pathogen/Vundle bundle.
+Powerline replaces the standard Vim 'statusline' with a custom statusline made
+up of Powerline segments.
+
+Powerline ignores any 'statusline' customizations you have defined in your
+|vimrc|. If you remove Powerline, your 'statusline' customizations are restored.
+
==============================================================================
3. Requirements *Powerline-requirements*
-Powerline has been developed and tested in vim 7.3, but it should run without
-any problems in vim 7.2. The default configuration requires a Unix-like system
+Powerline has been developed and tested in Vim 7.3, but it should run without
+any problems in Vim 7.2. The default configuration requires a Unix-like system
to work properly.
-The plugin only works with vim running in an 88/256-color terminal or gvim.
+The plugin only works with Vim running in an 88/256-color terminal or gvim.
Vi-compatible mode must be disabled.
@@ -72,12 +78,12 @@ The following configuration options should be set in your |vimrc|: >
set nocompatible " Disable vi-compatibility
set laststatus=2 " Always show the statusline
- set encoding=utf-8 " Necessary to show unicode glyphs
+ set encoding=utf-8 " Necessary to show Unicode glyphs
Note: If you're using an 88/256-color terminal but still don't see the colored
statusline, you may have to set the following option as well: >
- set t_Co=256 " Explicitly tell vim that the terminal supports 256 colors
+ set t_Co=256 " Explicitly tell Vim that the terminal supports 256 colors
==============================================================================
4. Configuration *Powerline-configuration*
@@ -93,7 +99,7 @@ By default Powerline caches all the statuslines and colors in a cache file in
the plugin's directory (or the vim directory, depending on the installation
method used).
-It's recommended that you enable the cache, as this dramatically improves vim
+It's recommended that you enable the cache, as this dramatically improves Vim
startup time after the cache file has been generated (the plugin usually loads
within ~100ms without the cache and ~1ms with the cache).
@@ -110,7 +116,7 @@ Defaults: "<plugin_directory>/Powerline_<theme>_<colorscheme>_<symbols>.cache"
Powerline provides a command to easily clear the cache after changing your
settings or updating your theme. Simply run the following command to clear
-your cache, and restart vim afterwards: >
+your cache, and restart Vim afterwards: >
:PowerlineClearCache
<
@@ -120,6 +126,11 @@ your cache, and restart vim afterwards: >
It's possible to disable statusline caching by setting this option to 0. This
is mostly useful when developing statuslines.
+Example: >
+
+ let g:Powerline_cache_enabled=0
+<
+
Default: 1
------------------------------------------------------------------------------
@@ -130,9 +141,17 @@ are currently three available options: "compatible", "unicode" and "fancy".
TYPE DESCRIPTION ~
compatible Doesn't use any special characters.
- unicode Simulates icons and arrows using similar unicode glyphs.
+ unicode Simulates icons and arrows using similar Unicode glyphs.
fancy Custom icons and arrows. Requires a patched font.
+Example: >
+
+ let g:Powerline_symbols='fancy'
+<
+
+Default: "compatible"
+
+
Symbols can be inserted into statuslines by using the following variables
(just insert the variables as text in your segments):
@@ -142,28 +161,26 @@ Symbols can be inserted into statuslines by using the following variables
$FT Inserts a filetype symbol
$LINE Inserts a line number symbol
-Default: "compatible"
-
------------------------------------------------------------------------------
4.3.1 Compatible symbols *Powerline-symbols-compatible*
-These symbols will work in any configuration, and do not require a special
-font to work. This option will replace the fancy icons with plain text, and
+These symbols will work in any configuration, and do not require a special
+font to work. This option will replace the fancy icons with plain text, and
the pointy dividers with straight lines.
------------------------------------------------------------------------------
4.3.2 Fancy symbols *Powerline-symbols-fancy*
-These symbols require a custom font to work. A font patcher is provided for
-adding the required symbols to any outline font and some bitmap fonts, see
+These symbols require a custom font to work. A font patcher is provided for
+adding the required symbols to any outline font and some bitmap fonts, see
|Powerline-fonts| and the provided README file for usage details.
------------------------------------------------------------------------------
4.3.3 Overriding symbols *Powerline_symbols_override*
-You can override symbols by adding your symbols to the
-g:Powerline_symbols_override dictionary. Example: If you want the branch
-symbol to be "∓" (hex code 0x2213) and the line symbol to be "L" you can add
+You can override symbols by adding your symbols to the
+g:Powerline_symbols_override dictionary. Example: If you want the branch
+symbol to be "∓" (hex code 0x2213) and the line symbol to be "L" you can add
the following to your |vimrc|: >
let g:Powerline_symbols_override = {
@@ -189,25 +206,38 @@ Example: >
-----------------------------------------------------------------------------
4.4 Powerline_theme *Powerline_theme*
-This option defines the theme Powerline uses. The available themes are located
+This option defines the theme Powerline uses. The available themes are located
in autoload/Powerline/Themes/.
+A theme is a pre-defined set of Powerline segments which make up the status
+line.
+
+Example: >
+
+ let g:Powerline_theme='skwp'
+<
+
Default: "default"
------------------------------------------------------------------------------
4.5 Powerline_colorscheme *Powerline_colorscheme*
-This option defines the colorscheme Powerline uses. The available colorschemes
+This option defines the colorscheme Powerline uses. The available colorschemes
are located in autoload/Powerline/Colorschemes/.
+Example: >
+
+ let g:Powerline_colorscheme='skwp'
+<
+
Default: "default"
------------------------------------------------------------------------------
4.6 Powerline_stl_path_style *Powerline_stl_path_style*
-There are currently four ways to display the current path and file name. The
-default is to only display the file name like the %t statusline item. By
-setting this configuration value you can choose from the following ways
+There are currently four ways to display the current path and file name. The
+default is to only display the file name like Vim's %t 'statusline' item. By
+setting this configuration value you can choose from the following ways to
display the current path and file name:
VALUE DESCRIPTION ~
@@ -221,6 +251,11 @@ display the current path and file name:
relative Display a relative path, similar to the %f statusline item.
full Display the full path, similar to the %F statusline item.
+Example: >
+
+ let g:Powerline_stl_path_style='full'
+<
+
Default: "relative"
==============================================================================
@@ -231,25 +266,25 @@ TODO
==============================================================================
6. Customization *Powerline-customization*
-There are currently two ways of customizing Powerline: Basic customization
-using a couple of functions to insert and remove existing segments from the
-statusline, and advanced customization using your own autoload files. The
-customization features of Powerline allow you to create your own statuslines
+There are currently two ways of customizing Powerline: Basic customization
+using a couple of functions to insert and remove existing segments from the
+statusline, and advanced customization using your own autoload files. The
+customization features of Powerline allow you to create your own statuslines
without ever touching the original source code.
------------------------------------------------------------------------------
6.1 Basic customization *Powerline-basic-customization*
-Powerline provides the following functions to alter the default statusline
-look. These functions should be called from your |vimrc| file or another file
-which is sourced at vim startup.
+Powerline provides the following functions to alter the default statusline
+look. These functions should be called from your |vimrc| file or another file
+which is sourced at Vim startup.
-Note: These functions are currently applied to all statuslines, so if you
-insert a segment after a segment which is present in many statuslines (e.g.
-the "filename" segment), all the statuslines will have the inserted segment.
+Note: These functions are currently applied to all statuslines, so if you
+insert a segment after a segment which is present in many statuslines (e.g.
+the "filename" segment), all the statuslines will have the inserted segment.
This behavior may be changed in a future version of Powerline.
-Note: Remember to clear your cache with |:PowerlineClearCache| after changing
+Note: Remember to clear your cache with |:PowerlineClearCache| after changing
your statusline!
Example: >
@@ -263,10 +298,10 @@ Example: >
*Pl#Theme#InsertSegment*
Pl#Theme#InsertSegment({newsegment}, {location}, {targetsegment})
-This function inserts {newsegment} before or after {targetsegment}. The
-{location} parameter specifies the location of the new segment, valid values
-are "before" and "after". You can see all the available segments in
-autoload/Powerline/Segments.vim and the files specified in
+This function inserts {newsegment} before or after {targetsegment}. The
+{location} parameter specifies the location of the new segment, valid values
+are "before" and "after". You can see all the available segments in
+autoload/Powerline/Segments.vim and the files specified in
|Powerline-cust-segments|.
Pl#Theme#RemoveSegment({targetsegment}) *Pl#Theme#RemoveSegment*
@@ -280,21 +315,21 @@ This function replaces {oldsegment} with {newsegment}.
------------------------------------------------------------------------------
6.2 Advanced customization *Powerline-advanced-customization*
-Because Powerline utilizes vim's autoload functionality, you can easily create
-your own segments, themes, functions and colorschemes without touching the
-original source code. This is a bit more complex than using the utility
+Because Powerline utilizes Vim's autoload functionality, you can easily create
+your own segments, themes, functions and colorschemes without touching the
+original source code. This is a bit more complex than using the utility
functions, but it allows you to do a lot more with your statusline.
-Your custom autoload files should be stored in your |runtimepath| (usually in
+Your custom autoload files should be stored in your |runtimepath| (usually in
"~/.vim/autoload/Powerline/*").
-Note: Remember to clear your cache with |:PowerlineClearCache| after changing
+Note: Remember to clear your cache with |:PowerlineClearCache| after changing
your statusline!
6.2.1 Colorschemes *Powerline-cust-colorschemes*
------------------------------------------------------------------------------
-Colorschemes should be stored as separate files in
+Colorschemes should be stored as separate files in
{runtimepath}/autoload/Powerline/Colorschemes/.
SYNTAX ~
@@ -308,7 +343,7 @@ TODO
6.2.2 Functions *Powerline-cust-functions*
------------------------------------------------------------------------------
-Functions should be stored as separate files in
+Functions should be stored as separate files in
{runtimepath}/autoload/Powerline/Functions/.
SYNTAX ~
@@ -322,7 +357,7 @@ TODO
6.2.3 Segments *Powerline-cust-segments*
------------------------------------------------------------------------------
-Segments should be stored as separate files in
+Segments should be stored as separate files in
{runtimepath}/autoload/Powerline/Segments/.
SYNTAX ~
@@ -336,7 +371,7 @@ TODO
6.2.4 Themes *Powerline-cust-themes*
------------------------------------------------------------------------------
-Themes should be stored as separate files in
+Themes should be stored as separate files in
{runtimepath}/autoload/Powerline/Themes/.
SYNTAX ~

0 comments on commit b3e0a46

Please sign in to comment.
Something went wrong with that request. Please try again.