*tComment.txt*  tComment -- An easily extensible & universal comment plugin

Author: Thomas Link, micathom AT gmail com?subject=vim

tComment provides easy to use, file-type sensible comments for Vim. It 
can handle embedded syntax.


                                                    *tComment-Installation*
Installation~
Edit the vba file and type:

    :so %

See :help vimball for details. If you use vim 7.0, you may need to 
update your vimball installation first.


                                                    *tComment-Usage*
Usage~
TComment works like a toggle, i.e., it will comment out text that 
contains uncommented lines, and it will remove comment markup for 
already commented text (i.e. text that contains no uncommented lines).

If the file-type is properly defined, TComment will figure out which 
comment string to use. Otherwise you use |TCommentDefineType()| to 
override the default choice.

TComment can properly handle an embedded syntax, e.g., ruby/python/perl 
regions in vim scripts, HTML or JavaScript in php code etc.


                                                    *tComment-Key-Bindings*
Key bindings~

Most of the time the default toggle keys will do what you want (or to be 
more precise: what I think you want it to do ;-).

                                                    *g:tcommentMapLeaderOp1*
                                                    *g:tcommentMapLeaderOp2*
As operator (the prefix can be customized via g:tcommentMapLeaderOp1 
and g:tcommentMapLeaderOp2):

    gc{motion}   :: Toggle comments (for small comments within one line 
                    the &filetype_inline style will be used, if 
                    defined)
    gcc          :: Toggle comment for the current line
    gC{motion}   :: Comment region
    gCc          :: Comment the current line

                                                    *g:tcommentOpModeExtra*
By default the cursor stays put. If you want the cursor to the end of 
the commented text, set g:tcommentOpModeExtra to '>' (but this may not 
work properly with exclusive motions).

Primary key maps:

    <c-_><c-_>   :: :TComment
    <c-_><space> :: :TComment <QUERY COMMENT-BEGIN ?COMMENT-END>
    <c-_>b       :: :TCommentBlock
    <c-_>a       :: :TCommentAs <QUERY COMMENT TYPE>
    <c-_>n       :: :TCommentAs &filetype <QUERY COUNT>
    <c-_>s       :: :TCommentAs &filetype_<QUERY COMMENT SUBTYPE>
    <c-_>i       :: :TCommentInline
    <c-_>r       :: :TCommentRight
    <c-_>p       :: Comment the current inner paragraph

A secondary set of key maps is defined for normal mode.

    <Leader>__       :: :TComment
    <Leader>_p       :: Comment the current inner paragraph
    <Leader>_<space> :: :TComment <QUERY COMMENT-BEGIN ?COMMENT-END>
    <Leader>_i       :: :TCommentInline
    <Leader>_r       :: :TCommentRight
    <Leader>_b       :: :TCommentBlock
    <Leader>_a       :: :TCommentAs <QUERY COMMENT TYPE>
    <Leader>_n       :: :TCommentAs &filetype <QUERY COUNT>
    <Leader>_s       :: :TCommentAs &filetype_<QUERY COMMENT SUBTYPE>

Keymaps are configurable via the following variables:

                                                    *g:tcommentMapLeader1*
g:tcommentMapLeader1    string (default: <c-_>)
        Prefix for the keymaps. Set to '' to disable keymaps with this 
        prefix.
                                                    *g:tcommentMapLeader2*
