[rbdr/dotfiles] / vim / doc / Powerline.txt

*Powerline.txt*	For Vim version 7.3.	Last change: 2011 Nov 23

                                            ______
         _________                          \    /__
         \_____   \______  _  _____________ /   /'__' ___   ____
          |    ___/  _ \ \/ \/ / __ \_  ___\   / |  |/   \_/ __ \
          |   |  |  (_) \  _  /  ___/|  |  /  /__|  |  |  \  ___/
          '___'   \____/ \/ \/ \___  |__' /___  /'__'__|  /\___ \
                                   \/        / /        \/     \/
                                            | /
                                            |/
                                            '

==============================================================================
CONTENTS                                                  *Powerline-contents*

    1. Introduction ....................... |Powerline-introduction|
    2. Usage .............................. |Powerline-usage|
    3. Requirements ....................... |Powerline-requirements|
       3.1 Recommended settings ........... |Powerline-recommended-settings|
    4. Configuration ...................... |Powerline-configuration|
       4.1 Powerline_cache_file ........... |Powerline_cache_file|
           4.1.1 Clearing the cache ....... |:PowerlineClearCache|
       4.2 Powerline_cache_enabled ........ |Powerline_cache_enabled|
       4.3 Powerline_symbols .............. |Powerline_symbols|
           4.3.1 Compatible symbols ....... |Powerline-symbols-compatible|
           4.3.2 Fancy symbols ............ |Powerline-symbols-fancy|
       4.4 Powerline_theme ................ |Powerline_theme|
       4.5 Powerline_colorscheme .......... |Powerline_colorscheme|
    5. Fonts .............................. |Powerline-fonts|
    6. Customization ...................... |Powerline-customization|
       6.1 Basic customization ............ |Powerline-basic-customization|
       6.2 Advanced customization ......... |Powerline-advanced-customization|
           6.2.1 Colorschemes ............. |Powerline-cust-colorschemes|
           6.2.2 Functions ................ |Powerline-cust-functions|
           6.2.3 Segments ................. |Powerline-cust-segments|
           6.2.4 Themes ................... |Powerline-cust-themes|
    7. License ............................ |Powerline-license|
    8. Known issues ....................... |Powerline-known-issues|
    9. Contributing ....................... |Powerline-contributing|

==============================================================================
1. Introduction                           *Powerline* *Powerline-introduction*

Powerline is a utility plugin which allows you to create better-looking, more 
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.

==============================================================================
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 
to work properly.

The plugin only works with vim running in an 88/256-color terminal or gvim.

Vi-compatible mode must be disabled.

------------------------------------------------------------------------------
3.1 Recommended settings                      *Powerline-recommended-settings*

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

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

==============================================================================
4. Configuration                                     *Powerline-configuration*

Powerline will work fine without any user configuration, but default behavior 
can be overridden by setting configuration variables globally in your |vimrc| 
file.

------------------------------------------------------------------------------
4.1 Powerline_cache_file                                *Powerline_cache_file*

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 
startup time after the cache file has been generated (the plugin usually loads 
within ~100ms without the cache and ~1ms with the cache).

Note: The default cache filename includes the current theme, colorscheme and 
symbol settings in order to tie the cache file your current configuration, so 
the cache file will be regenerated when you change any settings. This may 
leave several old cache files in your vim folder, and these may safely be 
deleted.

Defaults: "<plugin_directory>/Powerline_<theme>_<colorscheme>_<symbols>.cache"

------------------------------------------------------------------------------
4.1.1 Clearing the cache                                *:PowerlineClearCache*

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: >

    :PowerlineClearCache
<
------------------------------------------------------------------------------
4.2 Powerline_cache_enabled                          *Powerline_cache_enabled*

It's possible to disable statusline caching by setting this option to 0. This 
is mostly useful when developing statuslines.

Default: 1

------------------------------------------------------------------------------
4.3 Powerline_symbols                                      *Powerline_symbols*

This option defines which set of symbols and dividers you want to use. There 
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.
    fancy          Custom icons and arrows. Requires a patched font.

Symbols can be inserted into statuslines by using the following variables 
(just insert the variables as text in your segments):

    VARIABLE       DESCRIPTION ~
    $BRANCH        Inserts a branch symbol
    $RO            Inserts a read-only symbol
    $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 
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 
|Powerline-fonts| and the provided README file for usage details.

------------------------------------------------------------------------------
4.4 Powerline_theme                                          *Powerline_theme*

This option defines the theme Powerline uses. The available themes are located 
in autoload/Powerline/Themes/.

Default: "default"

------------------------------------------------------------------------------
4.5 Powerline_colorscheme                              *Powerline_colorscheme*

This option defines the colorscheme Powerline uses. The available colorschemes 
are located in autoload/Powerline/Colorschemes/.

Default: "default"

==============================================================================
5. Fonts                                                     *Powerline-fonts*

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 
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.

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 
your statusline!

Example: >

    " Insert the charcode segment after the filetype segment
    call Pl#Theme#InsertSegment('charcode', 'after', 'filetype')

    " Replace the scrollpercent segment with the charcode segment
    call Pl#Theme#ReplaceSegment('scrollpercent', 'fileinfo')
<
                                                      *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 
|Powerline-cust-segments|.

Pl#Theme#RemoveSegment({targetsegment})               *Pl#Theme#RemoveSegment*

This function removes the {targetsegment} segment entirely.

Pl#Theme#ReplaceSegment({oldsegment}, {newsegment})  *Pl#Theme#ReplaceSegment*

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 
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 
"~/.vim/autoload/Powerline/*").

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 
{runtimepath}/autoload/Powerline/Colorschemes/.

SYNTAX ~

TODO

EXAMPLE ~

TODO

6.2.2 Functions                                     *Powerline-cust-functions*
------------------------------------------------------------------------------

Functions should be stored as separate files in 
{runtimepath}/autoload/Powerline/Functions/.

SYNTAX ~

TODO

EXAMPLE ~

TODO

6.2.3 Segments                                       *Powerline-cust-segments*
------------------------------------------------------------------------------

Segments should be stored as separate files in 
{runtimepath}/autoload/Powerline/Segments/.

SYNTAX ~

TODO

EXAMPLE ~

TODO

6.2.4 Themes                                           *Powerline-cust-themes*
------------------------------------------------------------------------------

Themes should be stored as separate files in 
{runtimepath}/autoload/Powerline/Themes/.

SYNTAX ~

TODO

EXAMPLE ~

TODO

==============================================================================
7. License                                                 *Powerline-license*

Creative Commons Attribution-ShareAlike 3.0 Unported

http://creativecommons.org/licenses/by-sa/3.0/

==============================================================================
8. Known issues                                       *Powerline-known-issues*

See the issue tracker at
https://github.com/Lokaltog/vim-powerline/issues

==============================================================================
9. Contributing                                       *Powerline-contributing*

If you experience any bugs or have feature requests, please open an issue on
GitHub. Fork the source repository on GitHub and send a pull request if you
have any code improvements.

Author: Kim Silkebækken <kim.silkebaekken+vim@gmail.com>
Source repository: https://github.com/Lokaltog/vim-powerline

==============================================================================
vim:tw=78:sw=4:ts=8:ft=help:norl:
Commit	Line	Data
321ecaca BB	1	Powerline.txt For Vim version 7.3. Last change: 2011 Nov 23
	2
	3	______
	4	_________ \ /__
	5	\_____ \______ _ _____________ / /'__' ___ ____
	6	\| ___/ _ \ \/ \/ / __ \_ ___\ / \| \|/ \_/ __ \
	7	\| \| \| (_) \ _ / ___/\| \| / /__\| \| \| \ ___/
	8	'___' \____/ \/ \/ \___ \|__' /___ /'__'__\| /\___ \
	9	\/ / / \/ \/
	10	\| /
	11	\|/
	12	'
	13
	14	==============================================================================
	15	CONTENTS Powerline-contents
	16
	17	1. Introduction ....................... \|Powerline-introduction\|
	18	2. Usage .............................. \|Powerline-usage\|
	19	3. Requirements ....................... \|Powerline-requirements\|
	20	3.1 Recommended settings ........... \|Powerline-recommended-settings\|
	21	4. Configuration ...................... \|Powerline-configuration\|
	22	4.1 Powerline_cache_file ........... \|Powerline_cache_file\|
	23	4.1.1 Clearing the cache ....... \|:PowerlineClearCache\|
	24	4.2 Powerline_cache_enabled ........ \|Powerline_cache_enabled\|
	25	4.3 Powerline_symbols .............. \|Powerline_symbols\|
	26	4.3.1 Compatible symbols ....... \|Powerline-symbols-compatible\|
	27	4.3.2 Fancy symbols ............ \|Powerline-symbols-fancy\|
	28	4.4 Powerline_theme ................ \|Powerline_theme\|
	29	4.5 Powerline_colorscheme .......... \|Powerline_colorscheme\|
	30	5. Fonts .............................. \|Powerline-fonts\|
	31	6. Customization ...................... \|Powerline-customization\|
	32	6.1 Basic customization ............ \|Powerline-basic-customization\|
	33	6.2 Advanced customization ......... \|Powerline-advanced-customization\|
	34	6.2.1 Colorschemes ............. \|Powerline-cust-colorschemes\|
	35	6.2.2 Functions ................ \|Powerline-cust-functions\|
	36	6.2.3 Segments ................. \|Powerline-cust-segments\|
	37	6.2.4 Themes ................... \|Powerline-cust-themes\|
	38	7. License ............................ \|Powerline-license\|
	39	8. Known issues ....................... \|Powerline-known-issues\|
	40	9. Contributing ....................... \|Powerline-contributing\|
	41
	42	==============================================================================
	43	1. Introduction Powerline Powerline-introduction
	44
	45	Powerline is a utility plugin which allows you to create better-looking, more
	46	functional vim statuslines.
	47
	48	==============================================================================
	49	2. Usage Powerline-usage
	50
	51	Powerline is automatically enabled when it's installed, either by unzipping
	52	the provided archive or by adding it as a Pathogen/Vundle bundle.
	53
	54	==============================================================================
	55	3. Requirements Powerline-requirements
	56
	57	Powerline has been developed and tested in vim 7.3, but it should run without
	58	any problems in vim 7.2. The default configuration requires a Unix-like system
	59	to work properly.
	60
	61	The plugin only works with vim running in an 88/256-color terminal or gvim.
	62
	63	Vi-compatible mode must be disabled.
	64
65	------------------------------------------------------------------------------
66	3.1 Recommended settings Powerline-recommended-settings
67
68	The following configuration options should be set in your \|vimrc\|: >
69
70	set nocompatible " Disable vi-compatibility
71	set laststatus=2 " Always show the statusline
72	set encoding=utf-8 " Necessary to show unicode glyphs
73
74	Note: If you're using an 88/256-color terminal but still don't see the colored
75	statusline, you may have to set the following option as well: >
76
77	set t_Co=256 " Explicitly tell vim that the terminal supports 256 colors
78
79	==============================================================================
80	4. Configuration Powerline-configuration
81
82	Powerline will work fine without any user configuration, but default behavior
83	can be overridden by setting configuration variables globally in your \|vimrc\|
84	file.
85
86	------------------------------------------------------------------------------
87	4.1 Powerline_cache_file Powerline_cache_file
88
89	By default Powerline caches all the statuslines and colors in a cache file in
90	the plugin's directory (or the vim directory, depending on the installation
91	method used).
92
93	It's recommended that you enable the cache, as this dramatically improves vim
94	startup time after the cache file has been generated (the plugin usually loads
95	within ~100ms without the cache and ~1ms with the cache).
96
97	Note: The default cache filename includes the current theme, colorscheme and
98	symbol settings in order to tie the cache file your current configuration, so
99	the cache file will be regenerated when you change any settings. This may
100	leave several old cache files in your vim folder, and these may safely be
101	deleted.
102
103	Defaults: "<plugin_directory>/Powerline_<theme>_<colorscheme>_<symbols>.cache"
104
105	------------------------------------------------------------------------------
106	4.1.1 Clearing the cache :PowerlineClearCache
107
108	Powerline provides a command to easily clear the cache after changing your
109	settings or updating your theme. Simply run the following command to clear
110	your cache, and restart vim afterwards: >
111
112	:PowerlineClearCache
113	<
114	------------------------------------------------------------------------------
115	4.2 Powerline_cache_enabled Powerline_cache_enabled
116
117	It's possible to disable statusline caching by setting this option to 0. This
118	is mostly useful when developing statuslines.
119
120	Default: 1
121
122	------------------------------------------------------------------------------
123	4.3 Powerline_symbols Powerline_symbols
124
125	This option defines which set of symbols and dividers you want to use. There
126	are currently three available options: "compatible", "unicode" and "fancy".
127
128	TYPE DESCRIPTION ~
129	compatible Doesn't use any special characters.
130	unicode Simulates icons and arrows using similar unicode glyphs.
131	fancy Custom icons and arrows. Requires a patched font.
132
133	Symbols can be inserted into statuslines by using the following variables
134	(just insert the variables as text in your segments):
135
136	VARIABLE DESCRIPTION ~
137	$BRANCH Inserts a branch symbol
138	$RO Inserts a read-only symbol
139	$FT Inserts a filetype symbol
140	$LINE Inserts a line number symbol
141
142	Default: "compatible"
143
144	------------------------------------------------------------------------------
145	4.3.1 Compatible symbols Powerline-symbols-compatible
146
147	These symbols will work in any configuration, and do not require a special
148	font to work. This option will replace the fancy icons with plain text, and
149	the pointy dividers with straight lines.
150
151	------------------------------------------------------------------------------
152	4.3.2 Fancy symbols Powerline-symbols-fancy
153
154	These symbols require a custom font to work. A font patcher is provided for
155	adding the required symbols to any outline font and some bitmap fonts, see
156	\|Powerline-fonts\| and the provided README file for usage details.
157
158	------------------------------------------------------------------------------
159	4.4 Powerline_theme Powerline_theme
160
161	This option defines the theme Powerline uses. The available themes are located
162	in autoload/Powerline/Themes/.
163
164	Default: "default"
165
166	------------------------------------------------------------------------------
167	4.5 Powerline_colorscheme Powerline_colorscheme
168
169	This option defines the colorscheme Powerline uses. The available colorschemes
170	are located in autoload/Powerline/Colorschemes/.
171
172	Default: "default"
173
174	==============================================================================
175	5. Fonts Powerline-fonts
176
177	TODO
178
179	==============================================================================
180	6. Customization Powerline-customization
181
182	There are currently two ways of customizing Powerline: Basic customization
183	using a couple of functions to insert and remove existing segments from the
184	statusline, and advanced customization using your own autoload files. The
185	customization features of Powerline allow you to create your own statuslines
186	without ever touching the original source code.
187
188	------------------------------------------------------------------------------
189	6.1 Basic customization Powerline-basic-customization
190
191	Powerline provides the following functions to alter the default statusline
192	look. These functions should be called from your \|vimrc\| file or another file
193	which is sourced at vim startup.
194
195	Note: These functions are currently applied to all statuslines, so if you
196	insert a segment after a segment which is present in many statuslines (e.g.
197	the "filename" segment), all the statuslines will have the inserted segment.
198	This behavior may be changed in a future version of Powerline.
199
200	Note: Remember to clear your cache with \|:PowerlineClearCache\| after changing
201	your statusline!
202
203	Example: >
204
205	" Insert the charcode segment after the filetype segment
206	call Pl#Theme#InsertSegment('charcode', 'after', 'filetype')
207
208	" Replace the scrollpercent segment with the charcode segment
209	call Pl#Theme#ReplaceSegment('scrollpercent', 'fileinfo')
210	<
211	Pl#Theme#InsertSegment
212	Pl#Theme#InsertSegment({newsegment}, {location}, {targetsegment})
213
214	This function inserts {newsegment} before or after {targetsegment}. The
215	{location} parameter specifies the location of the new segment, valid values
216	are "before" and "after". You can see all the available segments in
217	autoload/Powerline/Segments.vim and the files specified in
218	\|Powerline-cust-segments\|.
219
220	Pl#Theme#RemoveSegment({targetsegment}) Pl#Theme#RemoveSegment
221
222	This function removes the {targetsegment} segment entirely.
223
224	Pl#Theme#ReplaceSegment({oldsegment}, {newsegment}) Pl#Theme#ReplaceSegment
225
226	This function replaces {oldsegment} with {newsegment}.
227
228	------------------------------------------------------------------------------
229	6.2 Advanced customization Powerline-advanced-customization
230
231	Because Powerline utilizes vim's autoload functionality, you can easily create
232	your own segments, themes, functions and colorschemes without touching the
233	original source code. This is a bit more complex than using the utility
234	functions, but it allows you to do a lot more with your statusline.
235
236	Your custom autoload files should be stored in your \|runtimepath\| (usually in
237	"~/.vim/autoload/Powerline/*").
238
239	Note: Remember to clear your cache with \|:PowerlineClearCache\| after changing
240	your statusline!
241
242	6.2.1 Colorschemes Powerline-cust-colorschemes
243	------------------------------------------------------------------------------
244
245	Colorschemes should be stored as separate files in
246	{runtimepath}/autoload/Powerline/Colorschemes/.
247
248	SYNTAX ~
249
250	TODO
251
252	EXAMPLE ~
253
254	TODO
255
256	6.2.2 Functions Powerline-cust-functions
257	------------------------------------------------------------------------------
258
259	Functions should be stored as separate files in
260	{runtimepath}/autoload/Powerline/Functions/.
261
262	SYNTAX ~
263
264	TODO
265
266	EXAMPLE ~
267
268	TODO
269
270	6.2.3 Segments Powerline-cust-segments
271	------------------------------------------------------------------------------
272
273	Segments should be stored as separate files in
274	{runtimepath}/autoload/Powerline/Segments/.
275
276	SYNTAX ~
277
278	TODO
279
280	EXAMPLE ~
281
282	TODO
283
284	6.2.4 Themes Powerline-cust-themes
285	------------------------------------------------------------------------------
286
287	Themes should be stored as separate files in
288	{runtimepath}/autoload/Powerline/Themes/.
289
290	SYNTAX ~
291
292	TODO
293
294	EXAMPLE ~
295
296	TODO
297
298	==============================================================================
299	7. License Powerline-license
300
301	Creative Commons Attribution-ShareAlike 3.0 Unported
302
303	http://creativecommons.org/licenses/by-sa/3.0/
304
305	==============================================================================
306	8. Known issues Powerline-known-issues
307
308	See the issue tracker at
309	https://github.com/Lokaltog/vim-powerline/issues
310
311	==============================================================================
312	9. Contributing Powerline-contributing
313
314	If you experience any bugs or have feature requests, please open an issue on
315	GitHub. Fork the source repository on GitHub and send a pull request if you
316	have any code improvements.
317
318	Author: Kim Silkebækken <kim.silkebaekken+vim@gmail.com>
319	Source repository: https://github.com/Lokaltog/vim-powerline
320
321	==============================================================================
322	vim:tw=78:sw=4:ts=8:ft=help:norl: