Fix #5322 Extend stack exec --help docs and consequent changes

Adds, to `stack exec --help`, `If the command is absent, the first of any arguments is taken as the command.`

Given that change, expands the meta variables to `COMMAND` (from `CMD`) and `ARGUMENT(S)` (from `ARG`). The `(S)` is used to indicate one or more arguments.

Changes the example from `stack exec -- ghc-pkg describe base` to `stack exec ghc-pkg -- describe base`, to follow the alternative actually presented by `stack exec --help`.

In addition, for consistency throughout:

- Changes, throughout, the meta variable of `--package` to `PACKAGE(S)` (from default `ARG`), to avoid confusion over different references to 'arguments'. Also changes `Additional packages` to `Additional package(s)` to indicate one or more packages.

- Makes consistent changes to `stack script --help`.

- Makes consistent changes to `stack build --help` in respect of the `--exec` option.

- Makes consistent changes to `stack hoogle --help`, which referred to `'stack exec' synatax`. Also, rather than cross-refer user to `stack exec`, refers to `the '-- ARGUMENT(S)' syntax` and conforms to the `stack exec --help` approach of giving an example also after `-- ARGUMENT(S)`.

Author: mpilgrem

src/Stack/Config.hs

@@ -53,7 +53,7 @@ import           Distribution.Version (simplifyVersionRange, mkVersion')
 import           GHC.Conc (getNumProcessors)
 import           Lens.Micro ((.~))
 import           Network.HTTP.StackClient (httpJSON, parseUrlThrow, getResponseBody)
-import           Options.Applicative (Parser, strOption, long, help)
+import           Options.Applicative (Parser, help, long, metavar, strOption)
 import           Path
 import           Path.Extra (toFilePathNoTrailingSep)
 import           Path.Find (findInParents)
@@ -944,7 +944,10 @@ getDefaultUserConfigPath stackRoot = do
     return path
 
 packagesParser :: Parser [String]
-packagesParser = many (strOption (long "package" <> help "Additional packages that must be installed"))
+packagesParser = many (strOption
+                   (long "package" <>
+                     metavar "PACKAGE(S)" <>
+                     help "Additional package(s) that must be installed"))
 
 defaultConfigYaml :: IsString s => s
 defaultConfigYaml =

src/Stack/Options/BuildParser.hs

@@ -76,8 +76,8 @@ buildOptsParser cmd =
          help "Watch all local files not taking targets into account") <*>
     many (cmdOption
              (long "exec" <>
-              metavar "CMD [ARGS]" <>
-              help "Command and arguments to run after a successful build")) <*>
+              metavar "COMMAND [ARGUMENT(S)]" <>
+              help "Command and argument(s) to run after a successful build")) <*>
     switch
         (long "only-configure" <>
          help

src/Stack/Options/ExecParser.hs

@@ -16,16 +16,16 @@ execOptsParser mcmd =
         <*> eoArgsParser
         <*> execOptsExtraParser
   where
-    eoCmdParser = ExecCmd <$> strArgument (metavar "CMD" <> completer projectExeCompleter)
+    eoCmdParser = ExecCmd <$> strArgument (metavar "COMMAND" <> completer projectExeCompleter)
     eoArgsParser = many (strArgument (metavar txt))
       where
         txt = case mcmd of
             Nothing -> normalTxt
             Just ExecCmd{} -> normalTxt
-            Just ExecRun -> "-- ARGS (e.g. stack run -- file.txt)"
-            Just ExecGhc -> "-- ARGS (e.g. stack runghc -- X.hs -o x)"
-            Just ExecRunGhc -> "-- ARGS (e.g. stack runghc -- X.hs)"
-        normalTxt = "-- ARGS (e.g. stack exec -- ghc-pkg describe base)"
+            Just ExecRun -> "-- ARGUMENT(S) (e.g. stack run -- file.txt)"
+            Just ExecGhc -> "-- ARGUMENT(S) (e.g. stack runghc -- X.hs -o x)"
+            Just ExecRunGhc -> "-- ARGUMENT(S) (e.g. stack runghc -- X.hs)"
+        normalTxt = "-- ARGUMENT(S) (e.g. stack exec ghc-pkg -- describe base)"
 
 evalOptsParser :: String -- ^ metavar
                -> Parser EvalOpts
@@ -59,7 +59,10 @@ execOptsExtraParser = ExecOptsExtra
         <*> pure True
 
     eoPackagesParser :: Parser [String]
-    eoPackagesParser = many (strOption (long "package" <> help "Additional packages that must be installed"))
+    eoPackagesParser = many
+                       (strOption (long "package"
+                                  <> help "Additional package(s) that must be installed"
+                                  <> metavar "PACKAGE(S)"))
 
     eoRtsOptionsParser :: Parser [String]
     eoRtsOptionsParser = concat <$> many (argsOption

src/Stack/Options/ScriptParser.hs

@@ -24,9 +24,12 @@ data ScriptExecute
 
 scriptOptsParser :: Parser ScriptOpts
 scriptOptsParser = ScriptOpts
-    <$> many (strOption (long "package" <> help "Additional packages that must be installed"))
+    <$> many (strOption
+          (long "package" <>
+            metavar "PACKAGE(S)" <>
+            help "Additional package(s) that must be installed"))
     <*> strArgument (metavar "FILE" <> completer (fileExtCompleter [".hs", ".lhs"]))
-    <*> many (strArgument (metavar "-- ARGS (e.g. stack script X.hs -- args to program)"))
+    <*> many (strArgument (metavar "-- ARGUMENT(S) (e.g. stack script X.hs -- argument(s) to program)"))
     <*> (flag' SECompile
             ( long "compile"
            <> help "Compile the script without optimization and run the executable"

src/main/Main.hs

@@ -277,11 +277,12 @@ commandLineHandler currentDir progName isInterpreter = complicatedOptions
                     execCmd
                     (execOptsParser $ Just ExecGhc)
         addCommand' "hoogle"
-                    ("Run hoogle, the Haskell API search engine. Use 'stack exec' syntax " ++
-                     "to pass Hoogle arguments, e.g. stack hoogle -- --count=20 or " ++
-                     "stack hoogle -- server --local")
+                    ("Run hoogle, the Haskell API search engine. Use the '-- ARGUMENT(S)' syntax " ++
+                     "to pass Hoogle arguments, e.g. stack hoogle -- --count=20, or " ++
+                     "stack hoogle -- server --local.")
                     hoogleCmd
-                    ((,,,) <$> many (strArgument (metavar "ARG"))
+                    ((,,,) <$> many (strArgument
+                                 (metavar "-- ARGUMENT(S) (e.g. stack hoogle -- server --local)"))
                           <*> boolFlags
                                   True
                                   "setup"
@@ -297,7 +298,7 @@ commandLineHandler currentDir progName isInterpreter = complicatedOptions
 
       -- These are the only commands allowed in interpreter mode as well
       addCommand' "exec"
-                  "Execute a command"
+                  "Execute a command. If the command is absent, the first of any arguments is taken as the command."
                   execCmd
                   (execOptsParser Nothing)
       addCommand' "run"