dotfiles/vim/plugins/GoldenView/README.md

344 lines
11 KiB
Markdown
Raw Normal View History

2018-04-05 13:06:54 +02:00
# Always have a nice view for vim split windows
------------- - -----------------------------------------------
Plugin : GoldenView.vim
Author : Zhao Cai
EMail : caizhaoff@gmail.com
Homepage : http://zhaocai.github.io/GoldenView.Vim/
Vim.org : http://www.vim.org/scripts/script.php?script_id=4529
Version : 1.3.6
Date Created : Tue 18 Sep 2012 05:23:13 PM EDT
Last Modified : Mon 22 Apr 2013 05:55:22 PM EDT
------------- - -----------------------------------------------
The initial motive for [GoldenView][GoldenView] comes from the frustration of using other vim plugins to auto-resize split windows. The idea is deadly simple and very useful: **resize the focused window to a proper size.** However, in practice, many hiccups makes **auto-resizing** not a smooth experience. Below are a list of issues [GoldenView][GoldenView] attempts to solve:
First and the most important one, auto-resizing should play nicely with existing plugins like `tagbar`, `vimfiler`, `unite`, `VOoM`, `quickfix`, `undotree`, `gundo`, etc. These windows should manage there own window size.
Second, auto-resizing should take care of **the other windows** too. Resizing the focused window may cause the other windows become too small. When you have 4+ split windows, auto-resizing may just make a mess out of it.
![GoldView Screencast]( http://dl.dropboxusercontent.com/u/1897501/Screencasts/GoldenView.gif )
## Features
[GoldenView][GoldenView] has preliminarily solved the issues described above. It also provides other features. Bascally, it does two things:
### 1. AutoResizing
First of all, it automatically resize the focused split window to a "golden" view based on [golden ratio][golden-ratio-wikipedia] and `textwidth`.
### 2. Tiled Windows Management
Second, it maps a single key (`<C-L>` by default) to nicely split windows to tiled windows.
```
----+----------------+------------+---+
| | | | |
| F | | S1 | T |
| I | +------------| A |
| L | | S2 | G |
| E | MAIN PANE +------------+ B |
| R | | S3 | A |
| | | | R |
| | | | |
+---+----------------+------------+---+
```
To get this view, just hit `<C-L>` 4 times. or, if you have a large monitor, you may get tiled windows below.
```
----+---------------+--------------+------------+---+
| | | | | |
| F | | | S1 | T |
| I | | +------------| A |
| L | | M2 | S2 | G |
| E | MAIN PANE | +------------+ B |
| R | | | S3 | A |
| | | | | B |
| | | | | |
+---+---------------+--------------+------------+---+
```
To quickly switch between those windows, a few keys are mapped to
- Focus to the main window
- Switch with the `MAIN PANE`, the largest, smallest, etc.
- Jump to the next and previous window
## Installation
Install [GoldenView][GoldenView] is the *same as installing other vim plugins*. If experienced with vim, you can skim the example below and move to [next section](#quick-start).
### **Option A** - With [Plugin Manager][vim-plugin-manager] ( **recommended** )
If you use plugin managers like *Pathogen*, *vundle*, *neobundle*, *vim-addon-manager*, etc., just unarchive the zip file or clone the [GoldenView][GoldenView] repo from `git://github.com/zhaocai/GoldenView.git` into your local plugin installation directory (most likely `~/.vim/bundle/`). Then add corresponding scripts in .vimrc for the bundle manager you are using.
**Example**:
- *neobundle*:
```vim
NeoBundle 'zhaocai/GoldenView.Vim' "Always have a nice view for vim split windows
```
- *vundle*:
```vim
Bundle 'zhaocai/GoldenView.Vim'
```
- *vim-addon-manager*:
```vim
call vam#ActivateAddons(['GoldenView.Vim'], {'auto_install' : 1})
```
### **Option B** - Without [Plugin Manager][vim-plugin-manager]
Unarchive the zip file into a directory that is under `runtimepath` of your vim, `~/.vim` for example.
## Quick Start
[GoldenView][GoldenView] should work out of the box without configuration. It should automatically start to resize focused window to [golden ratio][golden-ratio-wikipedia] based on `textwidth` and vim available size. You may start to play with it now.
To get you started, a few default keys are mapped as below:
```vim
" 1. split to tiled windows
nmap <silent> <C-L> <Plug>GoldenViewSplit
" 2. quickly switch current window with the main pane
" and toggle back
nmap <silent> <F8> <Plug>GoldenViewSwitchMain
nmap <silent> <S-F8> <Plug>GoldenViewSwitchToggle
" 3. jump to next and previous window
nmap <silent> <C-N> <Plug>GoldenViewNext
nmap <silent> <C-P> <Plug>GoldenViewPrevious
```
The meaning of those keys are self-explaining. A general workflow would be `<Plug>GoldenViewSplit` key to quickly and nicely split windows to the layout as below. Then you may open your files.
```
----+----------------+------------+---+
| | | | |
| F | | S1 | T |
| I | +------------| A |
| L | | S2 | G |
| E | MAIN PANE +------------+ B |
| R | | S3 | A |
| | | | R |
| | | | |
+---+----------------+------------+---+
```
To switch `S1` with `MAIN PANE`, in `S1` and hit `<Plug>GoldenViewSwitchMain`. To switch back, hit `<Plug>GoldenViewSwitchToggle` in either `MAIN PAIN` or `S1`
#### g:goldenview__enable_default_mapping
Every experienced vim user has a different set of key mappings. If you you are (most likely) unhappy about some of the mappings, map you own keys as below:
```vim
let g:goldenview__enable_default_mapping = 0
nmap <silent> <MY_KEY> <Plug>GoldenViewSplit
" ... and so on
```
#### g:goldenview__enable_at_startup
if you do not want to start auto-resizing automatically, you can put the following script in your vimrc.
```vim
let g:goldenview__enable_at_startup = 0
```
## More Commands and Mappings
### `:ToggleGoldenViewAutoResize`
### `:DisableGoldenViewAutoResize`
### `:EnableGoldenViewAutoResize`
These commands toggle, enable, and disable GoldenView auto-resizing.
### `:GoldenViewResize`
this command do manual resizing of focused window.
You can also map a key for this as below:
```vim
nmap <silent> <YOUR_KEY> <Plug>GoldenViewResize
```
### `:SwitchGoldenViewMain`
### `:SwitchGoldenViewLargest`
### `:SwitchGoldenViewSmallest`
these commands do as it named.
You can also add mappings as below. ( no default keys for these mappings)
```vim
nmap <silent> <YOUR_KEY> <Plug>GoldenViewSwitchWithLargest
nmap <silent> <YOUR_KEY> <Plug>GoldenViewSwitchWithSmallest
```
Other switch rules can be easily defined. If you have some ideas, please post to [github issue][GoldenViewIssue] for discussion.
## Rules
[GoldenView][] defines two rules:
### `g:goldenview__ignore_urule`
is to "ignore" - allow those special buffers to manage their own window size.
### `g:goldenview__restore_urule`
is to "restore" - restore window size of some of special buffers.
The `urule` (user rules) are like this, which will be normalize at runtime for faster processing.
```vim
\{
\ 'filetype' : [
\ '' ,
\ 'qf' , 'vimpager', 'undotree', 'tagbar',
\ 'nerdtree', 'vimshell', 'vimfiler', 'voom' ,
\ 'tabman' , 'unite' , 'quickrun', 'Decho' ,
\ ],
\ 'buftype' : [
\ 'nofile' ,
\ ],
\ 'bufname' : [
\ 'GoToFile' , 'diffpanel_\d\+' ,
\ '__Gundo_Preview__' , '__Gundo__' ,
\ '\[LustyExplorer-Buffers\]' , '\-MiniBufExplorer\-' ,
\ '_VOOM\d\+$' , '__Urannotate_\d\+__' ,
\ '__MRU_Files__' ,
\ ],
\},
```
## Profiles
[GoldenView][] defines two profile:
### `g:goldenview__active_profile`
defines the functions and preferences to auto resize windows.
### `g:goldenview__reset_profile`
defines reset preferences to restore everything to default.
`function GoldenView#ExtendProfile()` is provided to customize preferences.
For more details, please read the source code! :)
## Troubleshooting:
### Please do not resize me!
[GoldenView][] maintains rules for "common" cases. But vim offers a great variety of plugins which defines buffers for special purposes. If you find some special buffers which is supposed to not be auto-resized. Please check `g:goldenview__ignore_urule`. You may extend the `g:goldenview__active_profile` yourself or post the issue to [github issue][GoldenViewIssue] for adding it to builtin support.
### [minibufexpl.vim][] takes 5+ lines
Check my fork [minibufexpl.vim][] to see if it is working for you. I have send pull request to the origin repo.
### I cannot resize window height to < 7
This is features. As mentioned in the [Introduction](#always-have-a-nice-view-for-vim-split-windows) section, there is no normal cases to have a normal window too small. For special cases like [minibufexpl.vim][], it can be handled case by case.
However, if you really want to have small windows. It can be done by :
```vim
" Extend a new profile named 'small-height' from default profile.
"
" 1. Change "2" to your desire minimal height
" 2. Change "small-height" to the profile name you like
" ---------------------------------------------------------------
call GoldenView#ExtendProfile('small-height', {
\ 'other_window_winheight' : 2 ,
\ })
let g:goldenview__active_profile = 'small-height'
```
(refer to issue #5)
### I still have Issues:
If you have any issues, please post it to [github issue][GoldenViewIssue] for discussion.
Remember to run the following command and post the results.
```vim
echo GoldenView#Info()
```
## Contributors
## RELEASE HISTORY
Refer to [History.md]( https://github.com/zhaocai/GoldenView.Vim/blob/master/History.md )
## LICENSE:
Copyright (c) 2013 Zhao Cai \<caizhaoff@gmail.com\>
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <http://www.gnu.org/licenses/>.
[dwm]: http://www.vim.org/scripts/script.php?script_id=4186
[golden-ratio-plugin]: http://www.vim.org/scripts/script.php?script_id=3690
[golden-ratio-wikipedia]: http://en.wikipedia.org/wiki/Golden_ratio
[zl]: https://github.com/zhaocai/zl.vim "zl.vim vim script library"
[GoldenView]: http://zhaocai.github.io/GoldenView.Vim/ "GoldenView Homepage"
[GoldenViewCode]: https://github.com/zhaocai/GoldenView.Vim "GoldenView Vim Plugin"
[vim-plugin-manager]: http://vim-scripts.org/vim/tools.html "Vim Plugin Manangers"
[GoldenViewIssue]: https://github.com/zhaocai/GoldenView.Vim/issues "GoldenView Issue Track"
[minibufexpl.vim]: https://github.com/zhaocai/minibufexpl.vim