1 *bashsupport.txt* Bash Support Nov 11 2005
3 bash Support *bash-support* *bashsupport*
5 for Vim version 6.0 and above
6 Fritz Mehner <mehner@fh-swf.de>
8 Write and run bash scripts using menus and hot keys (key mappings).
10 1. Usage with GUI |bashsupport-usage-gvim|
11 1.1 Menu 'Comments' |bashsupport-comments|
12 1.1.1 Append aligned comments |bashsupport-aligned-comm|
13 1.1.2 Code to comment |bashsupport-code-to-comm|
14 1.1.3 Comment to code |bashsupport-comm-to-code|
15 1.1.4 Frame comments, file header, ... |bashsupport-comm-templates|
16 1.1.5 Comment/uncomment with echo |bashsupport-comm-echo|
17 1.1.6 KEYWORD + comment |bashsupport-comm-keywords|
18 1.2 Menu 'Statements' |bashsupport-statements|
19 1.2.1 Normal mode, insert mode |bashsupport-stat-norm-ins|
20 1.2.2 Visual mode |bashsupport-stat-visual|
21 1.2.3 Code Snippets |bashsupport-stat-snippets|
22 1.3 Menu 'set' |bashsupport-set|
23 1.4 Menu 'shopt' |bashsupport-shopt|
24 1.5 Menu 'Regex' |bashsupport-regex|
25 1.6 Menu 'Run' |bashsupport-run|
26 1.6.1 Save and run |bashsupport-run-script|
27 1.6.2 Save and check syntax |bashsupport-syntax-check|
28 1.6.3 Command line arguments |bashsupport-cmdline-args|
29 1.6.4 Start debugger |bashsupport-debugger|
30 1.6.5 Hardcopy |bashsupport-hardcopy|
31 1.6.6 Xterm size |bashsupport-xterm|
32 1.6.7 Output redirection |bashsupport-output|
33 2. Usage without GUI |bashsupport-usage-vim|
34 3. Hot keys |bashsupport-hotkeys|
35 4. Customization and configuration |bashsupport-customization|
36 4.1 Files |bashsupport-custom-files|
37 4.2 Global variables |bashsupport-custom-variables|
38 4.3 The root menu |bashsupport-custom-root|
39 5. Template files and tags |bashsupport-tempfiles|
40 5.1 Template files |bashsupport-tempfiles|
41 5.2 Tags |bashsupport-tags|
42 6. Bash dictionary |bashsupport-dictionary|
43 7. Release Notes |bashsupport-release-notes|
45 How to add this help file to Vim's help |add-local-help|
48 ==============================================================================
49 1. USAGE with GUI (gVim) *bashsupport-usage-gvim*
50 ==============================================================================
52 If the menus are not visible call them with the entry "Load Bash Support"
53 in the standard Tools-menu.
55 ------------------------------------------------------------------------------
56 1.1 MENU 'Comments' *bashsupport-comments*
57 ------------------------------------------------------------------------------
59 1.1.1 APPEND ALIGNED COMMENTS TO CONSECUTIVE LINES *bashsupport-aligned-comm*
60 --------------------------------------------------
62 In NORMAL MODE the menu entry
64 will append a comment to the current line.
66 In VISUAL MODE this entry will append aligned comments to all marked lines.
74 and choosing 'Line End Comm.' will yield
81 The cursor position above is marked by '|' . Empty lines will be ignored.
83 The default starting column is 49 ( = (8*6 or 4*12 or 2*24) + 1 ). This can
84 be changed by setting a global variable in the file .vimrc , e.g. :
86 let g:BASH_LineEndCommColDefault = 45
88 The starting column can also be set by the menu entry 'Comments->Set End Comm.
89 Col.' . Just position the cursor in an arbitrary column (column number is
90 shown in the Vim status line) and choose this menu entry. This setting is
94 1.1.2 CODE TO COMMENT *bashsupport-code-to-comm*
97 A marked block will be changed into
104 The menu entry works also for a single line. A single line needs not to be
105 marked (normal mode).
108 1.1.3 COMMENT TO CODE *bashsupport-comm-to-code*
109 ---------------------
125 The menu entry works also for a single line. A single line needs not to be
126 marked (normal mode).
129 1.1.4 FRAME COMMENTS, FILE HEADER, ... *bashsupport-comm-templates*
130 --------------------------------------
132 Frame comments, function descriptions and file header comments are read as
133 templates from the appropriate files (see |bashsupport-tempfiles|).
135 1.1.5 COMMENT/UNCOMMENT WITH echo *bashsupport-comm-echo*
136 ---------------------------------
138 The echo-entry in the Comments-menu can be used to put one or more statements
139 in a sort of comment. This is usually done for testing:
141 echo "rm -f $allfiles"
143 This can only be done in normal mode: The complete line (from the first
144 non-blank to the end) is framed with echo "..." ; the cursor will be then
145 moved to the next line. Now this line can be framed and so forth.
147 The remove-echo-entry removes an echo. The keyword echo, the following double
148 quotation mark and the last double quotation mark in the current line will be
149 removed; the cursor will then be moved to the next line.
151 Longer sections of a script are better commented out with set options
154 1.1.6 KEYWORD+comment *bashsupport-comm-keywords*
155 ---------------------
157 Preliminary line end comments to document (and find again) places where work
158 will be resumed shortly, like
160 # :TODO:12.05.2004:Mn: <your comment>
162 Usually not meant for the final documentation.
164 ------------------------------------------------------------------------------
165 1.2 MENU 'Statements' *bashsupport-statements*
166 ------------------------------------------------------------------------------
168 1.2.1 NORMAL MODE, INSERT MODE. *bashsupport-stat-norm-ins*
169 --------------------------------
171 An empty statement will be inserted and properly indented. The entry 'if'
172 will insert an if-statement:
178 Inner statements will be indented.
180 1.2.1 VISUAL MODE *bashsupport-stat-visual*
183 The highlighted area (...) will be surrounded by a statement, parentheses,
184 quotes or an echo with quotes:
189 select in do ... done
202 ------------------------------------------------------------------------------
203 1.2.3 CODE SNIPPETS *bashsupport-stat-snippets*
204 ------------------------------------------------------------------------------
206 Code snippets are pieces of code which are kept in separate files in a special
207 directory. File names are used to identify the snippets. The default snippet
208 directory is $HOME/.vim/codesnippets-bash. Snippets are managed with the 3
211 bash -> Statements -> read code snippet
212 bash -> Statements -> write code snippet
213 bash -> Statements -> edit code snippet
215 from the Statements submenu.
217 Creating a new snippet:
218 -----------------------
219 When nothing is marked, "write code snippet" will write the whole buffer
220 to a snippet file, otherwise the marked area will be written to a file.
224 Select the appropriate file from the snippet directory ("read code snippet").
225 The inserted lines will be indented.
227 Indentation / no indentation
228 ----------------------------
229 Code snippets are normally indented after insertion. To suppress indentation
230 add the file extension "ni" or "noindent" to the snippet file name, e.g.
232 parameter_handling.sh.noindent
235 ------------------------------------------------------------------------------
236 1.3 MENU 'set' *bashsupport-set*
237 ------------------------------------------------------------------------------
239 Calling a set-command (submenu "set") in NORMAL or INSERT MODE will set this
244 Calling a set-command (submenu "set") for a marked block (VISUAL MODE)
249 will set this option above this block and unset it below:
251 set -o posix # SetOptionNumber_1
254 set +o posix # SetOptionNumber_1
256 The option numbers SetOptionNumber_xxx are automatically incremented. They can
257 be searched for with the vim star command (*).
260 ------------------------------------------------------------------------------
261 1.4 MENU 'shopt' *bashsupport-shopt*
262 ------------------------------------------------------------------------------
264 Calling a shopt-command (submenu "shopt") in NORMAL or INSERT MODE will set
267 shopt -s shift_verbose
269 Calling a shopt-command (submenu "shopt") for a marked block (VISUAL MODE)
274 will set this option above this block and unset it below:
276 shopt -s shift_verbose # ShoptOptionNumber_1
279 shopt -u shift_verbose # ShoptOptionNumber_1
281 The option numbers ShoptOptionNumber_xxx are automatically incremented. They
282 can be searched for with the vim star command (*).
284 ------------------------------------------------------------------------------
285 1.5 MENU 'Regex' *bashsupport-regex*
286 ------------------------------------------------------------------------------
288 These menu can be used to compose regular expressions with a few keystrokes.
289 In normal mode the entries insert the shown constructs after the cursor. The
290 first group ( "*(|)" , ... ) and the entry '[ ]' can enclose a marked text.
297 ------------------------------------------------------------------------------
298 1.6 MENU 'Run' *bashsupport-run*
299 ------------------------------------------------------------------------------
301 1.6.1 Save and run *bashsupport-run-script*
304 Save the current buffer to his file and run this file. The command line, the
305 applied parameters and the shell return code are shown in the bottom line.
307 * In NORMAL MODE the whole buffer will be executed.
308 * In VISUAL MODE only the marked lines will be executed.
311 1.6.2 Save and check syntax *bashsupport-syntax-check*
312 ---------------------------
314 Save the current buffer to his file and run this file with the -n flag
315 (bash: Read commands but do not execute them).
316 Errors are listed in an error window; now the quickfix commands can be used.
318 The syntax check can be influenced by shopt options. Options which shall
319 always take effect can be declared in .vimrc , e.g.
321 let g:BASH_SyntaxCheckOptionsGlob = "-O extglob"
323 These options can be augmented or canceled using the menu entry 'syntax check
324 options' typing for instance
326 +O extglob -O nocaseglob
328 after the prompt. The options entered this way are buffer related. The global
329 options set in .vimrc and the buffer related options are checked. Only the
330 shopts options for Bash 3.0 (GNU Bash-3.0, manual: 2004 June 26) are
333 cdable_vars cdspell checkhash checkwinsize
334 cmdhist dotglob execfail expand_aliases
335 extdebug extglob extquote failglob
336 force_fignore gnu_errfmt histappend histreedit
337 histverify hostcomplete huponexit interactive_comments
338 lithist login_shell mailwarn no_empty_cmd_completion
339 nocaseglob nullglob progcomp promptvars
340 restricted_shell shift_verbose sourcepath xpg_echo
343 1.6.3 Command line arguments *bashsupport-cmdline-args*
344 ----------------------------
346 The entry 'com. line arg.' calls an input dialog which asks for command line
347 arguments. These arguments are forwarded to the script which is run by the
348 'run' entry. The arguments are kept until you change them.
350 The arguments belong to the current buffer (that is, each buffer can have its
352 If the buffer gets a new name with "save as" the arguments will now belong to
353 the buffer with the new name.
356 1.6.4 START DEBUGGER *bashsupport-debugger*
359 The menu entry 'start debugger' starts the bash debugger 'bashdb'. Your version
360 of the bash must be prepared for debugging and the debugger must be installed
361 (see http://bashdb.sourceforge.net/).
362 If you are working under a running GUI the debugger will be started in an
363 independent xterm. In the non-GUI version starting the debugger is done by
364 :!bash --debugger <command line arguments>
365 In both cases the command line arguments come from the argument setting
366 |bashsupport-cmdline-args| if any.
369 1.6.5 Hardcopy *bashsupport-hardcopy*
372 Normal mode, insert mode: a Postscript file is made from the whole file.
373 Visual mode : a Postscript file is made from the marked area.
376 1.6.6 Xterm size *bashsupport-xterm*
379 The size of the xterm (see below) can be changes for the current session. The
380 size has to be specified as COLUMNS LINES (e.g. 96 32 ).
382 1.6.7 Output redirection *bashsupport-output*
383 ------------------------
385 The last menu entry 'output: ... ' has 3 states:
386 'output: VIM->buffer->xterm'
387 'output: BUFFER->xterm->vim'
388 'output: XTERM->vim->buffer'
389 The first state (upper-case) is the current one.
393 The script is run from the command line like ":!./% arguments".
394 * This is suitable for scripts with dialog elements and few lines of output.
398 The shell output will be displayed in a window with name "Bash-Output". This
399 buffer and its content will disappear when the window is closed. It is not
400 writable and it has no file. The content could be saved with "save as".
401 If the output fits completely into this window the cursor will stay in the
402 script window otherwise the cursor will be set into the output window (you may
404 When the script is run again and the output buffer is still open it will be
407 The buffer will not be opened if the script does not produce any output.
408 This is for convenience; you do not have to close an empty buffer.
410 * This is suitable for scripts without dialog elements and many lines of output
411 * (e.g. from options like xtrace). Use Vim as pager (scroll, jump, search with
412 * regular expressions, .. )
416 The script will be run in a xterm-window. A wrapper script will ask you to
417 close this window with Return or <C-D> (bash).
418 The wrapper shows the complete command line and the return code of the script.
420 * This is suitable for scripts with dialog elements and many lines of output.
421 * The xterm is scrollable and independent from the editor window.
423 Appearance of the xterm
424 -----------------------
425 The appearance of the xterm can be controlled by the global variable
426 g:BASH_XtermDefaults. The assignment
428 let g:BASH_XtermDefaults = "-fa courier -fs 10 -geometry 96x32"
430 placed in .vimrc would override the defaults. The defaults are
432 "-fa courier -fs 12 -geometry 80x24"
434 FreeType font 'courier', FreeType font size 12 point, window width 80
435 characters, window height 24 lines.
437 The default output method is VIM. The preferred output method can be selected
438 in .vimrc by the global variable g:BASH_OutputGvim, e.g.
440 let g:BASH_OutputGvim = "xterm"
442 The methods are "vim", "buffer" and "xterm".
444 ==============================================================================
445 2. USAGE without GUI (Vim) *bashsupport-usage-vim*
446 ==============================================================================
448 The frequently used constructs and commands can also be inserted and used with
451 -- Load / Unload bash Support -------------------------
453 \lbs Load Bash Support (normal)
454 \ubs Unload Bash Support (normal)
456 -- Comments -------------------------------------------
458 \cl Line End Comment (normal)
459 \cf Frame Comment (normal)
460 \cu Function Description (normal)
461 \ch File Header (normal)
462 \ckb Keyword comment BUG (normal)
463 \ckt Keyword comment TODO (normal)
464 \ckr Keyword comment TRICKY (normal)
465 \ckw Keyword comment WARNING (normal)
466 \ckn Keyword comment New_Keyword (normal)
467 \cc code to comment (normal, visual)
468 \co comment to code (normal, visual)
470 \ct Date & Time (normal)
471 \ce echo "..." (normal)
472 \cr remove echo "..." (normal)
473 \cv vim modeline (normal)
475 -- Statements ------------------------------------------
477 \ac case in ... esac (normal)
478 \al elif then (normal)
479 \af for in do done (normal, visual)
480 \ai if then fi (normal, visual)
481 \ae if then else fi (normal, visual)
482 \as select in do done (normal, visual)
483 \at until do done (normal, visual)
484 \aw while do done (normal, visual)
485 \ao echo -e "..." (normal, visual)
487 -- Run ------------------------------------------------
489 \rr update file, run script (normal)
490 \rc update file, check syntax (normal)
491 \ra set command line arguments (normal)
492 \rd start debugger (normal)
493 \re make script executable (normal)
494 \rh hardcopy buffer to FILENAME.ps (normal)
495 \rs settings and hot keys (normal)
496 \rt set xterm size (normal)
497 \ro change output destination (normal)
499 -- bash help ------------------------------------------
501 \h display help for the builtin (normal)
505 File bash-hot-keys.pdf contains a reference card for these key mappings.
506 Multiline inserts and code snippets will be indented after insertion.
508 The hot keys are defined in the file type plugin sh.vim (part of this
509 bash-support plugin package).
512 ==============================================================================
513 3. HOT KEYS *bashsupport-hotkeys*
514 ==============================================================================
516 The following hot keys are defined in NORMAL, VISUAL and INSERT MODE:
518 Shift-F1 display help for a the built command under the cursor or ask
521 Alt-F9 run syntax check
522 Shift-F9 command line arguments (for the current buffer)
523 F9 start debugger (bashdb)
526 ==============================================================================
527 4.0 CUSTOMIZATION *bashsupport-customization*
528 ==============================================================================
530 ------------------------------------------------------------------------------
531 4.1 FILES *bashsupport-custom-files*
532 ------------------------------------------------------------------------------
534 README.bashsupport This file.
536 codesnippets-bash/* Some code snippets as a starting point.
538 doc/bashsupport.txt The help file for the local online help.
540 ftplugin/sh.vim A file type plugin. Define hot keys, creates a local
541 dictionary for each bash file.
543 plugin/bash-support.vim The bash plugin for Vim/gVim.
544 plugin/wrapper.sh The wrapper script for the use with a xterm.
546 plugin/templates/bash-file-header -+- bash template files
547 plugin/templates/bash-frame | (see bashsupport.txt)
548 plugin/templates/bash-function-description -+
550 wordlists/bash.list A file with words used as dictionary for automatic word
551 completion. This file is referenced in the file
552 customization.vimrc .
554 ----------------------- -------------------------------------------------------------
555 ----------------------- The following files and extensions are for convenience only.
556 bash-support.vim will work without them.
557 -------------------------------------------------------------
559 rc/customization.vimrc Additional settings I use in .vimrc: incremental search,
560 tabstop, hot keys, font, use of dictionaries, ...
561 The file is commented. Append it to your .vimrc if you like.
563 rc/customization.gvimrc Additional settings I use in .gvimrc:
564 hot keys, mouse settings, ...
565 The file is commented. Append it to your .gvimrc if you like.
567 doc/bash-hot-keys.pdf Reference card for the key mappings.
568 The mappings can be used with the non-GUI Vim,
569 because the menus are not available.
571 ------------------------------------------------------------------------------
572 4.2 GLOBAL VARIABLES *bashsupport-custom-variables*
573 ------------------------------------------------------------------------------
575 Several global variables are checked by the script to customize it:
577 ---------------------------------------------------------------------------------------
578 global variable default value tag
579 (see |bashsupport-tags|)
580 ---------------------------------------------------------------------------------------
581 g:BASH_AuthorName "" |AUTHOR|
582 g:BASH_AuthorRef "" |AUTHORREF|
583 g:BASH_Email "" |EMAIL|
584 g:BASH_Company "" |COMPANY|
585 g:BASH_Project "" |PROJECT|
586 g:BASH_CopyrightHolder "" |COPYRIGHTHOLDER|
588 g:BASH_Template_Directory $HOME."/.vim/plugin/templates/"
589 g:BASH_Template_File "bash-file-header"
590 g:BASH_Template_Frame "bash-frame"
591 g:BASH_Template_Function "bash-function-description"
593 g:BASH_CodeSnippets $HOME."/.vim/codesnippets-bash"
594 g:BASH_LoadMenus "yes"
595 g:BASH_Dictionary_File $HOME."/.vim/wordlists/bash.list"
598 g:BASH_OutputGvim "vim"
599 g:BASH_XtermDefaults "-fa courier -fs 12 -geometry 80x24"
600 g:BASH_LineEndCommColDefault 49
601 g:BASH_SyntaxCheckOptionsGlob ""
603 --------------------------------------------------------------------------------
605 1. group: Defines the text which will be inserted for the tags when a template
606 is read in (see |bashsupport-tempfiles|).
608 g:BASH_AuthorName : author name
609 g:BASH_AuthorRef : author reference (e.g. acronym)
610 g:BASH_Email : email address
611 g:BASH_Company : name of the company / institution
612 g:BASH_Project : project
613 g:BASH_CopyrightHolder : the copyright holder
615 2. group: Sets the template directory and the names of the template files (see below).
617 3. group: g:BASH_CodeSnippets : The name of the code snippet directory
618 (see |bashsupport-stat-snippets|).
619 g:BASH_LoadMenus : Load menus and mappings ("yes", "no") at start up.
620 g:BASH_Dictionary_File : Path and file name of the bash word list used for
621 dictionary completion (see |bashsupport-dictionary|).
622 g:BASH_Root : The name of the root menu entry of this plugin
623 (see |bashsupport-custom-root|).
625 4. group: g:BASH_OutputGvim : Target for a script output
626 (see |bashsupport-output|).
627 g:BASH_XtermDefaults : The xterm defaults (see |bashsupport-xterm|).
628 g:BASH_LineEndCommColDefault : default starting column for line end comments
629 g:BASH_SyntaxCheckOptionsGlob : shopt options used with syntax checking
631 To override the defaults add appropriate assignments in .vimrc .
632 Here are my settings as an example:
634 let g:BASH_AuthorName = "Dr.-Ing. Fritz Mehner"
635 let g:BASH_AuthorRef = "Mn"
636 let g:BASH_Email = "mehner@fh-swf.de"
637 let g:BASH_Company = "FH Südwestfalen, Iserlohn"
639 This plugin sets the global variable is_bash:
641 This assignment is necessary to avoid a wrong syntax highlighting for $(..) and
644 ------------------------------------------------------------------------------
645 4.3 THE ROOT MENU *bashsupport-custom-root*
646 ------------------------------------------------------------------------------
648 The variable g:BASH_Root, if set (in .vimrc or in .gvimrc), gives the name of
649 the single gVim root menu entry in which the Bash submenus will be put.
652 Note the terminating dot. A single root menu entry is appropriate if the
653 screen is limited or several plugins are in use.
655 If set to "", this single root menu entry will not appear. Now all submenus
656 are put into the gVim root menu. Nice for a Bash-only-programmer and Bash
660 ==============================================================================
661 5. TEMPLATE FILES AND TAGS *bashsupport-tempfiles*
662 ==============================================================================
664 ------------------------------------------------------------------------------
666 ------------------------------------------------------------------------------
668 Three menu entries generate block comments:
670 bash -> Comments -> Frame Comment
671 bash -> Comments -> Function Description
672 bash -> Comments -> File Header
674 The comments which will be inserted by these menu entries are read from
677 ------------------------------------------------------------------------------
678 MENU ENTRY FILE GLOBAL VARIABLE
679 ------------------------------------------------------------------------------
680 Frame Comment bash-frame g:BASH_Template_Frame
681 Function Description bash-function-description g:BASH_Template_Function
682 File Header bash-file-header g:BASH_Template_File
683 ------------------------------------------------------------------------------
685 The template files can be written or changed by the user to fulfill special
686 requirements (layout for a project or work group already exists, file headers /
687 blocks have to be prepared for a documentation tool, ... ). They can hold not
688 only comments but a complete file skeleton if this is necessary. So you may
689 want to lay out your own templates.
691 ------------------------------------------------------------------------------
692 5.2 TAGS *bashsupport-tags*
693 ------------------------------------------------------------------------------
694 The comments in these files do not have to be personalized but they can be.
695 The text can contain the following tags which are replaced by the appropriate
696 information when the file is read in:
712 Each tag can occur more than once. The tag |CURSOR| may appear only once.
713 The tag |CURSOR| will be the cursor position after the block is read in.
714 There is no need to use any of these tags, some or all can be missing.
716 The template files can actually be links pointing to existing templates.
719 ==============================================================================
720 6. BASH DICTIONARY *bashsupport-dictionary*
721 ==============================================================================
723 The file bash.list contains words used as dictionary for automatic word
724 completion. This feature is enabled by default. The default word list is
726 $HOME/.vim/wordlists/bash.list
728 If you want to use an additional list MyBash.List put the following line into
731 let g:BASH_Dictionary_File = "$HOME/.vim/wordlists/bash.list,".
732 \ "$HOME/.vim/wordlists/MyBash.List"
734 The right side is a comma separated list of files. Note the point at the end
735 of the first line (string concatenation) and the backslash in front of the
736 second line (continuation line).
737 You can use Vim's dictionary feature CTRL-X, CTRL-K (and CTRL-P, CTRL-N).
740 ==============================================================================
741 7. Release Notes *bashsupport-release-notes*
742 ==============================================================================
744 See file README.bashsupport .
746 ==============================================================================
747 vim:tw=78:noet:ts=2:ft=help:norl: