Fix #1226 - Update the mcsc documentation to make it clearer how to use it

doc/ale-cs.txt

@@ -5,9 +5,9 @@ ALE C# Integration                                             *ale-cs-options*
 ===============================================================================
 mcs                                                                *ale-cs-mcs*
 
-  The mcs linter checks the syntax of the '*.cs' file loaded in the current
+  The `mcs` linter looks only for syntax errors while you type. See |ale-cs-mcsc|
-  buffer only. It uses the --parse option of the mcs compiler and implicitly 
+  for the separately configured linter for checking for semantic errors.
-  sets the -unsafe flag.
+
 
 g:ale_cs_mcs_options                                     *g:ale_cs_mcs_options*
                                                          *b:ale_cs_mcs_options*
@@ -25,49 +25,37 @@ g:ale_cs_mcs_options                                     *g:ale_cs_mcs_options*
 ===============================================================================
 mcsc                                                              *ale-cs-mcsc*
 
+  The mcsc linter checks for semantic errors when files are opened or saved
+  See |ale-lint-file-linters| for more information on linters which do not
+  check for problems while you type.
+
   The mcsc linter uses the mono mcs compiler to generate a temporary module
   target file (-t:module). The module includes including all '*.cs' files
   contained in the directory tree rooted at the path defined by the
   |g:ale_cs_mcsc_source| or |b:ale_cs_mcsc_source| variable.
   variable and all sub directories.
 
-  The paths to search for additional assembly ('*.dll') files can be
+  The paths to search for additional assembly files can be specified using the
-  specified using the |g:ale_cs_mcsc_assembly_path| or 
+  |g:ale_cs_mcsc_assembly_path| or |b:ale_cs_mcsc_assembly_path| variables.
-  |b:ale_cs_mcsc_assembly_path| variable. The additional assembly files ('*.dll')
+
-  can be included through the |g:ale_cs_mcsc_assemblies| or 
+  NOTE: ALE will not any errors in files apart from syntax errors if any one
-  |b:ale_cs_mcsc_assemblies| parameter. 
+  of the source files contains a syntax error. Syntax errors must be fixed
+  first before other errors will be shown.
 
-  NOTE: mcs compiles sources in multiple phases. It stops compilation after
-  finding errors during the current phase.
-  For example assume a file named 'FileWithTypeError.cs' is edited and saved
-  which contains a Type error. In the same directory tree a file named
-  'FileWithSyntaxError.cs' exists which contains a syntax error 
-  (eg.: a missing '{'). 
-  In that case mcs and thus mcsc linter will stop after the syntax check phase is
-  finished and report the syntax error in the file 'FileWithSyntaxError.cs'. The
-  Type error in the file 'FileWithTypeError.cs is not seen jet.
-  The only possibility to find the error in in 'FileWithTypeError.cs' is to fix
-  the syntax error in 'FileWithSyntaxError.cs' first. After saving mcs will
-  successfully pass the syntax check phase and advance to the next compilation
-  phase at which the Type error hidden in 'FileWithTypeError.cs' is found  and 
-  now can be indicated  by ale.
 
 g:ale_cs_mcsc_options                                   *g:ale_cs_mcsc_options*
                                                         *b:ale_cs_mcsc_options*
   Type: |String|
   Default: `''`
 
-  This parameter can be used to define additional flags and parameters independent
+  This option can be set to pass additional arguments to the `mcs` compiler.
-  of the source tree to be linted. The specified string is directly passed to
-  mcs compiler without any further change.
 
-  For example, to add the dotnet package which is not added per default
+  For example, to add the dotnet package which is not added per default: >
 
       let g:ale_cs_mcs_options = '-pkg:dotnet'
+<
+  NOTE: the `-unsafe` option is always passed to `mcs`.
 
-  NOTE: The mcs -unsafe option is included implicitly per default. Therefore it
-  is not necessary to specify it explicitly through the |g:ale_cs_mcsc_options|
-  or |b:ale_cs_mcsc_options| parameter.
 
 g:ale_cs_mcsc_source                                     *g:ale_cs_mcsc_source*
                                                          *b:ale_cs_mcsc_source*
@@ -80,14 +68,16 @@ g:ale_cs_mcsc_source                                     *g:ale_cs_mcsc_source*
   NOTE: Currently it is not possible to specify sub directories and
   directory sub trees which shall not be searched for *.cs files.
 
+
 g:ale_cs_mcsc_assembly_path                       *g:ale_cs_mcsc_assembly_path*
                                                   *b:ale_cs_mcsc_assembly_path*
   Type: |List|
   Default: `[]`
 
   This variable defines a list of path strings to be searched for external
-  assembly ('*.dll') files. The list is passed to the mcs compiler using the
+  assembly files. The list is passed to the mcs compiler using the `-lib:`
-  '-lib:' flag. 
+  flag.
+
 
 g:ale_cs_mcsc_assemblies                             *g:ale_cs_mcsc_assemblies*
                                                      *b:ale_cs_mcsc_assemblies*
@@ -96,7 +86,15 @@ g:ale_cs_mcsc_assemblies                             *g:ale_cs_mcsc_assemblies*
 
   This variable defines a list of external assembly (*.dll) files required
   by the mono mcs compiler to generate a valid module target. The list is
-  passed the mcs compiler using the '-r:' flag.
+  passed the mcs compiler using the `-r:` flag.
+
+  For example: >
+
+    " Compile C# programs with the Unity engine DLL file on Mac.
+    let g:ale_cs_mcss_assemblies = [
+    \ '/Applications/Unity/Unity.app/Contents/Frameworks/Managed/UnityEngine.dll',
+    \]
+<
 
 ===============================================================================
   vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl: