*tComment.txt*  tComment -- One comment plugin to rule them all

Author: Thomas Link, samul AT web.de

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


                                                    *tComment-Installation*
Installation~
Copy the file tComment.vim to your plugin directory (~/.vim/plugins/ or 
similar). See |standard-plugin| for further details.

                                                    *tComment-uninstall*
In case you have some bash or similar, you can feed the file 
etc/tComment.lst to rm: >
    
    cd $HOME/.vim/
    rm -i `cat etc/tComment.lst`

                                                    *tComment-Usage*
Usage~
The command TComment is bound to <c-_><c-_> by default. 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).

                                                    *tComment-Key-Bindings*
Key bindings~
    <c-_><c-_>   :: :TComment
    <c-_><space> :: :TComment <QUERY COMMENT-BEGIN ?COMMENT-END>
    <c-_>b       :: :TCommentBlock
    <c-_>a       :: :TCommentAs <QUERY COMMENT TYPE>
    <c-_>s       :: :TCommentAs &filetype_<QUERY COMMENT SUBTYPE>
    <c-_>i       :: :TCommentInline
    <c-_>r       :: :TCommentRight

                                                    *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 positon 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 could do something like: >

        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 
  fallback 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 filetype 
  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 plugins

As of version 1.5, the following file types are explicitly defined 
(other filetypes 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 adapted from/inspired by Meikel 
Brandmeyer's EnhancedCommentify.vim (vimscript #23).


vim: tw=72
