*tcomment.txt*  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 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 |tcomment#DefineType()| 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-maps*
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>


-----------------------------------------------------------------------
Install~

Edit the vba file and type: >

    :so %

See :help vimball for details. If you have difficulties or use vim 7.0, 
please make sure, you have the current version of vimball (vimscript 
#1502) installed or update your runtime.


========================================================================
Contents~

        :TComment ..................... |:TComment|
        :TCommentAs ................... |:TCommentAs|
        :TCommentRight ................ |:TCommentRight|
        :TCommentBlock ................ |:TCommentBlock|
        :TCommentInline ............... |:TCommentInline|
        :TCommentMaybeInline .......... |:TCommentMaybeInline|
        tcomment#DefineType ........... |tcomment#DefineType()|
        tcomment#TypeExists ........... |tcomment#TypeExists()|
        tcomment#Comment .............. |tcomment#Comment()|
        tcomment#Operator ............. |tcomment#Operator()|
        tcomment#OperatorLine ......... |tcomment#OperatorLine()|
        tcomment#OperatorAnyway ....... |tcomment#OperatorAnyway()|
        tcomment#OperatorLineAnyway ... |tcomment#OperatorLineAnyway()|
        tcomment#CommentAs ............ |tcomment#CommentAs()|
        tcomment#CollectFileTypes ..... |tcomment#CollectFileTypes()|
        tcomment#Complete ............. |tcomment#Complete()|
        tcomment#CompleteArgs ......... |tcomment#CompleteArgs()|


========================================================================
plugin/tcomment.vim~

                                                    *:TComment*
:[range]TComment[!] ?ARGS...
    If there is a visual selection that begins and ends in the same line, 
    then |:TCommentInline| is used instead.
    The optional range defaults to the current line. With a bang '!', 
    always comment the line.
    
    ARGS... are either (see also |tcomment#Comment()|):
      1. a list of key=value pairs
      2. 1-2 values for: ?commentBegin, ?commentEnd

                                                    *:TCommentAs*
:[range]TCommentAs[!] commenttype ?ARGS...
    TCommentAs requires g:tcomment_{filetype} to be defined.
    With a bang '!', always comment the line.
    
    ARGS... are either (see also |tcomment#Comment()|):
      1. a list of key=value pairs
      2. 1-2 values for: ?commentBegin, ?commentEnd

                                                    *:TCommentRight*
:[range]TCommentRight[!] ?ARGS...
    Comment 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.
    With a bang '!', always comment the line.
    
    ARGS... are either (see also |tcomment#Comment()|):
      1. a list of key=value pairs
      2. 1-2 values for: ?commentBegin, ?commentEnd

                                                    *:TCommentBlock*
:[range]TCommentBlock[!] ?ARGS...
    Comment as "block", e.g. use the {&ft}_block comment style. The 
    commented text isn't indented or reformated.
    With a bang '!', always comment the line.
    
    ARGS... are either (see also |tcomment#Comment()|):
      1. a list of key=value pairs
      2. 1-2 values for: ?commentBegin, ?commentEnd

                                                    *:TCommentInline*
:[range]TCommentInline[!] ?ARGS...
    Use the {&ft}_inline comment style.
    With a bang '!', always comment the line.
    
    ARGS... are either (see also |tcomment#Comment()|):
      1. a list of key=value pairs
      2. 1-2 values for: ?commentBegin, ?commentEnd

                                                    *:TCommentMaybeInline*
:[range]TCommentMaybeInline[!] ?ARGS...
    With a bang '!', always comment the line.
    
    ARGS... are either (see also |tcomment#Comment()|):
      1. a list of key=value pairs
      2. 1-2 values for: ?commentBegin, ?commentEnd


========================================================================
autoload/tcomment.vim~

                                                    *tcomment#DefineType()*
tcomment#DefineType(name, commentdef)
    Currently this function just sets a variable

                                                    *tcomment#TypeExists()*
tcomment#TypeExists(name)
    Return 1 if a comment type is defined.

                                                    *tcomment#Comment()*
tcomment#Comment(beg, end, ...)
    tcomment#Comment(line1, line2, ?commentMode, ?commentAnyway, ?args...)
    args... are either:
      1. a list of key=value pairs where known keys are:
            as=STRING     ... Use a specific comment definition
            col=N         ... Start the comment at column N (in block mode; must 
                              be smaller than |indent()|)
            mode=STRING   ... See the notes below on the "commentMode" argument
            begin=STRING  ... Comment prefix
            end=STRING    ... Comment postfix
            middle=STRING ... Middle line comments in block mode
            rxbeg=N       ... Regexp to find the substring of "begin" that 
                              should be multipied by "count"
            rxend=N       ... The above for "end"
            rxmid=N       ... The above for "middle"
      2. 1-2 values for: ?commentPrefix, ?commentPostfix
      3. a dictionary (internal use only)
    
    commentMode:
      G ... guess the value of commentMode
      B ... block (use extra lines for the comment markers)
      i ... maybe inline, guess
      I ... inline
      R ... right (comment the line right of the cursor)
      v ... visual
      o ... operator
    By default, each line in range will be commented by adding the comment 
    prefix and postfix.

                                                    *tcomment#Operator()*
tcomment#Operator(type, ...)

                                                    *tcomment#OperatorLine()*
tcomment#OperatorLine(type)

                                                    *tcomment#OperatorAnyway()*
tcomment#OperatorAnyway(type)

                                                    *tcomment#OperatorLineAnyway()*
tcomment#OperatorLineAnyway(type)

                                                    *tcomment#CommentAs()*
tcomment#CommentAs(beg, end, commentAnyway, filetype, ?args...)
    Where args is either:
      1. A count NUMBER
      2. An args list (see the notes on the "args" argument of 
         |tcomment#Comment()|)
    comment text as if it were of a specific filetype

                                                    *tcomment#CollectFileTypes()*
tcomment#CollectFileTypes()
    collect all known comment types

                                                    *tcomment#Complete()*
tcomment#Complete(ArgLead, CmdLine, CursorPos)
    return a list of filetypes for which a tcomment_{&ft} is defined

                                                    *tcomment#CompleteArgs()*
tcomment#CompleteArgs(ArgLead, CmdLine, CursorPos)



vim:tw=78:fo=tcq2:isk=!-~,^*,^|,^":ts=8:ft=help:norl:
