*context-commentstring.txt* Change 'commentstring' according to context.
Version 0.1.0
Script ID: ????
Copyright © 2013 Alejandro Exojo Piqueras
License: MIT license {{{
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}}}
CONTENTS *context-commentstring-contents*
Introduction |context-commentstring-introduction|
Installation |context-commentstring-installation|
Configuration and usage |context-commentstring-configuration|
Customization |context-commentstring-customization|
Bugs and limitations |context-commentstring-bugs|
Credits and considerations |context-commentstring-credits|
Changelog |context-commentstring-changelog|
==============================================================================
INTRODUCTION *context-commentstring-introduction*
*context-commentstring* is a Vim plugin that sets the value of 'commentstring'
to a different value depending on the region of the file you are in. Is only
useful for |file-types| where is possible to have a language embedded in a
language. The most common example are small pieces of CSS or JavaScript in an
HTML file, but also Lua, Python or Perl blocks embedded in Vim code.
Note that it relies on the parsing done by the |syntax| highlighting system,
so it works out of the box for several well known |file-types|, but you will
have to write some |syntax-highlighting| file yourself if you don't have any
and want to use this plugin for your |file-type|.
The use of 'commentstring' is not very popular, but is necessary for Vim's
|zf| action if you use the |fold-marker| feature. Is also exploited by Tim
Pope's |commentary.txt| plugin, a utility to comment and uncomment lines of
code. Find the plugin at:
https://github.com/tpope/vim-commentary
Additionally, this plugin sets the value of the 'comments' setting
automatically. The 'comments' setting describes how inserting new lines should
be handled when inside a comment region. This automatic formatting can be
configured via the 'formatoptions' setting.
------------------------------------------------------------------------------
INSTALLATION *context-commentstring-installation*
The usual for any other Vim plugin: copy the files where Vim will look for
them with the same directory layout that came with the plugin. If you use
other plugins, color schemes, etc. that are installed by you, you probably
know where that is. In UNIX-like systems (Linux, Mac OS X), is some place like
$HOME/.vim, and on Windows $HOME/vimfiles. See |vimfiles| for details.
If you don't have installed any plugins yet, I strongly recommend to first
install and configure a plugin manager (a plugin to help you with other
plugins), and then install |context-commentstring|. My recommendation is that
you start with Pathogen because is very simple and it works very well with a
version control system. Find it at:
https://github.com/tpope/vim-pathogen
------------------------------------------------------------------------------
CONFIGURATION AND USAGE *context-commentstring-configuration*
It should work out of the box for HTML and VimL (Vim script) files. It will
simply change the value of 'commentstring' when you are in the appropriate
region. See below for how to customize or extend it.
==============================================================================
CUSTOMIZATION *context-commentstring-customization*
The plugin works by checking if the current syntax group matches a group of an
embedded language, for example, JavaScript inside HTML. You can check the
default values by looking the source code, or simply with >
echo g:context#commentstring#table
<
This variable is of type |Dictionary|, and you can modify it to your will. You
can add values or overwrite existing ones. If you think that some missing
values are useful to you, contact the author so maybe others can benefit as
well.
The keys of the |Dictionary| variable are the |file-type| where you want the
'commentstring' to change, and the values are nested |Dictionaries| that have
pairs of syntax groups and values for 'commentstring' as keys and values
respectively.
You will need to know the names of the syntax group. For that, you can use the
|zS| command provided by |scriptease|, or use this simple but convenient
snippet of code: >
augroup temporary_test
autocmd CursorMoved
\ echo map(synstack(line('.'), col('.')),
\ 'synIDattr(v:val, "name")')
<
That will echo to the |Command-line| an array of the values of the current
syntax groups. When you are done with your testing, remove the echo doing: >
autocmd!
augroup END
<
The 'comments' setting can be configured the exact same way as 'commentstring'
but the variable to change is >
g:context#commentstring#comments_table
==============================================================================
BUGS *context-commentstring-bugs*
At the moment, there is only one known issue: it doesn't work properly at the
edges of the embedded language, where the boundary is. Is unlikely that this
will have a solution, and is an uncommon case anyway. Try to move the cursor
one extra line further.
Feel free to contact the author through Gitorious or GitHub:
https://gitorious.org/vim-for-qt-kde/vim-context-commentstring
https://github.com/suy/vim-context-commentstring
==============================================================================
CREDITS AND CONSIDERATIONS *context-commentstring-credits*
This plugin was created almost solely to be used as a sidekick for
|commentary.txt|, by Tim Pope. And I only had the guts to attempt to implement
it because I could look at the code of |scriptease.txt| (also by Tim Pope),
where the names of the syntax groups are provided by |zS|. That was almost
half the work, and to my taste the more boring one. So kudos to him. If you
don't know his work yet, be sure to check it out. Closely tied with Kana
Natsuno and Shougo Matsushita, is probably the most brilliant and active Vim
plugin author.
==============================================================================
CHANGELOG *context-commentstring-changelog*
0.1.1 2014-06-06
- Clear the autocommand always, in case the filetype is changed for
whatever reason.
0.1.0 2013-06-06
- First public release.
==============================================================================
vim:tw=80:ts=8:ft=help:norl:fen:fdl=0:fdm=marker: