Fixes #650 Correct window positioning defaults (#652)

* Fix for window positioning
With default case having multiple vertically split windows, the tagbar
window should open on the far right of the screen. When the feature in
pull-request 630 was added, this behavior changed to open the tagbar
window relative to the current window. This commit will fix that by
allowing direct usage of the vim split options.

Validated the following cases for the old default values. These all
still behave the same way as prior to pull-request 630 when the tagbar
is activated in the `active` window shown in the below examples:
```
	" No options
	+-----------------------------------+
	| preview                           |
	+--------+--------+--------+--------+
	| edit   | edit   | edit   | tagbar |
	|        | active |        |        |
	+--------+--------+--------+--------+

	" tagbar on left, preview above
	let g:tagbar_left = 1
	+-----------------------------------+
	| preview                           |
	+--------+--------+--------+--------+
	| tagbar | edit   | edit   | edit   |
	|        |        | active |        |
	+--------+--------+--------+--------+

	" tagbar on bottom, preview to right of tagbar
	let g:tagbar_vertical = 10
	+--------+---------------+--------+
	| edit   | edit          | edit   |
	|        | active        |        |
	|        +-----+---------+        |
	|        | tag | preview |        |
	+--------+-----+---------+--------+

	" tagbar on top, preview to the right of tagbar
	let g:tagbar_left = 1
	let g:tagbar_vertical = 10
	+--------+-----+---------+--------+
	| edit   | tag | preview | edit   |
	|        +-----+---------+        |
	|        | edit          |        |
	|        | active        |        |
	+--------+---------------+--------+

```

New values also all validated using the following:
```
" Behaves the same as no options
let g:tagbar_position = 'right'

" Behaves the same as g:tagbar_left = 1
let g:tagbar_position = 'left'

" Behaves the same as g:tagbar_vertical = <#>
let g:tagbar_position = 'bottom'

" Behaves the same as g:tagbar_left = 1 | g:tagbar_vertical = <#>
let g:tagbar_position = 'top'
```

* #650 - Fix typo in doc/tagbar.txt for g:tagbar_height option

autoload/tagbar.vim

@@ -879,24 +879,15 @@ function! s:OpenWindow(flags) abort
     endif
 
     let s:window_opening = 1
-    if g:tagbar_position =~# '\v(bottom|right)'
-        let openpos = 'rightbelow '
-    else
-        let openpos = 'leftabove '
-    endif
-    if g:tagbar_position =~# '\v(left|right)'
+    if g:tagbar_position =~# 'vertical'
+        let size = g:tagbar_width
         let mode = 'vertical '
-        let width = g:tagbar_width
     else
+        let size = g:tagbar_height
         let mode = ''
-        if g:tagbar_height > 0
-            let width = g:tagbar_height
-        else
-            let width = g:tagbar_vertical
-        endif
     endif
-    exe 'silent keepalt ' . openpos . mode . width . 'split ' . s:TagbarBufName()
-    exe 'silent ' . mode . 'resize ' . width
+    exe 'silent keepalt ' . g:tagbar_position . size . 'split ' . s:TagbarBufName()
+    exe 'silent ' . mode . 'resize ' . size
     unlet s:window_opening
 
     call s:InitWindow(autoclose)
@@ -2294,7 +2285,7 @@ function! s:ShowInPreviewWin() abort
     " We want the preview window to be relative to the file window in normal
     " (horizontal) mode, and relative to the Tagbar window in vertical mode,
     " to make the best use of space.
-    if g:tagbar_position !~# '\v(top|bottom)'
+    if g:tagbar_position =~# 'vertical'
         call s:GotoFileWindow(taginfo.fileinfo, 1)
         call s:mark_window()
     endif
@@ -2305,15 +2296,15 @@ function! s:ShowInPreviewWin() abort
         silent execute
             \ g:tagbar_previewwin_pos . ' pedit ' .
             \ fnameescape(taginfo.fileinfo.fpath)
-        if g:tagbar_position =~# '\v(top|bottom)'
+        if g:tagbar_position !~# 'vertical'
             silent execute 'vertical resize ' . g:tagbar_width
         endif
         " Remember that the preview window was opened by Tagbar so we can
         " safely close it by ourselves
         let s:pwin_by_tagbar = 1
     endif
 
-    if g:tagbar_position =~# '\v(top|bottom)'
+    if g:tagbar_position !~# 'vertical'
         call s:GotoFileWindow(taginfo.fileinfo, 1)
         call s:mark_window()
     endif

doc/tagbar.txt

@@ -446,24 +446,26 @@ configuration files.
 
                                                            *g:tagbar_position*
 g:tagbar_position~
-Default: 'right'
+Default: 'botright vertical'
 
-By default the Tagbar window will be opened on the right-hand side of vim. Set
-this option to one of 'left', 'right', 'bottom', or 'top' to open in the
-corresponding position instead. This can be useful when activating Tagbar at
-the same time as another plugin which creates a new window. It allows for more
-granular control of the Tagbar position in relation to the current active
-window.
+By default the Tagbar window will be opened on the right-hand side of vim in a
+vertical split. Set this option to one of the standart vim split options such
+as 'topleft', 'botright', 'leftabove', or 'rightbelow' to open in the
+corresponding position instead. If desiring a vertically split window, then
+include a ' vertical' in the field value as well. This can be useful when
+activating Tagbar at the same time as another plugin which creates a new
+window. It allows for more granular control of the Tagbar position in
+relation to the current active window.
 
-If set to 'top' of 'bottom', |g:tagbar_height| will be used to determine the
-window height for the tagbar window.
+If using a vertical split, |g:tagbar_width| will be used to determine the
+window width for the tagbar window. Else |g:tagbar_height| will be used to
+determine the window height for the tagbar window.
 
-if set to 'left' or 'right', |g:tagbar_width| will be used to determine the
-window width for the tagbar window.
+See |split| for more details on window positioning.
 
 Example:
 >
-        let g:tagbar_position = 'left'
+        let g:tagbar_position = 'leftabove'
 <
                                                                *g:tagbar_left*
 g:tagbar_left~
@@ -505,20 +507,20 @@ Example:
 g:tagbar_height~
 Default: 0
 
-If |g:tagbar_position| is set to 'bottom' or 'top', then this value is used to
-determine the height of the Tagbar window.
-See |g:tagbar_left| for configuring the position of the window.
+If |g:tagbar_position| does not include a 'vertical' option, then this
+value is used to determine the height of the Tagbar window.
 
 Example:
 >
         let g:tagbar_height = 30
 <
+
                                                               *g:tagbar_width*
 g:tagbar_width~
 Default: 40
 
-If |g:tagbar_position| is set to 'left' or 'right', then this value is used to
-determine the width of the Tagbar window in characters.
+If |g:tagbar_position| does include a 'vertical' options, then this value is
+used to determine the width of the Tagbar window in characters.
 
 Example:
 >

plugin/tagbar.vim

@@ -50,27 +50,37 @@ endfunction
 
 function! s:setup_options() abort
     if exists('g:tagbar_position')
-        if g:tagbar_position !~# '\v(top|bottom)'
-            let previewwin_pos = 'topleft'
-        else
+        " Map older deprecated values to correct values
+        if g:tagbar_position ==# 'top'
+            let g:tagbar_position = 'leftabove'
+        elseif g:tagbar_position ==# 'bottom'
+            let g:tagbar_position = 'rightbelow'
+        elseif g:tagbar_position ==# 'left'
+            let g:tagbar_position = 'topleft vertical'
+        elseif g:tagbar_position ==# 'right'
+            let g:tagbar_position = 'botright vertical'
+        endif
+        if g:tagbar_position !~# 'vertical'
             let previewwin_pos = 'rightbelow vertical'
+        else
+            let previewwin_pos = 'topleft'
         endif
         let default_pos = g:tagbar_position
     else
         if exists('g:tagbar_vertical') && g:tagbar_vertical > 0
             let previewwin_pos = 'rightbelow vertical'
             if exists('g:tagbar_left') && g:tagbar_left
-                let default_pos = 'top'
+                let default_pos = 'leftabove'
             else
-                let default_pos = 'bottom'
+                let default_pos = 'rightbelow'
             endif
             let g:tagbar_height = g:tagbar_vertical
         elseif exists('g:tagbar_left') && g:tagbar_left
             let previewwin_pos = 'topleft'
-            let default_pos = 'left'
+            let default_pos = 'topleft vertical'
         else
             let previewwin_pos = 'topleft'
-            let default_pos = 'right'
+            let default_pos = 'botright vertical'
         endif
     endif
     let options = [
@@ -86,6 +96,7 @@ function! s:setup_options() abort
         \ ['height', 10],
         \ ['indent', 2],
         \ ['left', 0],
+        \ ['position', default_pos],
         \ ['previewwin_pos', previewwin_pos],
         \ ['show_balloon', 1],
         \ ['show_visibility', 1],
@@ -94,7 +105,6 @@ function! s:setup_options() abort
         \ ['sort', 1],
         \ ['systemenc', &encoding],
         \ ['vertical', 0],
-        \ ['position', default_pos],
         \ ['width', 40],
         \ ['zoomwidth', 1],
         \ ['silent', 0],