diff --git a/doc/syntastic.txt b/doc/syntastic.txt index b1cc5a95..5375db94 100644 --- a/doc/syntastic.txt +++ b/doc/syntastic.txt @@ -86,7 +86,7 @@ checker integrations, see the guide on the GitHub wiki: 1.1. Quick start *syntastic-quickstart* Syntastic comes preconfigured with a default list of enabled checkers per -filetype. This list is kept reasonably short to prevent slowing down Vim or +|filetype|. This list is kept reasonably short to prevent slowing down Vim or trying to use conflicting checkers. You can see the list of checkers available for the current filetype with the @@ -161,13 +161,13 @@ is derived from the |syntastic_stl_format| option. ------------------------------------------------------------------------------ 2.2. Error signs *syntastic-error-signs* -Syntastic uses the |:sign| commands to mark lines with errors and warnings in -the sign column. To enable this feature, use the |'syntastic_enable_signs'| -option. +Syntastic uses the |:sign| commands (provided that the |+signs| feature is +compiled in) to mark lines with errors and warnings in the sign column. To +enable this feature, use the |'syntastic_enable_signs'| option. -Signs are colored using the Error and Todo syntax highlight groups by default. -If you wish to customize the colors for the signs, you can use the following -groups: +Signs are colored using the Error and Todo syntax highlight groups by default +(see |group-name|). If you wish to customize the colors for the signs, you +can use the following groups: SyntasticErrorSign - For syntax errors, links to 'error' by default SyntasticWarningSign - For syntax warnings, links to 'todo' by default SyntasticStyleErrorSign - For style errors, links to 'SyntasticErrorSign' @@ -194,17 +194,13 @@ Example: > You can use the |:Errors| command to display the errors for the current buffer in the |location-list|. -Note that when you use |:Errors| the current location list is overwritten with -Syntastic's own location list. The location list is also overwritten when -|syntastic_auto_jump| is non-zero and the cursor has to jump to an issue. - By default syntastic doesn't fill the |location-list| with the errors found by the checkers, in order to reduce clashes with other plugins. Consequently, if -you run |:lopen| or |:lwindow| rather than |:Errors| to open the error window you -wouldn't see syntastic's list of errors. If you insist on using |:lopen| or -|:lwindow| you should either run |:SyntasticSetLoclist| after running the checks, -or set |syntastic_always_populate_loc_list| which tells syntastic to update the -|location-list| automatically. +you run |:lopen| or |:lwindow| rather than |:Errors| to open the error window +you wouldn't see syntastic's list of errors. If you insist on using |:lopen| +or |:lwindow| you should either run |:SyntasticSetLoclist| after running the +checks, or set |syntastic_always_populate_loc_list| which tells syntastic to +update the |location-list| automatically. ------------------------------------------------------------------------------ 2.4. Error highlighting *syntastic-highlighting* @@ -273,15 +269,15 @@ for more info. Manually cause a syntax check to be done. By default the checkers in the |'g:syntastic__checkers'| or |'b:syntastic_checkers'| lists are run, -cf. |syntastic-filetype-checkers|. If |syntastic_aggregate_errors| is unset +cf. |syntastic-filetype-checkers|. If |'syntastic_aggregate_errors'| is unset (which is the default), checking stops the first time a checker reports any -errors; if |syntastic_aggregate_errors| is set, all checkers that apply are run -in turn, and all errors found are aggregated in a single list. +errors; if |'syntastic_aggregate_errors'| is set, all checkers that apply are +run in turn, and all errors found are aggregated in a single list. The command may be followed by a (space separated) list of checkers. In this case |'g:syntastic__checkers'| and |'b:syntastic_checkers'| are ignored, and the checkers named by the command's arguments are run instead, in -the order specified. The rules of |syntastic_aggregate_errors| still apply. +the order specified. The set by |'syntastic_aggregate_errors'| still apply. Example: > :SyntasticCheck flake8 pylint @@ -301,7 +297,7 @@ Resets the list of errors and turns off all error notifiers. If |'syntastic_always_populate_loc_list'| is not set, the |location-list| is not filled in automatically with the list of errors detected by the checkers. This is useful if you run syntastic along with other plugins that use location -lists. The |:SyntasticSetLoclist| command allows you to stick the errors into +lists. The |:SyntasticSetLoclist| command allows you to stick the errors into the location list explicitly. ============================================================================== @@ -309,14 +305,14 @@ the location list explicitly. *'syntastic_check_on_open'* Default: 0 -If enabled, syntastic will do syntax checks when buffers are first loaded as -well as on saving > +If this variable is enabled, syntastic in active mode will run syntax checks +when buffers are first loaded, as well as on saving: > let g:syntastic_check_on_open = 1 < *'syntastic_check_on_wq'* Default: 1 In active mode syntax checks are normally run whenever buffers are written to -disk, even when the writes happen right before quitting Vim. If you want to +disk, even when the writes happen just before quitting Vim. If you want to skip checks when you issue |:wq|, |:x|, and |:ZZ|, set this variable to 0: > let g:syntastic_check_on_wq = 0 < @@ -331,36 +327,37 @@ time a checker finds any errors. > *'syntastic_id_checkers'* Default: 1 When results from multiple checkers are aggregated in a single error list -(that is either when |syntastic_aggregate_errors| is enabled, or when checking -a file with a composite filetype), it might not be immediately obvious which -checker has produced a given error message. This variable instructs syntastic -to label error messages with the names of the checkers that created them. > +(that is either when |'syntastic_aggregate_errors'| is enabled, or when +checking a file with a composite filetype), it might not be immediately +obvious which checker has produced a given error message. This variable +instructs syntastic to label error messages with the names of the checkers +that created them. > let g:syntastic_id_checkers = 0 < *'syntastic_sort_aggregated_errors'* Default: 1 By default, when results from multiple checkers are aggregated in a single -error list (that is either when |syntastic_aggregate_errors| is enabled, or -when checking a file with a composite filetype), errors are grouped by file, -then sorted by line number, then grouped by type (namely errors take precedence -over warnings), then they are sorted by column number. If you want to leave -messages grouped by checker output, set this variable to 0. > +error list (that is either when |'syntastic_aggregate_errors'| is enabled, +or when checking a file with a composite filetype), errors are grouped by +file, then sorted by line number, then grouped by type (namely errors take +precedence over warnings), then they are sorted by column number. If you want +to leave messages grouped by checker output, set this variable to 0: > let g:syntastic_sort_aggregated_errors = 0 < *'syntastic_echo_current_error'* Default: 1 If enabled, syntastic will echo current error to the command window. If -multiple errors are found on the same line, |syntastic_cursor_columns| is used -to decide which one is shown. > +multiple errors are found on the same line, |'syntastic_cursor_columns'| is +used to decide which one is shown. > let g:syntastic_echo_current_error = 1 < *'syntastic_cursor_columns'* Default: 1 This option controls which errors are echoed to the command window if -|syntastic_echo_current_error| is set and multiple errors are found on the same -line. When the option is enabled, the first error corresponding to the current -column is show. Otherwise, the first error on the current line is echoed, -regardless of the cursor position on the current line. +|'syntastic_echo_current_error'| is set and multiple errors are found on the +same line. When the option is enabled, the first error corresponding to the +current column is show. Otherwise, the first error on the current line is +echoed, regardless of the cursor position on the current line. When dealing with very large lists of errors, disabling this option can speed up navigation significantly: > @@ -401,10 +398,17 @@ errors (where possible). Highlighting can be turned off with the following > < *'syntastic_always_populate_loc_list'* Default: 0 -Enable this option to tell syntastic to always stick any detected errors into -the |location-list|: > +By default syntastic doesn't fill the |location-list| with the errors found +by the checkers, in order to reduce clashes with other plugins. Enable this +option to tell syntastic to always stick any detected errors into the +|location-list|: > let g:syntastic_always_populate_loc_list = 1 < +Please note that if |'syntastic_auto_jump'| is set to a non-zero value the +location list is overwritten with Syntastic's own list when taking a jump, +regardless of the value of |'syntastic_always_populate_loc_list'|. The +location list is also overwritten when running the |:Errors| command. + *'syntastic_auto_jump'* Default: 0 Enable this option if you want the cursor to jump to the first detected issue @@ -425,6 +429,10 @@ When set to 3 the cursor will jump to the first error detected, if any. If all issues detected are warnings, the cursor won't jump. > let g:syntastic_auto_jump = 3 < +Please note that in either situation taking the jump also has the side effect +of the location list being overwritten with Syntastic's own location list, +regardless of the value of |'syntastic_always_populate_loc_list'|. + *'syntastic_auto_loc_list'* Default: 2 Use this option to tell syntastic to automatically open and/or close the @@ -779,7 +787,7 @@ this variable, that takes precedence over it in the buffers where it is defined. For aggregated lists (see |syntastic-aggregating-errors|) these variables are -ignored if |syntastic_sort_aggregated_errors| is set (which is the default). +ignored if |'syntastic_sort_aggregated_errors'| is set (which is the default). ============================================================================== 6. Notes *syntastic-notes* @@ -791,7 +799,7 @@ Some Vim plugins use composite filetypes, such as "django.python" or "handlebars.html". Normally, syntastic deals with this situation by splitting the filetype in its simple components, and calling all checkers that apply. If this behaviour is not desirable, you can disable it by mapping the -composite filetypes to a simple ones using |syntastic_filetype_map|, e.g.: > +composite filetypes to a simple ones using |'syntastic_filetype_map'|, e.g.: > let g:syntastic_filetype_map = { "handlebars.html": "handlebars" } < ------------------------------------------------------------------------------ @@ -808,7 +816,7 @@ checkers, without any translation or conversion. The 'shellslash' option is relevant only on Windows systems. This option determines (among other things) the rules for quoting command lines, and there is no easy way for syntastic to make sure its state is appropriate for your -shell. It should be turned off if your 'shell' (or |g:syntastic_shell|) is +shell. It should be turned off if your 'shell' (or |'syntastic_shell'|) is "cmd.exe", and on for shells that expect an UNIX-like syntax, such as Cygwin's "sh". Most checkers will stop working if 'shellslash' is set to the wrong value. @@ -831,7 +839,7 @@ quickfix windows. The "csh" and "tcsh" shells are mostly compatible with syntastic. However, some checkers assume Bourne shell syntax for redirecting "stderr". For this -reason, you should point |g:syntastic_shell| to a Bourne-compatible shell, +reason, you should point |'syntastic_shell'| to a Bourne-compatible shell, such as "zsh", "bash", "ksh", or even the original Bourne "sh": > let g:syntastic_shell = "/bin/sh" < @@ -853,7 +861,7 @@ details. At the time of this writing the "fish" shell (see http://fishshell.com/) doesn't support the standard UNIX syntax for file redirections, and thus it -can't be used together with syntastic. You can however set |g:syntastic_shell| +can't be used together with syntastic. You can however set |'syntastic_shell'| to a more traditional shell, such as "zsh", "bash", "ksh", or even the original Bourne "sh": > let g:syntastic_shell = "/bin/sh" @@ -914,7 +922,7 @@ Syntastic can be used along with the "python-mode" Vim plugin (see https://github.com/klen/python-mode). However, they both run syntax checks by default when you save buffers to disk, and this is probably not what you want. To avoid both plugins opening error windows, you can either set passive mode -for python in syntastic (see |syntastic_mode_map|), or disable lint checks in +for python in syntastic (see |'syntastic_mode_map'|), or disable lint checks in "python-mode", by setting |pymode_lint_write| to 0. E.g.: > let g:pymode_lint_write = 0 < @@ -954,7 +962,7 @@ http://valloric.github.io/YouCompleteMe/). However, by default "YouCompleteMe" disables syntastic's checkers for the "c", "cpp", "objc", and "objcpp" filetypes, in order to allow its own checkers to run. If you want to use YCM's identifier completer but still run syntastic's checkers for those filetypes you -have to set |ycm_show_diagnostics_ui| to 0. E.g.: > +have to set |g:ycm_show_diagnostics_ui| to 0. E.g.: > let g:ycm_show_diagnostics_ui = 0 < ------------------------------------------------------------------------------ diff --git a/plugin/syntastic.vim b/plugin/syntastic.vim index e2c42288..4a2af0c2 100644 --- a/plugin/syntastic.vim +++ b/plugin/syntastic.vim @@ -19,7 +19,7 @@ if has('reltime') lockvar! g:_SYNTASTIC_START endif -let g:_SYNTASTIC_VERSION = '3.6.0-136' +let g:_SYNTASTIC_VERSION = '3.6.0-137' lockvar g:_SYNTASTIC_VERSION " Sanity checks {{{1