vim/syntastic
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

README: reorganise the FAQ.

Browse Source
This commit is contained in:
LCD 47 2016-08-31 10:14:03 +03:00
parent f527cb1a2d
commit 631df935f6
2 changed files with 169 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

353
README.markdown
View File

@ -25,22 +25,21 @@
3. [Recommended settings](#settings) 3. [Recommended settings](#settings)
4. [FAQ](#faq) 4. [FAQ](#faq)
4.1. [I installed syntastic but it isn't reporting any errors...](#faqinfo) 4.1. [I installed syntastic but it isn't reporting any errors...](#faqinfo)
4.2. [How can I check scripts written for different versions of Python?](#faqpython) 4.2. [Syntastic supports several checkers for my filetype, how do I tell it which one(s) to use?](#faqcheckers)
4.3. [How can I check scripts written for different versions of Ruby?](#faqruby) 4.3. [I have enabled multiple checkers for the current filetype. How can I display all errors from all checkers together?](#faqaggregate)
4.4. [Are there any local checkers for HTML5 that I can use with syntastic?](#faqhtml5) 4.4. [How can I pass additional arguments to a checker?](#faqargs)
4.5. [The `perl` checker has stopped working...](#faqperl) 4.5. [I run a checker and the location list is not updated...](#faqloclist)
4.6. [What happened to the `rustc` checker?](#faqrust) 4.5. [I run`:lopen` or `:lwindow` and the error window is empty...](#faqloclist)
4.7. [What happened to the `tsc` checker?](#faqtsc) 4.6. [How can I jump between the different errors without using the location list at the bottom of the window?](#faqlnext)
4.8. [What happened to the `xcrun` checker?](#faqxcrun) 4.7. [The error window is closed automatically when I :quit the current buffer but not when I :bdelete it?](#faqbdelete)
4.9. [I run a checker and the location list is not updated...](#faqloclist) 4.8. [My favourite checker needs to load a configuration file from the project's root rather than the current directory...](#faqconfig)
4.9. [I run`:lopen` or `:lwindow` and the error window is empty...](#faqloclist) 4.9. [What is the difference between syntax checkers and style checkers?](#faqstyle)
4.10. [How can I pass additional arguments to a checker?](#faqargs) 4.10. [How can I check scripts written for different versions of Python?](#faqpython)
4.11. [Syntastic supports several checkers for my filetype - how do I tell which one(s) to use?](#faqcheckers) 4.11. [How can I check scripts written for different versions of Ruby?](#faqruby)
4.12. [What is the difference between syntax checkers and style checkers?](#faqstyle) 4.12. [The `perl` checker has stopped working...](#faqperl)
4.13. [I have enabled multiple checkers for the current filetype. How can I display all errors from all checkers together?](#faqaggregate) 4.13. [What happened to the `rustc` checker?](#faqrust)
4.14. [How can I jump between the different errors without using the location list at the bottom of the window?](#faqlnext) 4.14. [What happened to the `tsc` checker?](#faqtsc)
4.15. [My favourite checker needs to load a configuration file from the project's root rather than the current directory...](#faqconfig) 4.15. [What happened to the `xcrun` checker?](#faqxcrun)
4.16. [The error window is closed automatically when I :quit the current buffer but not when I :bdelete it?](#faqbdelete)
5. [Resources](#otherresources) 5. [Resources](#otherresources)
- - - - - -
@ -230,131 +229,12 @@ or the error output for a syntax checker may have changed. In this case, make
sure you have the latest version of the syntax checker installed. If it still sure you have the latest version of the syntax checker installed. If it still
fails then post an [issue][bug_tracker] - or better yet, create a pull request. fails then post an [issue][bug_tracker] - or better yet, create a pull request.
<a name="faqpython"></a>
__4.2. Q. How can I check scripts written for different versions of Python?__
A. Install a Python version manager such as [virtualenv][virtualenv]
or [pyenv][pyenv], activate the environment for the relevant version
of Python, and install in it the checkers you want to use. Set
`g:syntastic_python_checkers` accordingly in your `vimrc`, and run [Vim][vim]
from the virtual environment.
If you're starting Vim from a desktop manager rather than from a terminal you
might need to write wrapper scripts around your checkers, to activate the
virtual environment before running the actual checks. Then you'll need to
point the relevant `g:syntastic_python_<checker>_exec` variables to the wrapper
scripts.
<a name="faqruby"></a>
__4.3. Q. How can I check scripts written for different versions of Ruby?__
A. Install a Ruby version manager such as [rvm][rvm] or [rbenv][rbenv],
activate the environment for the relevant version of Ruby, and install in it
the checkers you want to use. Set `g:syntastic_ruby_checkers` accordingly in
your `vimrc`, and run [Vim][vim] from the virtual environment.
If you're starting Vim from a desktop manager rather than from a terminal you
might need to write wrapper scripts around your checkers, to activate the
virtual environment before running the actual checks. Then you'll need to
point the relevant `g:syntastic_ruby_<checker>_exec` variables to the wrapper
scripts.
<a name="faqhtml5"></a>
__4.4. Q. Are there any local checkers for HTML5 that I can use with syntastic?__
[HTML Tidy][tidy_old] has a fork named [HTML Tidy for HTML5][tidy]. It's a drop
in replacement, and syntastic can use it without changes. Just install it
somewhere and point `g:syntastic_html_tidy_exec` to its executable:
```vim
let g:syntastic_html_tidy_exec = 'tidy5'
```
Alternatively, you can install [vnu.jar][vnu_jar] from the [validator.nu][vnu]
project and run it as a [HTTP server][vnu_server]:
```sh
$ java -Xss512k -cp /path/to/vnu.jar nu.validator.servlet.Main 8888
```
Then you can configure syntastic to use it:
```vim
let g:syntastic_html_validator_api = 'http://localhost:8888/'
```
<a name="faqperl"></a>
__4.5. Q. The `perl` checker has stopped working...__
A. The `perl` checker runs `perl -c` against your file, which in turn
__executes__ any `BEGIN`, `UNITCHECK`, and `CHECK` blocks, and any `use`
statements in your file (cf. [perlrun][perlrun]). This is probably fine if you
wrote the file yourself, but it's a security problem if you're checking
third-party files. Since there is currently no way to disable this behaviour
while still producing useful results, the checker is now disabled by default.
To (re-)enable it, make sure the `g:syntastic_perl_checkers` list includes
`perl`, and set `g:syntastic_enable_perl_checker` to 1 in your `vimrc`:
```vim
let g:syntastic_enable_perl_checker = 1
```
<a name="faqrust"></a>
__4.6. Q. What happened to the `rustc` checker?__
A. It is now part of the [rust.vim][rust] plugin. If you install this plugin the
checker should be picked up automatically by syntastic.
<a name="faqtsc"></a>
__4.7. Q. What happened to the `tsc` checker?__
A. It didn't meet people's expectations and it has been removed. A better
checker for TypeScript comes with the plugin [tsuquyomi][tsuquyomi]. If you
install this plugin the checker should be picked up automatically by syntastic.
<a name="faqxcrun"></a>
__4.8. Q. What happened to the `xcrun` checker?__
A. The `xcrun` checker used to have a security problem and it has been removed.
A better checker for __Swift__ is part of the [vim-swift][swift] plugin. If you
install this plugin the checker should be picked up automatically by syntastic.
<a name="faqloclist"></a>
__4.9. Q. I run a checker and the location list is not updated...__
__4.9. Q. I run`:lopen` or `:lwindow` and the error window is empty...__
A. By default the location list is changed only when you run the `:Errors`
command, in order to minimise conflicts with other plugins. If you want the
location list to always be updated when you run the checkers, add this line to
your `vimrc`:
```vim
let g:syntastic_always_populate_loc_list = 1
```
<a name="faqargs"></a>
__4.10. Q. How can I pass additional arguments to a checker?__
A. Almost all syntax checkers use the `makeprgBuild()` function. Those checkers
that do can be configured using global variables. The general form of the
global `args` variables is `syntastic_<filetype>_<checker>_args`.
So, If you wanted to pass `--my --args --here` to the ruby mri checker you
would add this line to your `vimrc`:
```vim
let g:syntastic_ruby_mri_args = "--my --args --here"
```
See `:help syntastic-checker-options` for more information.
<a name="faqcheckers"></a> <a name="faqcheckers"></a>
__4.11. Q. Syntastic supports several checkers for my filetype - how do I tell it __4.2. Q. Syntastic supports several checkers for my filetype, how do I tell it
which one(s) to use?__ which one(s) to use?__
A. Stick a line like this in your `vimrc`: A. Add a line like this to your `vimrc`:
```vim ```vim
let g:syntastic_<filetype>_checkers = ['<checker-name>'] let g:syntastic_<filetype>_checkers = ['<checker-name>']
``` ```
@ -362,10 +242,9 @@ let g:syntastic_<filetype>_checkers = ['<checker-name>']
To see the list of supported checkers for your filetype read the To see the list of supported checkers for your filetype read the
[manual][checkers] (`:help syntastic-checkers` in Vim). [manual][checkers] (`:help syntastic-checkers` in Vim).
e.g. Python has the following checkers, among others: `flake8`, `pyflakes`, For example, Python has the following checkers, among others: `flake8`,
`pylint` and a native `python` checker. `pyflakes`, `pylint` and a native `python` checker. To tell syntastic to use
`pylint`, you would use this setting:
To tell syntastic to use `pylint`, you would use this setting:
```vim ```vim
let g:syntastic_python_checkers = ['pylint'] let g:syntastic_python_checkers = ['pylint']
``` ```
@ -379,8 +258,7 @@ This is telling syntastic to run the `php` checker first, and if no errors are
found, run `phpcs`, and then `phpmd`. found, run `phpcs`, and then `phpmd`.
You can also run checkers explicitly by calling `:SyntasticCheck <checker>`. You can also run checkers explicitly by calling `:SyntasticCheck <checker>`.
For example to run `phpcs` and `phpmd`:
e.g. to run `phpcs` and `phpmd`:
```vim ```vim
:SyntasticCheck phpcs phpmd :SyntasticCheck phpcs phpmd
``` ```
@ -390,39 +268,9 @@ aren't listed in `g:syntastic_<filetype>_checkers`. You can't run checkers for
"foreign" filetypes though (e.g. you can't run, say, a Python checker if the "foreign" filetypes though (e.g. you can't run, say, a Python checker if the
filetype of the current file is `php`). filetype of the current file is `php`).
<a name="faqstyle"></a>
__4.12. Q. What is the difference between syntax checkers and style checkers?__
A. The errors and warnings they produce are highlighted differently and can
be filtered by different rules, but otherwise the distinction is pretty much
arbitrary. There is an ongoing effort to keep things consistent, so you can
_generally_ expect messages produced by syntax checkers to be _mostly_ related
to syntax, and messages produced by style checkers to be _mostly_ about style.
But there can be no formal guarantee that, say, a style checker that runs into
a syntax error wouldn't die with a fatal message, nor that a syntax checker
wouldn't give you warnings against using some constructs as being bad practice.
There is also no guarantee that messages marked as "style" are less severe than
the ones marked as "syntax" (whatever that might mean). And there are even a
few Frankenstein checkers (for example `flake8` and `pylama`) that, by their
nature, produce both kinds of messages. Syntastic is not smart enough to be
able to sort out these things by itself.
In fact it's more useful to look at this from the perspective of filtering
unwanted messages, rather than as an indicator of severity levels. The
distinction between syntax and style is orthogonal to the distinction between
errors and warnings, and thus you can turn off messages based on level, on
type, or both.
e.g. To disable all style messages:
```vim
let g:syntastic_quiet_messages = { "type": "style" }
```
See `:help syntastic_quiet_messages` for details.
<a name="faqaggregate"></a> <a name="faqaggregate"></a>
__4.13. Q. I have enabled multiple checkers for the current filetype. How can I __4.3. Q. I have enabled multiple checkers for the current filetype. How can I
display all errors from all checkers together?__ display all errors from all checkers together?__
A. Set `g:syntastic_aggregate_errors` to 1 in your `vimrc`: A. Set `g:syntastic_aggregate_errors` to 1 in your `vimrc`:
@ -432,9 +280,46 @@ let g:syntastic_aggregate_errors = 1
See `:help syntastic-aggregating-errors` for more details. See `:help syntastic-aggregating-errors` for more details.
<a name="faqargs"></a>
__4.4. Q. How can I pass additional arguments to a checker?__
A. In most cases a command line is constructed using an internal function
named `makeprgBuild()`, which provides a number of options that allow you to
customise every part of the command that gets run. You can set these options
using global variables.
The general form of the global `args` variable is
`syntastic_<filetype>_<checker>_args`. Thus if you wanted to pass
`--my --args --here` to the Ruby `mri` checker you would add this line to your
`vimrc`:
```vim
let g:syntastic_ruby_mri_args = "--my --args --here"
```
See `:help syntastic-checker-options` for more information.
A number of checkers don't use the `makeprgBuild()` function mentioned above,
or have additional options that can be configured. For these checkers the exact
list of options should be included in the [manual][checkers]
(`:help syntastic-checkers` in Vim).
<a name="faqloclist"></a>
__4.5. Q. I run a checker and the location list is not updated...__
__4.5. Q. I run`:lopen` or `:lwindow` and the error window is empty...__
A. By default the location list is changed only when you run the `:Errors`
command, in order to minimise conflicts with other plugins. If you want the
location list to always be updated when you run the checkers, add this line to
your `vimrc`:
```vim
let g:syntastic_always_populate_loc_list = 1
```
<a name="faqlnext"></a> <a name="faqlnext"></a>
__4.14. Q. How can I jump between the different errors without using the location __4.6. Q. How can I jump between the different errors without using the location
list at the bottom of the window?__ list at the bottom of the window?__
A. Vim provides several built-in commands for this. See `:help :lnext` and A. Vim provides several built-in commands for this. See `:help :lnext` and
@ -444,9 +329,21 @@ If you use these commands a lot then you may want to add shortcut mappings to
your `vimrc`, or install something like [unimpaired][unimpaired], which provides such your `vimrc`, or install something like [unimpaired][unimpaired], which provides such
mappings (among other things). mappings (among other things).
<a name="faqbdelete"></a>
__4.7. Q. The error window is closed automatically when I :quit the current buffer
but not when I :bdelete it?__
A. There is no safe way to handle that situation automatically, but you can
work around it:
```vim
nnoremap <silent> <C-d> :lclose<CR>:bdelete<CR>
cabbrev <silent> bd <C-r>=(getcmdtype()==#':' && getcmdpos()==1 ? 'lclose\|bdelete' : 'bd')<CR>
```
<a name="faqconfig"></a> <a name="faqconfig"></a>
__4.15. My favourite checker needs to load a configuration file from the __4.8. My favourite checker needs to load a configuration file from the
project's root rather than the current directory...__ project's root rather than the current directory...__
A. You can set up an `autocmd` to search for the configuration file in the A. You can set up an `autocmd` to search for the configuration file in the
@ -463,18 +360,106 @@ autocmd FileType javascript let b:syntastic_javascript_jscs_args =
\ get(g:, 'syntastic_javascript_jscs_args', '') . \ get(g:, 'syntastic_javascript_jscs_args', '') .
\ FindConfig('-c', '.jscsrc', expand('<afile>:p:h', 1)) \ FindConfig('-c', '.jscsrc', expand('<afile>:p:h', 1))
``` ```
<a name="faqbdelete"></a>
__4.16. Q. The error window is closed automatically when I :quit the current buffer <a name="faqstyle"></a>
but not when I :bdelete it?__
A. There is no safe way to handle that situation automatically, but you can __4.9. Q. What is the difference between syntax checkers and style checkers?__
work around it:
A. The errors and warnings they produce are highlighted differently and can
be filtered by different rules, but otherwise the distinction is pretty much
arbitrary. There is an ongoing effort to keep things consistent, so you can
_generally_ expect messages produced by syntax checkers to be _mostly_ related
to syntax, and messages produced by style checkers to be _mostly_ about style.
But there can be no formal guarantee that, say, a style checker that runs into
a syntax error wouldn't die with a fatal message, nor that a syntax checker
wouldn't give you warnings against using some constructs as being bad practice.
There is also no guarantee that messages marked as `style` are less severe than
the ones marked as `syntax` (whatever that might mean). And there are even a
few Frankenstein checkers (for example `flake8` and `pylama`) that, by their
nature, produce both kinds of messages. Syntastic is not smart enough to be
able to sort out these things by itself.
Generally it's more useful to look at this from the perspective of filtering
unwanted messages, rather than as an indicator of severity levels. The
distinction between syntax and style is orthogonal to the distinction between
errors and warnings, and thus you can turn off messages based on level, on
type, or both.
e.g. To disable all style messages:
```vim ```vim
nnoremap <silent> <C-d> :lclose<CR>:bdelete<CR> let g:syntastic_quiet_messages = { "type": "style" }
cabbrev <silent> bd <C-r>=(getcmdtype()==#':' && getcmdpos()==1 ? 'lclose\|bdelete' : 'bd')<CR>
``` ```
See `:help syntastic_quiet_messages` for more information.
<a name="faqpython"></a>
__4.10. Q. How can I check scripts written for different versions of Python?__
A. Install a Python version manager such as [virtualenv][virtualenv]
or [pyenv][pyenv], activate the environment for the relevant version
of Python, and install in it the checkers you want to use. Set
`g:syntastic_python_checkers` accordingly in your `vimrc`, and run [Vim][vim]
from the virtual environment.
If you're starting Vim from a desktop manager rather than from a terminal you
might need to write wrapper scripts around your checkers, to activate the
virtual environment before running the actual checks. Then you'll need to
point the relevant `g:syntastic_python_<checker>_exec` variables to the wrapper
scripts.
<a name="faqruby"></a>
__4.11. Q. How can I check scripts written for different versions of Ruby?__
A. Install a Ruby version manager such as [rvm][rvm] or [rbenv][rbenv],
activate the environment for the relevant version of Ruby, and install in it
the checkers you want to use. Set `g:syntastic_ruby_checkers` accordingly in
your `vimrc`, and run [Vim][vim] from the virtual environment.
If you're starting Vim from a desktop manager rather than from a terminal you
might need to write wrapper scripts around your checkers, to activate the
virtual environment before running the actual checks. Then you'll need to
point the relevant `g:syntastic_ruby_<checker>_exec` variables to the wrapper
scripts.
<a name="faqperl"></a>
__4.12. Q. The `perl` checker has stopped working...__
A. The `perl` checker runs `perl -c` against your file, which in turn
__executes__ any `BEGIN`, `UNITCHECK`, and `CHECK` blocks, and any `use`
statements in your file (cf. [perlrun][perlrun]). This is probably fine if you
wrote the file yourself, but it's a security problem if you're checking
third-party files. Since there is currently no way to disable this behaviour
while still producing useful results, the checker is now disabled by default.
To (re-)enable it, make sure the `g:syntastic_perl_checkers` list includes
`perl`, and set `g:syntastic_enable_perl_checker` to 1 in your `vimrc`:
```vim
let g:syntastic_enable_perl_checker = 1
```
<a name="faqrust"></a>
__4.13. Q. What happened to the `rustc` checker?__
A. It is now part of the [rust.vim][rust] plugin. If you install this plugin the
checker should be picked up automatically by syntastic.
<a name="faqtsc"></a>
__4.14. Q. What happened to the `tsc` checker?__
A. It didn't meet people's expectations and it has been removed. The plugin
[tsuquyomi][tsuquyomi] comes packaged with a checker for TypeScript. If you
install this plugin the checker should be picked up automatically by syntastic.
<a name="faqxcrun"></a>
__4.15. Q. What happened to the `xcrun` checker?__
A. The `xcrun` checker used to have a security problem and it has been removed.
A better checker for __Swift__ is part of the [vim-swift][swift] plugin. If you
install this plugin the checker should be picked up automatically by syntastic.
<a name="otherresources"></a> <a name="otherresources"></a>
@ -517,8 +502,6 @@ a look at [ghcmod-vim][ghcmod], [jedi-vim][jedi], [python-mode][python_mode], [v
[rvm]: https://rvm.io/ [rvm]: https://rvm.io/
[stack_overflow]: http://stackoverflow.com/questions/tagged/syntastic [stack_overflow]: http://stackoverflow.com/questions/tagged/syntastic
[swift]: https://github.com/kballard/vim-swift [swift]: https://github.com/kballard/vim-swift
[tidy]: http://www.htacg.org/tidy-html5/
[tidy_old]: http://tidy.sourceforge.net/
[tsuquyomi]: https://github.com/Quramy/tsuquyomi/ [tsuquyomi]: https://github.com/Quramy/tsuquyomi/
[unimpaired]: https://github.com/tpope/vim-unimpaired [unimpaired]: https://github.com/tpope/vim-unimpaired
[vam]: https://github.com/MarcWeber/vim-addon-manager [vam]: https://github.com/MarcWeber/vim-addon-manager

2
plugin/syntastic.vim
View File

@ -19,7 +19,7 @@ if has('reltime')
lockvar! g:_SYNTASTIC_START lockvar! g:_SYNTASTIC_START
endif endif
let g:_SYNTASTIC_VERSION = '3.7.0-202' let g:_SYNTASTIC_VERSION = '3.7.0-203'
lockvar g:_SYNTASTIC_VERSION lockvar g:_SYNTASTIC_VERSION
" Sanity checks {{{1 " Sanity checks {{{1