1 tabwins.txt Create tabs of symmetric or asymmetric windows, empty or populated 2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4 || || 5 || _ _ _ || 6 || | | | | (_) || 7 || | |_ __ _| |__ __ ___ _ __ ___ || 8 || | __/ _` | '_ \ \ \ /\ / / | '_ \/ __| || 9 || | || (_| | |_) | \ V V /| | | | \__ \ || 10 || \__\__,_|_.__/ \_/\_/ |_|_| |_|___/ || 11 || || 12 || || 13 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 14 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 15 16 v3.1.0 17 18 19 ==================================================================== 20 CONTENTS TabwinsContents 21 ==================================================================== 22 23 1. Introduction ......... TabwinsIntroduction 24 2. Usage ................ TabwinsUsage 25 3. Vertical & Horizontal TabwinsVandH 26 4. Tabwins Menu ......... TabwinsMenu 27 5. Configuration ........ TabwinsConfiguration 28 6. Adding New Builders .. TabwinsAddingNewBuilders 29 7. License .............. TabwinsLicense 30 8. Bugs ................. TabwinsBugs 31 9. Distributions ........ TabwinsDistributions 32 10. Release History .......TabwinsReleases 33 11. Credits .............. TabwinsCredits 34 35 36 ==================================================================== 37 Section 1: Introduction TabwinsIntroduction 38 ==================================================================== 39 40 Easy access to the power of the Vim GUI. 41 42 See the screen shots at 43 https://github.com/cesheridan/graphics/tree/master/tabwins 44 45 46 1 command for immediate access to customized window structures 47 and content ~during~ Vim sessions. 48 49 The Developer 50 - Avoids hit-or-miss, time-consuming, manual, repetitious 51 runs of :split/:vsplit, and thought-sinks about how 52 to produce the intended window structure 53 54 - Avoids losing current configurations due to mid-session 55 reloads of backed-up Vim sessions that have preferred 56 window structures 57 58 - Avoids loss of focus from these discontinuities 59 60 61 FORMS -- 62 63 :{Tabwins cmd} {window_dimensions}; {fill_spec,...}; {tab_option, ...} 64 :{symmetric cmd} {fill_spec,...}; {tab_option, ...} 65 66 Where 67 :{Tabwins cmd} is any of :Tabwins, :TabwinsVertical, :TabwinsHorizontal 68 Aliases :Tw, :V, & :H 69 About aliases, see tabwins.txt section "Configuration"/TabwinsConfiguration. 70 71 :{symmetric cmd} is any of the form :{V|H}IxJ or :{V|H}I 72 73 'fill_spec' 74 is a file, dir, shell/vim var, or string evaluable 75 by :execute -- see EXAMPLES 76 77 'tab_option' 78 has Vim key:value pair syntax -- see EXAMPLES 79 80 Semicolons separate arg groups, commas separate inside groups. 81 82 {window_dimensions} is the only mandatory arg, for :{Tabwins cmd} 83 84 SECTION "Usage/"TabwinsUsage IN tabwins.txt HAS MORE DETAIL. 85 86 87 EXAMPLES -- 88 89 >> ---------------------------------------------------------------- 90 >> Empty Windows 91 >> ---------------------------------------------------------------- 92 93 :Tabwins 1211 94 :T 1211 95 " For a new tab of 4 columns of 1, 2, 1, & 1 windows successively 96 " left to right. 97 98 :TabwinsHorizontal 4221 99 :H 4221 100 " For a new tab of 4 rows, with 4,2,2, & 1 windows successively 101 " top to bottom. 102 103 >> ---------------------------------------------------------------- 104 >> Populated Windows 105 >> ---------------------------------------------------------------- 106 107 :Tabwins 1211; $HOME, '~/.bashrc', '~/.vimrc', '/', '/usr/bin' 108 :T { as above } 109 " 'fill_content' specs of files are automatically opened via :edit, 110 " while specs of dirs are opened via :Explore 111 " (Specify the '' empty string for windows intended to be empty.) 112 113 :Tabwins 11111; $HOME, '~/.bashrc', '~/.vimrc', '/', '/usr/bin' 114 :T { as above } 115 " Same buffer content, in different window structure, of 5 cols, 116 " one window in each. 117 118 :TabwinsHorizontal 11111; $HOME, '~/.bashrc', '~/.vimrc', '/', '/usr/bin' 119 :H { as above } 120 " Flip axis priority of above to the horizontal 121 122 :Tabwins 312; '~/.bashrc', '~/.vimrc', '~/.git', $HOME, '/', '/usr/bin' 123 :T { as above } 124 125 >> ---------------------------------------------------------------- 126 >> Symmetric Window Structures 127 >> ---------------------------------------------------------------- 128 In a symmetric window, all secondary axis dimensions are the same. 129 130 :V5x8 131 :H5x8 132 :V6 133 :H6 134 :V8x14 135 :H8x14 136 " Empty windows 137 138 :V5x1 139 140 :V5x1 $HOME, '~/.bashrc', '~/.vimrc', '/', '/usr/bin' 141 " Structure & content same as :Tabwins 11111 above 142 143 :V5 $HOME, '~/.bashrc', '~/.vimrc', '/', '/usr/bin' 144 " Same result again: since the secondary axis has only 1 145 " window for its dimensions, V5 is available as an even 146 " shorter alias. 147 148 >> ---------------------------------------------------------------- 149 >> Dimensions >9 150 >> ---------------------------------------------------------------- 151 152 :Tabwins [ 5, 8, 13, 21 ] 153 :T [ 5, 8, 13, 21 ] 154 " For a 4-column tab with 5, 8, 13, 21 windows successively left to right. 155 156 :Tabwins [ 14, 14 ] 157 :T [ 14, 14 ] 158 " Or, :V2x14 159 160 :Tabwins [ 40, 30, 40, 30 ] 161 :T [ 40, 30, 40, 30 ] 162 " For large monitors ... 163 164 165 >> ---------------------------------------------------------------- 166 >> fill_specs with Multiple Commands 167 >> ---------------------------------------------------------------- 168 169 :Tabwins 1112; $HOME, '~/.bashrc', '~/.vimrc', '/', 'Explore /usr/bin | resize 20' 170 :T { as above } 171 " Does a :resize of the last window, via Vim '|' command concat. If a file 172 " or dir is followed with concated commands, the caller needs to explicitly 173 " add the command that opens the file or dir, i.e. 'Explore' in this example. 174 175 >> ---------------------------------------------------------------- 176 >> Tab Options 177 >> ---------------------------------------------------------------- 178 179 :Tabwins 1211; $HOME, '~/.bashrc', '~/.vimrc', '/', '/usr/bin'; 'ending_window_number' : 2 180 :Tabwins 1211; $HOME, '~/.bashrc', '~/.vimrc', '/', '/usr/bin'; 'netrw_liststyle' : 3 181 :T { as above } 182 183 :Tabwins 1211; $HOME, '~/.bashrc', '~/.vimrc', '/', '/usr/bin'; 'netrw_liststyle' : 3, 'ending_window_number' : 2 184 :T { as above } 185 " Multiple tab_options in same command. 186 187 188 TABWINS MENU -- 189 190 Default settings load Vim menu Tabwins, for access to selected 191 ~~~~~~~~~~~~~~~~ 192 tab-builder commands. Those and additional tab builders are 193 available via Vim commands defined in tabwins.vim. The menu has 194 only a small portion of the tab builders defined in tabwins.vim. 195 196 197 HELP IN VIM -- 198 199 :TabwinsFindTabwins loads the tabwins .vim & .txt files 200 into a V2 window, if your Vim &runtimepath can see them. 201 202 :TabwinsFindTabwins is in the 'Tabwins' menu. 203 204 205 HELP IN HTML -- 206 207 The top-level of the github repository includes an html 208 version of this Vim .txt file, viewable in rendered form via 209 http://htmlpreview.github.io/?https://github.com/cesheridan/tabwins/blob/master/tabwins.txt.html 210 211 212 DEPLOYMENT -- 213 214 tabwins.vim tabwins/ dir is structured for deployment in a 215 pathogen-managed bundle directory, e.g. ~/.vim/bundle/ 216 217 If pathogen is not installed, copy the the files in the tabwins 218 subdirs to the same subdirs in ~/.vim. 219 220 Enable :h tabwins in a pathogen environment with 221 :Helptags 222 and in a non-pathogen environment with 223 :helptags 224 225 226 ==================================================================== 227 Section 2: Usage TabwinsUsage 228 ==================================================================== 229 230 => See FORMS in TabwinsIntroduction 231 => See EXAMPLES in TabwinsIntroduction 232 233 234 THREE TABWINS COMMANDS -- 235 236 These commands all take the same arguments. 237 238 :Tabwins 239 Same as :TabwinsVertical 240 Default alias :T 241 242 :TabwinsVertical 243 Gives priority to the vertical axis. 244 Default alias :V 245 246 :TabwinsHorizontal 247 Gives priority to the horizontal axis. 248 Default alias :H 249 250 See "Vertical & Horizontal"/TabwinsVandH about primary/secondary 251 axes and vertical/horizontal priority. 252 253 See "Configuration"/TabwinsConfiguration re aliases. 254 255 These commands accept arbitrary dimension specification, 256 unconstrained by configuration vars, other than 257 windows-per-tabsize limits of the Vim instance. 258 259 260 SYMMETRIC WINDOW STRUCTURES -- 261 262 In these, the lengths of the secondary axis dimensions 263 are all equal. 264 265 Symmetric commands are available to reduce keystrokes. 266 267 'H' indicates horizontal priority, 'V' vertical priority. 268 269 Loading tabwins.vim creates :{V|H}IxJ commands where the 270 set of IxJ is the permutations of: 271 g:tabwins_max_v_size 272 g:tabwins_max_h_size 273 274 The same global vars determine the set of :{V|H}J commands 275 also produced on tabwins.vim load, where N is from 1 to the 276 value of the relevant g:tabwins_max_{h|v}_size var above. 277 278 279 DIMENSIONS GREATER THAN 9 -- 280 281 Dimensions >9 are unparsable when {window_dimensions} is 282 an integer. To enable dimensions >9, use list syntax as 283 shown in EXAMPLES of "Introduction"/TabwinsIntroduction 284 285 List syntax applies to any tab that one or more dimension >9. 286 All the dimensions of such a tab are specified in one list. 287 288 289 290 FILL SPECS WITH MULTIPLE COMMANDS -- 291 292 Multiple Vim commands can be specified in a fill_spec by 293 prepending commands with the Vim '|' concatenation operator. 294 See EXAMPLES in "Introduction"/TabwinsIntroduction. 295 296 297 TAB OPTIONS -- 298 299 Available tab_options are below, with global default vars 300 on the right. 301 302 See tabwins.txt section "Configuration"/TabwinsConfiguration 303 re the globals. 304 305 These options apply to the entire tab and can be combined when 306 separated by commas. 307 308 'explore_cmd_name' : g:tabwins_explore_cmd_name_default, 309 'netrw_liststyle' : g:tabwins_netrw_liststyle_default, 310 'line_number_at_window_top' : g:tabwins_netrw_line_number_default, 311 312 => Use a fill_spec for window-specific override of the 313 above options 314 315 'first_window_number' : g:tabwins_first_window_number_default, 316 => window population starts with this number, so you wouldn't 317 have to have to have a fill_spec for lower-numbered windows. 318 319 'ending_window_number' : g:tabwins_ending_window_number_default, 320 => the active window number after tabwins.vim builds a tab 321 322 323 See EXAMPLES in "Introduction"/TabwinsIntroduction. 324 325 326 327 ==================================================================== 328 Section 3: Vertical & Horizontal TabwinsVandH 329 ==================================================================== 330 331 Windows are built one axis at a time. The first axis built 332 is the primary axis, and the other axis is the secondary axis. 333 ~~~~~~~~~~~~ ~~~~~~~~~~~~~~ 334 If the tab starts by building the vertical axis, then the 335 vertical axis is the primary axis, and the horizontal axis 336 is the secondary axis. And vice-versa. 337 338 What's the difference between Horizontal & Vertical Tabs ? 339 340 Structurally, V2x3 is the same as H3x2. The only difference 341 is how Vim numbers the tabs, based on the axis that is the 342 primary axis. 343 344 IF the primary axis is vertical, then numbering starts in 345 col 1 and goes down the windows in col 1, then to the top 346 of col 2, then down col 2, and so on. 347 348 IF the primary axis is horizontal, numbering starts in 349 row 1 and goes left to right, then to row 2, left to right, 350 and so on. 351 352 Most of the asymmetric tab builders defined in the plugin 353 use a vertical primary axis. Developers can define any 354 mix of primary axis in their own tab builders -- See 355 "Adding New Builders"/TabwinsAddingNewBuilders 356 357 358 ==================================================================== 359 Section 4: 'Tabwins' Menu TabwinsMenu 360 ==================================================================== 361 362 In the 'Tabwins' menu built on plugin load, the extent that 363 populated tabs fill their buffers is dependent on the shell 364 vars available to the Vim session, and files/dirs present in 365 the local environment. 366 367 The menu items reference some of these shell vars. 368 369 The developer is encouraged to customize this menu for local usage. 370 371 Update or replace 372 function Tabwins_menu_build() 373 in tabwins.vim to do so. 374 375 376 ==================================================================== 377 Section 5: Configuration TabwinsConfiguration 378 ==================================================================== 379 380 The below globals are defined in tabwins.vim and are overridable. 381 382 383 To change Vertical/Horizontal max dimensions: 384 let g:tabwins_max_v_size = {N} 385 let g:tabwins_max_h_size = {N} 386 Default: 15 for each 387 388 389 To limit tabwins.vim load to once per Vim session: 390 let g:tabwins_multiple_loads_are_permitted = 'N' 391 Default: 'Y' 392 393 To prevent 'Tabwins' menu addition when tabwins loads: 394 let g:load_tabwins_menu_is_wanted = 'N' 395 Default: 'Y' 396 397 To change the 'Tabwins' menu number: 398 let g:tabwins_menu_number = {menu_number} 399 Default: 9998 400 401 402 To turn off creation of :Tabwins* aliases 403 let g:tabwins_create_aliases_is_wanted = 'N' 404 Default: 'Y' 405 => Creation of an alias command will NOT occur when an existing 406 command has the same name. 407 408 :Tabwins* Alias Defaults: 409 let g:tabwins_alias = 'T' 410 let g:tabwinsvertical_alias = 'V' 411 let g:tabwinshorizontal_alias = 'H' 412 let g:tabwinsfindtabwins_alias = 'TF' 413 414 415 To change the default beginning window number for filling fill_specs 416 let g:tabwins_first_window_number_default = {N} 417 Default: 1 418 Calls to Fill_tab() can override this on a per-tab basis. 419 420 To change the default window number that's active on :Tabwins* completion 421 let g:tabwins_ending_window_number_default = {N} 422 Default: 1 423 Calls to Fill_tab() can override this on a per-tab basis. 424 425 426 To change the default directory Explore command: 427 let g:explore_cmd_name = {explore_command_name} 428 Default: 'Explore' 429 430 To change the default top-line of netrw windows: 431 let g:tabwins_netrw_line_number_default = {N} 432 Default: g:tabwins_netrw_line_number_dirpath, which defaults to 3 433 Calls to Fill_tab() can override this on a per-tab basis. 434 435 To change the default netrw liststyle: 436 let g:tabwins_netrw_liststyle_default = {N} 437 Default: 1 438 Calls to Fill_tab() can override this on a per-tab basis. 439 if netrw var g:netrw_liststyle is not defined, it gets this value. 440 441 442 ==================================================================== 443 Section 6: Adding New Builders TabwinsAddingNewBuilders 444 ==================================================================== 445 446 ADDING SYMMETRIC TAB COMMANDS -- 447 448 Bump either/both values of: 449 g:tabwins_max_v_size 450 g:tabwins_max_h_size 451 above the values assigned in tabwins.vim. 452 453 Loading tabwins.vim will build commands for all the HxV and 454 VxH permutations. 455 456 Of course, the set of symmetric tab builder commands can be 457 reduced by lowering the values of the same globals. 458 459 460 MORE GENERALLY -- 461 462 Adapt the below example to create your own commands that build tabs 463 that have the window structures and content that you want. 464 465 let g:home_parent_dirpath = substitute(finddir($HOME), '\/\w\+$', '', 'g') 466 command! TabwinsHomeDir :Tabwins 232; 467 \ $HOME, 468 \ 'Explore ' . g:home_parent_dirpath . ' | resize 30', 469 \ 470 \ 'edit! ~/.bashrc', 471 \ '~/.gitignore', 472 \ 'enew!', 473 \ 474 \ '~/.vimrc', 475 \ '~/.vim' 476 \; 477 \ 'line_number_at_window_top' : 1 478 479 " windows are filled with the order of elements 480 " in 'fill_specs' You want to spec something for each 481 " of the windows created by :Tabwins 232, 482 " either commands, filepaths, or dirpaths. Spec an empty 483 " string to bypass the fill of a window buffer. 484 " Specs can include shell or vim vars, and if files or dirs 485 " the spec can include a vim command or use the default :edit or 486 " :Explore call in Fill_tab() 487 488 " NOTE-the .vim file implementation defines 'home_parent_dirpath' as 489 " as a vimscript var, i.e. 's:home_parent_dirpath' -- it's changed 490 " here to facilitate interactive experimentation. 491 492 493 See the other demo commands at end of the tabwins.vim. 494 495 See HELP in TabwinsUsage. 496 497 ==================================================================== 498 Section 7: License TabwinsLicense 499 ==================================================================== 500 501 Copyright (c) 2013, Charles E. Sheridan 502 503 This program is free software; you can redistribute it 504 and/or modify it under the terms of the GNU General Public 505 License as published by the Free Software Foundation, 506 version 2 of the License. 507 This program is distributed in the hope that it will be 508 useful, but WITHOUT ANY WARRANTY; without even the implied 509 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 510 PURPOSE. 511 512 See the GNU General Public License version 2 for more details. 513 514 515 ==================================================================== 516 Section 8: Bugs TabwinsBugs 517 ==================================================================== 518 519 Send bug reports and proposed fixes to 520 opensource at att.net 521 522 523 ==================================================================== 524 Section 9: Distributions TabwinsDistributions 525 ==================================================================== 526 527 github repository for this plugin 528 https://github.com/cesheridan/tabwins 529 530 531 vim.org URL of this plugin 532 http://www.vim.org/scripts/script.php?script_id=4767 533 534 535 The distribution at vim.org is taken from the github repository. 536 537 538 ==================================================================== 539 Section 10: RELEASE HISTORY TabwinsReleases 540 ==================================================================== 541 542 Release numbering follows the Semantic Versioning approach as 543 described at http://semver.org/ 544 545 >> v3.1.0 2013-12-08 546 1. For fill_specs that are files, put line #1 at window top. 547 2. tabwins.txt: correct Fill_tab() key 'dir_cmd_name' to 'explore_cmd_name' 548 3. tabwins.txt: correct 'tabwins_dir_reader_name_default' to 'tabwins_explore_cmd_name_default' 549 4. tabwins.txt: various improvements. 550 551 552 >> v3.0.0 2013-12-02 553 0. No behavioral changes to command logic. 554 1. Tab option 'line_number_at_window_top' 555 renamed => 'line_number_at_netrw_window_top' 556 557 2. Add configurable build of command aliases :T, :V, :H, and :TF 558 for :Tabwins* commands. An alias is NOT BUILT IF an existing 559 command has the same name. See ""Configuration"/TabwinsConfiguration 560 in tabwins.txt. 561 562 3. All defaults to Fill_tab() are now user-configurable global vars. 563 564 4. Most functions converted to vimscript ':s' scope -- the 565 Explore_*() functions and Fill_tab() are the exceptions. 566 567 5. Demo tabs are now :Tabwins* commands rather than functions. 568 6. Remove the :Ot* abbreviated commands for the demo tabs. 569 7. tabwins.txt: Add example builder command, & various improvements. 570 8. Comments in code cleaned up. 571 572 573 >> v2.2.0 2013-11-24 574 1. CLI commands support tab_option args. 575 ALL tabwins.vim capability is now available directly to 576 the Vim command line. A developer should not have to call 577 functions in tabwins.vim to create a tabwins command. 578 579 2. Configurable reloadability of tabwins.vim. 580 3. Add :TabwinsFindTabwins and include it in the 'Tabwins' menu. 581 4. Function Fill_tab() arg 'fill_content' renamed => 'fill_specs' 582 5. Rework documentation. 583 584 585 >> v2.1.0 2013-11-17 586 1. fill_specs supported as tabwins.vim CLI commands arg 587 2. Function Fill_tab() arg 'window_fill_specs' renamed => 'fill_content' 588 589 590 >> v2.0.0 2013-11-13 591 1. As previewed in v1.8.0, the predefined asymmetric :{VH}{I…} 592 commands are removed, replaced with calls to :TabwinsVertical, 593 :TabwinsHorizontal, and :Tabwins. All the Create_tab_{vh}*() 594 commands are removed, as the :Tabwins* commands can create the 595 same tabs, with arbitrary dimensions. 596 2. Addition of :Tabwins, establishing a plugin default to :TabwinsVertical. 597 3. Lots of updates to comments, reflecting 1) & 2). 598 599 600 >> v1.8.0 2013-11-13 601 1. New commands :TabwinsVertical and :TabwinsHorizontal to create 602 arbitrarily-dimensioned symmetric AND asymmetric tabs. 603 In v.1.7.0, each asymmetric command required creation of 604 a dedicated function, which is no longer the case. 605 606 Most of the predefined asymmetric commands in v.1.7.0 will be 607 removed in a later release. 608 609 610 >> v1.7.0 2013-11-11 611 1. First vim.org release. 612 613 ==================================================================== 614 Section 11: Credits TabwinsCredits 615 ==================================================================== 616 617 Author: Charles E. Sheridan 618 Contact: opensource at att.net 619