Manual: expand the section about checker options.

doc/syntastic.txt

@@ -746,53 +746,81 @@ takes precedence over both 'b:syntastic_<filetype>_<checker>_exec' and
 ------------------------------------------------------------------------------
 5.3 Configuring specific checkers                   *syntastic-config-makeprg*
 
-Most checkers use the 'makeprgBuild()' function and provide many options by
+Checkers are run by constructing a command line and passing it to a shell.
-default - in fact you can customise every part of the command that gets called.
+In most cases this command line is built using an internal function named
+'makeprgBuild()', which provides a number of options that allows you to
+customise every part of the command that gets called.
 
                                    *'syntastic_<filetype>_<checker>_<option>'*
-Checkers that use 'makeprgBuild()' construct a 'makeprg' like this: >
+Checkers that use 'makeprgBuild()' construct a command line like this: >
     let makeprg = self.makeprgBuild({
                 \ "exe": self.getExec(),
                 \ "args": "-a -b -c",
+                \ "fname: shellescape(expand('%', 1)),
                 \ "post_args": "--more --args",
                 \ "tail": "2>/dev/null" })
 <
-The result is a 'makeprg' of the form: >
+The result is a command line of the form: >
     <exe> <args> <fname> <post_args> <tail>
 <
 All arguments above are optional, and can be overridden by setting global
 variables 'g:syntastic_<filetype>_<checker-name>_<option-name>' - even
-parameters not specified in the call to makeprgBuild(). These variables also
+parameters not specified in the call to 'makeprgBuild()'. For example to
-have local versions 'b:syntastic_<filetype>_<checker-name>_<option-name>',
+override the args and the tail: >
-which take precedence over the global ones in the corresponding buffers.
+    let g:syntastic_c_pc_lint_args = "-w5 -Iz:/usr/include/linux"
-
+    let g:syntastic_c_pc_lint_tail = "2>/dev/null"
-If one of these variables has a non-empty default and you want it to be empty,
-you can set it to an empty string, e.g.: >
-    let g:syntastic_javascript_jslint_args = ""
 <
+These variables also have local versions named
+'b:syntastic_<filetype>_<checker-name>_<option-name>', which takes precedence
+over the global ones in the corresponding buffers.
+
+If any of the characters in the values of these variables have a special
+meaning for the shell in use (see |'shell'| and |'syntastic_shell'|) you need
+to escape them so that they can survive shell expansions. Vim function
+|shellescape()| can help you with that: >
+    let g:syntastic_c_cppcheck_args =
+        \ '-DBUILD_BASENAME=my-module ' . shellescape('-DBUILD_STR(s)=#s')
+<
+Alternatively, you can tell syntastic to escape special characters by turning
+the value into a list: >
+    let g:syntastic_c_cppcheck_args =
+        \ ['-DBUILD_BASENAME=my-module', '-DBUILD_STR(s)=#s']
+<
+Each element of the list will then be escaped as needed and turned into a
+separate shell argument.
+
+If one of the above variables has a non-empty default and you want it to be
+empty, you can set it to an empty string, e.g.: >
+    let g:syntastic_javascript_jslint_args = ""
+
+You can see the final outcome of setting these variables in the debug logs
+(cf. |syntastic-config-debug|).
+
                                         *'syntastic_<filetype>_<checker>_exe'*
-The 'exe' is normally the same as the 'exec' attribute described above, in
+The 'exe' option is special. Normally it is the same as the 'exec' attribute
-which case it may be omitted. However, you can use it to add environment
+described above, but you can use it to add environment variables to the
-variables, or to change the way the checker is run. For example this setup
+command line, or to change the way the checker is run. For example this setup
 allows you to run PC-Lint under Wine emulation on Linux: >
     let  g:syntastic_c_pc_lint_exec = "wine"
     let  g:syntastic_c_pc_lint_exe = "wine c:/path/to/lint-nt.exe"
 <
-To override the args and the tail: >
+                                      *'syntastic_<filetype>_<checker>_fname'*
-    let g:syntastic_c_pc_lint_args = "-w5 -Iz:/usr/include/linux"
+
-    let g:syntastic_c_pc_lint_tail = "2>/dev/null"
+The 'fname' option is also special. Normally it is automatically set by
-<
+syntastic to the name of the current file, but you can change that as needed.
-The general form of the override options is: >
+For example you can tell the SML/NJ compiler to use Compilation Manager by
-    syntastic_<filetype>_<checker>_<option-name>
+omitting the filename from the command line: >
+    let g:syntastic_sml_smlnj_fname = ""
 <
+                                            *syntastic-config-no-makeprgbuild*
 For checkers that do not use the 'makeprgBuild()' function you will have to
 look at the source code of the checker in question. If there are specific
-options that can be set, these are usually documented in the wiki:
+options that can be set, they are normally documented in the wiki:
 
     https://github.com/scrooloose/syntastic/wiki/Syntax-Checkers
 
                              *'syntastic_<filetype>_<checker>_quiet_messages'*
-In the same vein, 'g:syntastic_<filetype>_<checker-name>_quiet_messages' can
+Last but not least, 'g:syntastic_<filetype>_<checker-name>_quiet_messages' can
 be used to restrict message filters to messages produced by specific checkers.
 Example: >
     let g:syntastic_python_pylama_quiet_messages = {

plugin/syntastic.vim

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