Merge pull request #2667 from mlaily/cli-doc

Try to clarify CLI --help

help/markdown/core-commandlineparsing.md

@@ -36,16 +36,18 @@ match DocoptResult.tryGetArgument "-m" results with
 | Some arg -> printfn "%s" arg
 ```
 
+*Note the following links are permalinks to old commits. They are intended only as examples. You are encouraged to look at the current version too, because it's likely to have been updated.*
+
 A more sophisticated example can be found in the fake runner: https://github.com/fsharp/FAKE/blob/64d871f5065412fe7b233025e454ccf3b89e46d7/src/app/Fake.netcore/Program.fs#L204-L259
 
 Or the target module:
 
-- https://github.com/fsharp/FAKE/blob/rc_1/src/app/Fake.Core.Target/Target.fs#L9-L26
+- https://github.com/fsharp/FAKE/blob/64d871f5065412fe7b233025e454ccf3b89e46d7/src/app/Fake.Core.Target/Target.fs#L9-L26
 - https://github.com/fsharp/FAKE/blob/64d871f5065412fe7b233025e454ccf3b89e46d7/src/app/Fake.Core.Target/Target.fs#L564-L619
 
 You can also take a look at the test-suite:
 
-- https://github.com/fsharp/FAKE/blob/rc_1/src/test/Fake.Core.CommandLine.UnitTests/Fake.Core.CommandLine.fs
+- https://github.com/fsharp/FAKE/blob/64d871f5065412fe7b233025e454ccf3b89e46d7/src/test/Fake.Core.CommandLine.UnitTests/Fake.Core.CommandLine.fs
 
 ## Differences to the python reference Docopt implementation
 

src/app/Fake.Core.Environment/Environment.fs

@@ -92,8 +92,10 @@ module Environment =
 
     /// Retrieves the environment variable with the given name or returns the default bool if no value was set
     let environVarAsBoolOrDefault varName defaultValue =
-        try  
-            (environVar varName).ToUpper() = "TRUE" 
+        try
+            match environVar varName with
+            | null -> defaultValue
+            | var -> var.ToUpper() = "TRUE"
         with
         | _ ->  defaultValue
 

src/app/Fake.Core.Target/Target.fs

@@ -17,10 +17,11 @@ Usage:
   fake-run --help | -h
   fake-run [target_opts] [target <target>] [--] [<targetargs>...]
 
-Target Module Options [target_opts]:
-    -t, --target <target>    Run the given target (ignored if positional argument 'target' is given)
+Target Module options [target_opts]:
+    -t, --target <target>    Run the given target (ignored if a target is already provided with '[target <target>]')
     -e, --environment-variable <keyval> [*]
-                             Set an environment variable. Use 'key=val'. Consider using regular arguments, see https://fake.build/core-targets.html
+                             Set an environment variable. Use 'key=val'.
+                             Consider using regular arguments, see https://fake.build/core-targets.html
     -s, --single-target      Run only the specified target.
     -p, --parallel <num>     Run parallel with the given number of tasks.
         """

src/app/Fake.netcore/Cli.fs

@@ -6,85 +6,101 @@ open System
 open Fake.Core.CommandLineParsing
 
 let fakeArgsHint =
-  """
-General:
-
-  The Fake command line is divided into runtime and script arguments.
-  Runtime arguments control compilation and processing of the script,
-  while script arguments are specific for the script or provided by
-  a NuGet package.
-  In most use cases you use the "Fake.Core.Target"-Package and therefore
-  inherit the corresponding command line interface. While these arguments
-  are not strictly part of the runtime we still show both below to
-  make it easier for newcomers.
-
- -- RUNTIME ARGUMENTS SECTION --
+  $"""
+{Fake.Runtime.Environment.fakeVersionStr}
 
 """
 
 let fakeUsage =
   """
 Usage:
-  fake.exe [fake_opts] run [run_opts] [<script.fsx>] [--] [<scriptargs>...]
-  fake.exe [fake_opts] build [build_opts] [--] [<scriptargs>...]
-  fake.exe --version
-  fake.exe --help | -h
-
-Fake Options [fake_opts]:
-  -v, --verbose [*]     Verbose (can be used multiple times)
-                        Is ignored if -s is used.
-                        * -v: Log verbose but only for FAKE
-                        * -vv: Log verbose for Paket as well
-  -s, --silent          Be silent, use this option if you need to pipe your output into another tool or need some additional processing.                  
-
-Fake Run Options [run_opts]:
-  -d, --debug           Debug the script.
-  -n, --nocache         Disable fake cache for this run.
+  fake [fake_opts] run [run_opts] [<script.fsx>] [--] [<scriptargs>...]
+  fake [fake_opts] build [build_opts] [--] [<scriptargs>...]
+  fake --version
+  fake --help | -h
+
+Note `fake build` is basically equivalent to calling `fake run` with a script named `build.fsx`.
+
+Fake options [fake_opts]:
+  -v, --verbose [*]        Verbose (can be used multiple times)
+                           Is ignored if -s is used.
+                           * -v: Log verbose but only for FAKE
+                           * -vv: Log verbose for Paket as well
+  -s, --silent             Be silent.
+                           Use this option if you need to pipe your output into another tool or need some additional processing.
+
+Fake Run options [run_opts]:
+  -d, --debug              Debug the script.
+  -n, --nocache            Disable Fake cache for this run.
   -p, --partial-restore
-                        Only restore the required group instead of a full restore, 
-                        can be set globally by setting the environment variable FAKE_PARTIAL_RESTORE to true.
-  --fsiargs <fsiargs> [*]  Arguments passed to the f# interactive.
+                           Only restore the required group instead of a full restore,
+                           can be set globally by setting the environment variable FAKE_PARTIAL_RESTORE to true.
+  --fsiargs <fsiargs> [*]  Arguments passed to the F# interactive.
 
-Fake Build Options [build_opts]:
-  -d, --debug           Debug the script.
-  -n, --nocache         Disable fake cache for this run.
+Fake Build options [build_opts]:
+  -d, --debug              Debug the script.
+  -n, --nocache            Disable Fake cache for this run.
   -p, --partial-restore
-                        Only restore the required group instead of a full restore, 
-                        can be set globally by setting the environment variable FAKE_PARTIAL_RESTORE to true.
-  --fsiargs <fsiargs> [*]  Arguments passed to the f# interactive.
+                           Only restore the required group instead of a full restore,
+                           can be set globally by setting the environment variable FAKE_PARTIAL_RESTORE to true.
+  --fsiargs <fsiargs> [*]  Arguments passed to the F# interactive.
   -f, --script <script.fsx>
-                        The script to execute (defaults to `build.fsx`).
+                           The script to execute (defaults to `build.fsx`).
 """
 
 let fakeAdditionalHelp =
   """
 
- -- SCRIPT ARGUMENTS SECTION --
+ ----- SCRIPT ARGUMENTS SECTION -----
+
+Remaining arguments following the previously defined options are provided to the script.
+
+Each script might understand different arguments,
+but since there are good chances you are using the 'Fake.Core.Target' package,
+its command-line is documented below.
+
+THIS SECTION ONLY APPLIES IF YOU USE THE 'Fake.Core.Target' PACKAGE IN YOUR SCRIPT!
 
-THIS SECTION ONLY APPLIES IF YOU USE THE 'Fake.Core.Target' PACKAGE!
 You can use the following arguments in place of `<scriptargs>`:
 
+(`fake-run` refers to the Fake command and arguments defined above)
+
 Usage:
   fake-run --list
   fake-run --write-info <file>
   fake-run --version
   fake-run --help | -h
   fake-run [target_opts] [target <target>] [--] [<targetargs>...]
 
-Target Module Options [target_opts]:
-    -t, --target <target>
-                          Run the given target (ignored if positional
-argument 'target' is given)
+Target Module options [target_opts]:
+    -t, --target <target>    Run the given target (ignored if a target is already provided with '[target <target>]')
     -e, --environment-variable <keyval> [*]
-                          Set an environment variable. Use 'key=val'.
-Consider using regular arguments, see https://fake.build/core-targets.html
-    -s, --single-target    Run only the specified target.
-    -p, --parallel <num>  Run parallel with the given number of tasks.
+                             Set an environment variable. Use 'key=val'.
+                             Consider using regular arguments, see https://fake.build/core-targets.html
+    -s, --single-target      Run only the specified target.
+    -p, --parallel <num>     Run parallel with the given number of tasks.
+
+ ----- END OF SCRIPT ARGUMENTS SECTION -----
+
+Warning:
+
+Ordering of arguments does MATTER.
+`fake -v run script.fsx` executes `script.fsx` in verbose mode.
+`fake run -v script.fsx` will try to execute a script named '-v' and fail.
+
+If a script argument/option conflicts with any of the options allowed before,
+you need to separate script options with `--`.
+The reverse is also true: to print all targets, you can use
+`fake build --list` instead of `fake build -- --list`
+because `--list` doesn't conflict with any of the [build_opts].
+
+Basic examples:
 
-Example:
+Specify script file and execute default script action:
+    fake run mybuildscript.fsx
 
-To use verbose mode (from [fake_opts]) and print all
-targets use "fake -v build -- --list". Because "--list" 
-doesn't conflict with any of the [build_opts], you can use 
-"fake -v build --list"
+Specify script file and run the Clean target:
+    fake run build.fsx --target Clean
+or shorter version using the default build.fsx script:
+    fake build -t Clean
 """

src/test/Fake.Core.IntegrationTests/SimpleHelloWorldTests.fs

@@ -88,7 +88,7 @@ let tests =
         let stdOut = String.Join("\n", result.Messages)
         let stdErr = String.Join("\n", result.Errors)
 
-        stdOut.Trim() |> Expect.stringContains "Hello FAKE exected" "Hello FAKE"
+        stdOut.Trim() |> Expect.stringContains "Hello FAKE expected" "Hello FAKE"
         stdErr.Trim() |> Expect.equal "empty expected" ""
 
     testCase "simple failed to compile" <| fun _ ->

src/test/Fake.Core.UnitTests/Fake.DotNet.Cli.fs

@@ -7,7 +7,7 @@ open Expecto
 [<Tests>]
 let tests =
     testList "Fake.DotNet.Cli.Tests" [
-        testCase "Test that we can use Process-Helpers on Cli Paramters" <| fun _ ->
+        testCase "Test that we can use Process-Helpers on Cli Parameters" <| fun _ ->
             let cli =
                 DotNet.Options.Create()
                 |> Process.setEnvironmentVariable "Somevar" "someval"
@@ -22,7 +22,7 @@ let tests =
 
             Expect.isEmpty cli "Empty push args."
 
-        testCase "Test that the dotnet nuget push arguments with all params setreturns correct string" <| fun _ ->
+        testCase "Test that the dotnet nuget push arguments with all params set returns correct string" <| fun _ ->
             let param =
                 { DotNet.NuGetPushOptions.Create().PushParams with
                     DisableBuffering = true