209 lines
8.5 KiB
Plaintext
209 lines
8.5 KiB
Plaintext
*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
|