g:tcommentMapLeader2    string (default: <Leader>_)
        Secondary prefix. (The reason for why there are two prefixes is 
        that <c-_> appears preferable with gvim but can be difficult to 
        type on the terminal. The secondary prefix isn't used for insert 
        mode maps. Set to '' to disable keymaps with this prefix.

                                                    *tComment-commands*
Alternatively, you can type (? meaning "optional argument"):

                                                    *:TComment*
    :?<range> TComment ?commentBegin ?commentEnd
    :?<range> TComment! ?commentBegin ?commentEnd
    NOTE: If there is a visual selection that begins and ends in the same 
    line, then TCommentInline is used instead.

    NOTE: The range is optional and defaults to the current line.

                                                    *:TCommentInline*
    :?<range> TCommentInline ?commentBegin ?commentEnd
    :?<range> TCommentInline! ?commentBegin ?commentEnd
    Use the {&ft}_inline comment style.

                                                    *:TCommentBlock*
    :?<range> TCommentBlock ?commentBegin ?commentEnd
    :?<range> TCommentBlock! ?commentBegin ?commentEnd
    Comment as "block", e.g. use the {&ft}_block comment style.
    NOTE: This command is kind of crude. It doesn't indent or reformat 
    the text.

                                                    *:TCommentAs*
    :?<range> TCommentAs filetype
    :?<range> TCommentAs! filetype
    NOTE: TCommentAs requires g:tcomment_{filetype} to be defined.
    NOTE: This command supports command line completion. See 'wildmode' 
    and 'wildmenu' for how to get the most out of it.

                                                    *:TCommentRight*
    :?<range> TCommentRight
    :?<range> TCommentRight!
    NOTE: This command comments out the text to the right of the cursor. 
    If a visual selection was made (be it block-wise or not), all lines 
    are commented out at from the current cursor position downwards.

    The bang (!) variants always comment out the selected text and don't 
    work as toggles.

                                                    *TCommentDefineType()*
    Using this command you can also use different comment styles with 
    the TCommentDefineType(name, commentstring) function. This function 
    takes two arguments:
        name :: The name is either &filetype or {&filetype}_{style}. 
            I.e., For block comments the {&filetype}_block and for 
            inline comments the {&filetype}_inline styles are used.
        comment string :: a string mostly as described in 
            'commentstring'.
    
    If you want to define, e.g., a fancy block comment style for html 
    you put something like this into ~/.vim/after/plugin/tComment.vim:>

        call TCommentDefineType("html_fancy_block", "<!--%s  -->\n  -- ")

<   The part after the newline character is used for marking "middle" 
    lines.

    This comment style could then be accessed via (this command has 
    command line completion): >

        '<,'>TCommentAs html_fancy_block

<   If you're editing a html file, this could best be done by the <c-_>s     
    key map.


Goals~
- Maintain indentation of selected text; the comment markers are left 
  aligned but the text on the right (i.e., the comment) is indented 
  like the original text

- Handle embedded syntax like php+html or html+javaScript+css; you 
  have to set g:tcommentGuessFileType_{&filetype} to 1 or to the 
  fall-back file-type in order to activate this feature for other file 
  types than php or html
  
  tComment deduces the correct file type from the syntax name, similar 
  to the way EnhancedCommentify.vim does it. In opposition to 
  EnhancedCommentify.vim, it matches the syntax name against a list the 
  known file types, so that it can deal with, e.g., embedded javaScript

- Easy to customize/adapt for an yet unknown syntax by setting buffer 
  local variables (b:commentStart, b:commentEnd, or b:commentstring), 
  global variables (g:tcomment_{&ft} and g:tcomment_{&ft}_block), or the 
  buffer local &commentstring option (which can be set on a vim 
  |modeline|)

- Use 'commentstring' or 'comments' as a fallback (i.e., if a file-type 
  is properly defined, TComment will automatically support it)

- Same short-cut for commenting text and for removing comment markup

- The decision whether text should be commented or uncommented is made 
  on the basis of the whole selection (not line by line); comments in 
  code that should be commented aren't uncommented as it is the case 
  with some other plug-ins

As of version 1.5, the following file types are explicitly defined 
(other file-types are most likely supported through the 'commentstring' 
or 'comments' variables):

    ada, apache, autoit, catalog, cpp, css, c, cfg, conf, desktop, 
    docbk, dosbatch, dosini, dsl, dylan, eiffel, gtkrc, haskell, html, 
    io, javaScript, java, lisp, m4, nroff, objc, ocaml, pascal, perl, 
    php, prolog, ruby, r, scheme, sgml, sh, sql, spec, sps, tcl, tex, 
    tpl, viki, vim, websec, xml, xslt, yaml


Credits~
The way we check for embedded syntax was originally adapted 
from/inspired by Meikel Brandmeyer's EnhancedCommentify.vim
(vimscript #23) but has evolved since.


vim: tw=72