*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.

Demo:
http://vimsomnia.blogspot.com/2010/11/tcomment-vim-plugin.html


                                                    *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

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|
        g:tcommentBlankLines ................ |g:tcommentBlankLines|
        g:tcommentOpModeExtra ............... |g:tcommentOpModeExtra|
        g:tcommentOptions ................... |g:tcommentOptions|
        g:tcomment#ignore_char_type ......... |g:tcomment#ignore_char_type|
        g:tcommentGuessFileType ............. |g:tcommentGuessFileType|
        g:tcommentGuessFileType_dsl ......... |g:tcommentGuessFileType_dsl|
        g:tcommentGuessFileType_php ......... |g:tcommentGuessFileType_php|
        g:tcommentGuessFileType_html ........ |g:tcommentGuessFileType_html|
        g:tcommentGuessFileType_tskeleton ... |g:tcommentGuessFileType_tskeleton|
        g:tcommentGuessFileType_vim ......... |g:tcommentGuessFileType_vim|
        g:tcommentGuessFileType_django ...... |g:tcommentGuessFileType_django|
        g:tcommentIgnoreTypes_php ........... |g:tcommentIgnoreTypes_php|
        g:tcomment#syntax_substitute ........ |g:tcomment#syntax_substitute|
        g:tcommentSyntaxMap ................. |g:tcommentSyntaxMap|
        g:tcommentBlockC .................... |g:tcommentBlockC|
        g:tcommentBlockC2 ................... |g:tcommentBlockC2|
        g:tcommentInlineC ................... |g:tcommentInlineC|
        g:tcommentBlockXML .................. |g:tcommentBlockXML|
        g:tcommentInlineXML ................. |g:tcommentInlineXML|
        tcomment#DefineType ................. |tcomment#DefineType()|
        tcomment#Comment .................... |tcomment#Comment()|
        tcomment#Operator ................... |tcomment#Operator()|
        tcomment#OperatorLine ............... |tcomment#OperatorLine()|
        tcomment#OperatorAnyway ............. |tcomment#OperatorAnyway()|
        tcomment#OperatorLineAnyway ......... |tcomment#OperatorLineAnyway()|
        tcomment#CommentAs .................. |tcomment#CommentAs()|


========================================================================
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~

                                                    *g:tcommentBlankLines*
g:tcommentBlankLines           (default: 1)
    If true, comment blank lines too

                                                    *g:tcommentOpModeExtra*
g:tcommentOpModeExtra          (default: '')
    Modifies how the operator works.
      > ... Move the cursor to the end of the comment

                                                    *g:tcommentOptions*
g:tcommentOptions              (default: {})
    Other key-value options used by |tcomment#Comment()|.
    
    Example: If you want to put the opening comment marker always in 
    the first column regardless of the block's indentation, put this 
    into your |vimrc| file: >
      let g:tcommentOptions = {'col': 1}
<

                                                    *g:tcomment#ignore_char_type*
g:tcomment#ignore_char_type    (default: 1)
    |text-objects| for use with |tcomment#Operator| can have different 
    types: line, block, char etc. Text objects like aB, it, at etc. 
    have type char but this may not work reliably. By default, 
    tcomment handles those text objects most often as if they were of 
    type line. Set this variable to 0 in order to change this 
    behaviour. Be prepared that the result may not always match your 
    intentions.

                                                    *g:tcommentGuessFileType*
g:tcommentGuessFileType        (default: 0)
    Guess the file type based on syntax names always or for some fileformat only
    If non-zero, try to guess filetypes.
    tcomment also checks g:tcommentGuessFileType_{&filetype} for 
    filetype specific values.
    
    Values:
      0        ... don't guess
      1        ... guess
      FILETYPE ... assume this filetype

                                                    *g:tcommentGuessFileType_dsl*
g:tcommentGuessFileType_dsl    (default: 'xml')
    For dsl documents, assumet filetype = xml.

                                                    *g:tcommentGuessFileType_php*
g:tcommentGuessFileType_php    (default: 'html')
    In php documents, the php part is usually marked as phpRegion. We 
    thus assume that the buffers default comment style isn't php but 
    html.

                                                    *g:tcommentGuessFileType_html*
g:tcommentGuessFileType_html   (default: 1)

                                                    *g:tcommentGuessFileType_tskeleton*
g:tcommentGuessFileType_tskeleton (default: 1)

                                                    *g:tcommentGuessFileType_vim*
g:tcommentGuessFileType_vim    (default: 1)

                                                    *g:tcommentGuessFileType_django*
g:tcommentGuessFileType_django (default: 1)

                                                    *g:tcommentIgnoreTypes_php*
g:tcommentIgnoreTypes_php      (default: 'sql')
    In php files, some syntax regions are wongly highlighted as sql 
    markup. We thus ignore sql syntax when guessing the filetype in 
    php files.

                                                    *g:tcomment#syntax_substitute*
g:tcomment#syntax_substitute   (default: {...})

                                                    *g:tcommentSyntaxMap*
g:tcommentSyntaxMap            (default: {...})
    tcomment guesses filetypes based on the name of the current syntax 
    region. This works well if the syntax names match 
    /filetypeSomeName/. Other syntax names have to be explicitly 
    mapped onto the corresponding filetype.

                                                    *g:tcommentBlockC*
g:tcommentBlockC               (default: {...})
    Generic c-like block comments.

                                                    *g:tcommentBlockC2*
g:tcommentBlockC2              (default: {...})
    Generic c-like block comments (alternative markup).

                                                    *g:tcommentInlineC*
g:tcommentInlineC              (default: "/* %s */")
    Generic c-like comments.

                                                    *g:tcommentBlockXML*
g:tcommentBlockXML             (default: "<!--%s-->\n  ")
    Generic xml-like block comments.

                                                    *g:tcommentInlineXML*
g:tcommentInlineXML            (default: "<!-- %s -->")
    Generic xml-like comments.

                                                    *tcomment#DefineType()*
tcomment#DefineType(name, commentdef)
    If you don't explicitly define a comment style, |:TComment| will use 
    'commentstring' instead. We override the default values here in order 
    to have a blank after the comment marker. Block comments work only if 
    we explicitly define the markup.
    
    The comment definition can be either a string or a dictionary.
    
    If it is a string:
    The format for block comments is similar to 'commentstrings' with the 
    exception that the format strings for blocks can contain a second line 
    that defines how "middle lines" (see :h format-comments) should be 
    displayed.
    
    If it is a dictionary:
    See the help on the args argument of |tcomment#Comment|.

                                                    *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 (see also 
         |g:tcommentOptions|):
            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"
            commentstring_rx ... A regexp format string that matches 
                                 commented lines (no new groups may be 
                                 introduced, the |regexp| is |\V|; % have 
                                 to be doubled); "commentstring", "begin" 
                                 and optionally "end" must be defined or 
                                 deducible.
      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



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