Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Update Powerline.txt help file. Fixes Lokaltog#168. #173

Closed
wants to merge 1 commit into from

2 participants

@dougireton
  1. Add usage paragraphs
  2. Add option examples.
  3. Fix capitalization of Unicode and Vim
@dougireton dougireton Update Powerline.txt help file.
1. Add usage paragraphs
2. Add option examples.
3. Fix capitalization of Unicode and Vim
b3e0a46
@dougireton

Sorry about the whitespace fixes in this commit.

@dougireton

@Lokaltog in there anything in this commit which would prevent you from merging it? If you just haven't gotten time to review yet, no worries.

Thanks,

Doug Ireton

@Lokaltog
Owner

Sorry man, I've been on vacation. I'm reviewing and merging all the pull requests now. :)

@Lokaltog Lokaltog referenced this pull request from a commit
@Lokaltog Add usage examples and better explanations to docs
Thanks to @dougireton.

Refs #173.
Closes #168.
288fc56
@Lokaltog Lokaltog closed this
@neersighted neersighted referenced this pull request from a commit
@Lokaltog Add usage examples and better explanations to docs
Thanks to @dougireton.

Refs #173.
Closes #168.
5870cc7
@obxhdx obxhdx referenced this pull request from a commit
@Lokaltog Add repository_status vim segment
Split segment highlighting compared to the file_vcs_status segment is
missing.

Refs #173.
c8d4e58
@obxhdx obxhdx referenced this pull request from a commit
@Lokaltog Add modified_buffers segment
This segment returns a comma-separated list of modified buffers. The
segment is not enabled by default.

Closes #173.
d386ae7
@obxhdx obxhdx referenced this pull request from a commit
@Lokaltog Add repository_status vim segment
Split segment highlighting compared to the file_vcs_status segment is
missing.

Refs #173.
e16b914
@obxhdx obxhdx referenced this pull request from a commit
@Lokaltog Add modified_buffers segment
This segment returns a comma-separated list of modified buffers. The
segment is not enabled by default.

Closes #173.
169d79b
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jul 9, 2012
  1. @dougireton

    Update Powerline.txt help file.

    dougireton authored
    1. Add usage paragraphs
    2. Add option examples.
    3. Fix capitalization of Unicode and Vim
This page is out of date. Refresh to see the latest.
Showing with 82 additions and 47 deletions.
  1. +82 −47 doc/Powerline.txt
View
129 doc/Powerline.txt
@@ -46,7 +46,7 @@ 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*
@@ -54,14 +54,20 @@ functional vim statuslines.
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 ~
Something went wrong with that request. Please try again.