Commit b6f7d1a5 authored by Lennart Spitzner's avatar Lennart Spitzner

commandline-documentation: Add `notes` field to commands

- modify any existing commands appropriately
  (move certain contents from the commandDescription to commandNotes)
- modify the `commandHelp` function: reorder the help texts:
  synopsis - usage - description - flags - notes
parent 1ed5d26e
......@@ -80,6 +80,8 @@ data CommandUI flags = CommandUI {
commandUsage :: String -> String,
-- | Additional explanation of the command to use in help texts.
commandDescription :: Maybe (String -> String),
-- | Post-Usage notes and examples in help texts
commandNotes :: Maybe (String -> String),
-- | Initial \/ empty flags
commandDefaultFlags :: flags,
-- | All the Option fields for this command
......@@ -372,32 +374,43 @@ commandListOptions command =
-- | The help text for this command with descriptions of all the options.
commandHelp :: CommandUI flags -> String -> String
commandHelp command pname =
commandUsage command pname
++ (GetOpt.usageInfo ""
. addCommonFlags ShowArgs
$ commandGetOpts ShowArgs command)
++ case commandDescription command of
Nothing -> ""
Just desc -> '\n': desc pname
commandSynopsis command
++ "\n\n"
++ commandUsage command pname
++ ( case commandDescription command of
Nothing -> ""
Just desc -> '\n': desc pname)
++ "\n"
++ ( if cname == ""
then "Global flags:"
else "Flags for " ++ cname ++ ":" )
++ ( GetOpt.usageInfo ""
. addCommonFlags ShowArgs
$ commandGetOpts ShowArgs command )
++ ( case commandNotes command of
Nothing -> ""
Just notes -> '\n': notes pname)
where cname = commandName command
-- | Make a Command from standard 'GetOpt' options.
makeCommand :: String -- ^ name
-> String -- ^ short description
-> Maybe (String -> String) -- ^ long description
-> Maybe (String -> String) -- ^ description notes
-> flags -- ^ initial\/empty flags
-> (ShowOrParseArgs -> [OptionField flags]) -- ^ options
-> CommandUI flags
makeCommand name shortDesc longDesc defaultFlags options =
makeCommand name shortDesc longDesc notesDesc defaultFlags options =
CommandUI {
commandName = name,
commandSynopsis = shortDesc,
commandDescription = longDesc,
commandNotes = notesDesc,
commandUsage = usage,
commandDefaultFlags = defaultFlags,
commandOptions = options
}
where usage pname = "Usage: " ++ pname ++ " " ++ name ++ " [FLAGS]\n\n"
++ "Flags for " ++ name ++ ":"
where usage pname = "Usage: " ++ pname ++ " " ++ name ++ " [FLAGS]\n"
-- | Common flags that apply to every command
data CommonFlag = HelpFlag | ListOptionsFlag
......@@ -529,8 +542,7 @@ commandsRun globalCommand commands args =
"" -> ""
original -> original ++ "\n")
++ "Usage: " ++ pname ++ " COMMAND [FLAGS]\n"
++ " or: " ++ pname ++ " [GLOBAL FLAGS]\n\n"
++ "Global flags:",
++ " or: " ++ pname ++ " [GLOBAL FLAGS]\n",
commandDescription = Just $ \pname ->
"Commands:\n"
++ unlines [ " " ++ align name ++ " " ++ description
......@@ -562,11 +574,10 @@ commandsRun globalCommand commands args =
where globalHelp = commandHelp globalCommand'
helpCommandUI =
(makeCommand "help" "Help about commands." Nothing () (const [])) {
(makeCommand "help" "Help about commands." Nothing Nothing () (const [])) {
commandUsage = \pname ->
"Usage: " ++ pname ++ " help [FLAGS]\n"
++ " or: " ++ pname ++ " help COMMAND [FLAGS]\n\n"
++ "Flags for help:"
++ " or: " ++ pname ++ " help COMMAND [FLAGS]\n"
}
-- | Utility function, many commands do not accept additional flags. This
......
......@@ -217,6 +217,7 @@ globalCommand = CommandUI {
++ "Typical steps for installing Cabal packages:\n"
++ concat [ " " ++ pname ++ " " ++ x ++ "\n"
| x <- ["configure", "build", "install"]],
commandNotes = Nothing,
commandDefaultFlags = defaultGlobalFlags,
commandOptions = \_ ->
[option ['V'] ["version"]
......@@ -349,11 +350,12 @@ defaultConfigFlags progConf = emptyConfigFlags {
configureCommand :: ProgramConfiguration -> CommandUI ConfigFlags
configureCommand progConf = makeCommand name shortDesc
longDesc defaultFlags options
longDesc noteDesc defaultFlags options
where
name = "configure"
shortDesc = "Prepare to build the package."
longDesc = Just (\_ -> programFlagsDescription progConf)
longDesc = Nothing
noteDesc = Just (\_ -> programFlagsDescription progConf)
defaultFlags = defaultConfigFlags progConf
options showOrParseArgs =
configureOptions showOrParseArgs
......@@ -746,13 +748,15 @@ defaultCopyFlags = CopyFlags {
}
copyCommand :: CommandUI CopyFlags
copyCommand = makeCommand name shortDesc longDesc defaultCopyFlags options
copyCommand = makeCommand name shortDesc longDesc noteDesc
defaultCopyFlags options
where
name = "copy"
shortDesc = "Copy the files into the install locations."
longDesc = Just $ \_ ->
"Does not call register, and allows a prefix at install time\n"
++ "Without the --destdir flag, configure determines location.\n"
noteDesc = Nothing
options showOrParseArgs =
[optionVerbosity copyVerbosity (\v flags -> flags { copyVerbosity = v })
......@@ -807,7 +811,8 @@ defaultInstallFlags = InstallFlags {
}
installCommand :: CommandUI InstallFlags
installCommand = makeCommand name shortDesc longDesc defaultInstallFlags options
installCommand = makeCommand name shortDesc longDesc noteDesc
defaultInstallFlags options
where
name = "install"
shortDesc = "Copy the files into the install locations. Run register."
......@@ -815,6 +820,7 @@ installCommand = makeCommand name shortDesc longDesc defaultInstallFlags options
"Unlike the copy command, install calls the register command.\n"
++ "If you want to install into a location that is not what was\n"
++ "specified in the configure step, use the copy command.\n"
noteDesc = Nothing
options showOrParseArgs =
[optionVerbosity installVerbosity (\v flags -> flags { installVerbosity = v })
,optionDistPref
......@@ -883,11 +889,13 @@ defaultSDistFlags = SDistFlags {
}
sdistCommand :: CommandUI SDistFlags
sdistCommand = makeCommand name shortDesc longDesc defaultSDistFlags options
sdistCommand = makeCommand name shortDesc longDesc noteDesc
defaultSDistFlags options
where
name = "sdist"
shortDesc = "Generate a source distribution file (.tar.gz)."
longDesc = Nothing
noteDesc = Nothing
options showOrParseArgs =
[optionVerbosity sDistVerbosity (\v flags -> flags { sDistVerbosity = v })
,optionDistPref
......@@ -960,12 +968,13 @@ defaultRegisterFlags = RegisterFlags {
}
registerCommand :: CommandUI RegisterFlags
registerCommand = makeCommand name shortDesc longDesc
registerCommand = makeCommand name shortDesc longDesc noteDesc
defaultRegisterFlags options
where
name = "register"
shortDesc = "Register this package with the compiler."
longDesc = Nothing
noteDesc = Nothing
options showOrParseArgs =
[optionVerbosity regVerbosity (\v flags -> flags { regVerbosity = v })
,optionDistPref
......@@ -1002,11 +1011,12 @@ registerCommand = makeCommand name shortDesc longDesc
unregisterCommand :: CommandUI RegisterFlags
unregisterCommand = makeCommand name shortDesc
longDesc defaultRegisterFlags options
longDesc noteDesc defaultRegisterFlags options
where
name = "unregister"
shortDesc = "Unregister this package with the compiler."
longDesc = Nothing
noteDesc = Nothing
options showOrParseArgs =
[optionVerbosity regVerbosity (\v flags -> flags { regVerbosity = v })
,optionDistPref
......@@ -1097,12 +1107,13 @@ instance Monoid HscolourFlags where
where combine field = field a `mappend` field b
hscolourCommand :: CommandUI HscolourFlags
hscolourCommand = makeCommand name shortDesc longDesc
hscolourCommand = makeCommand name shortDesc longDesc noteDesc
defaultHscolourFlags options
where
name = "hscolour"
shortDesc = "Generate HsColour colourised code, in HTML format."
longDesc = Just (\_ -> "Requires hscolour.\n")
noteDesc = Nothing
options showOrParseArgs =
[optionVerbosity hscolourVerbosity
(\v flags -> flags { hscolourVerbosity = v })
......@@ -1186,11 +1197,12 @@ defaultHaddockFlags = HaddockFlags {
}
haddockCommand :: CommandUI HaddockFlags
haddockCommand = makeCommand name shortDesc longDesc defaultHaddockFlags options
haddockCommand = makeCommand name shortDesc longDesc noteDesc defaultHaddockFlags options
where
name = "haddock"
shortDesc = "Generate Haddock HTML documentation."
longDesc = Just $ \_ -> "Requires the program haddock, version 2.x.\n"
noteDesc = Nothing
options showOrParseArgs = haddockOptions showOrParseArgs
++ programConfigurationPaths progConf ParseArgs
haddockProgramPaths (\v flags -> flags { haddockProgramPaths = v})
......@@ -1344,11 +1356,13 @@ defaultCleanFlags = CleanFlags {
}
cleanCommand :: CommandUI CleanFlags
cleanCommand = makeCommand name shortDesc longDesc defaultCleanFlags options
cleanCommand = makeCommand name shortDesc longDesc noteDesc
defaultCleanFlags options
where
name = "clean"
shortDesc = "Clean up after a build."
longDesc = Just (\_ -> "Removes .hi, .o, preprocessed sources, etc.\n")
noteDesc = Nothing
options showOrParseArgs =
[optionVerbosity cleanVerbosity (\v flags -> flags { cleanVerbosity = v })
,optionDistPref
......@@ -1409,7 +1423,7 @@ defaultBuildFlags = BuildFlags {
buildCommand :: ProgramConfiguration -> CommandUI BuildFlags
buildCommand progConf =
makeCommand name shortDesc longDesc
makeCommand name shortDesc longDesc noteDesc
defaultBuildFlags
(\showOrParseArgs ->
[ optionVerbosity
......@@ -1422,7 +1436,8 @@ buildCommand progConf =
where
name = "build"
shortDesc = "Compile all targets or specific targets."
longDesc = Just $ \pname ->
longDesc = Nothing
noteDesc = Just $ \pname ->
"Examples:\n"
++ " " ++ pname ++ " build "
++ " All the components in the package\n"
......@@ -1520,7 +1535,8 @@ replCommand :: ProgramConfiguration -> CommandUI ReplFlags
replCommand progConf = CommandUI {
commandName = "repl",
commandSynopsis = "Open an interpreter session for the given target.",
commandDescription = Just $ \pname ->
commandDescription = Nothing,
commandNotes = Just $ \pname ->
"Examples:\n"
++ " " ++ pname ++ " repl "
++ " The first component in the package\n"
......@@ -1612,11 +1628,12 @@ defaultTestFlags = TestFlags {
}
testCommand :: CommandUI TestFlags
testCommand = makeCommand name shortDesc longDesc defaultTestFlags options
testCommand = makeCommand name shortDesc longDesc noteDesc defaultTestFlags options
where
name = "test"
shortDesc = "Run the test suite, if any (configure with UserHooks)."
longDesc = Nothing
noteDesc = Nothing
options showOrParseArgs =
[ optionVerbosity testVerbosity (\v flags -> flags { testVerbosity = v })
, optionDistPref
......@@ -1712,11 +1729,12 @@ defaultBenchmarkFlags = BenchmarkFlags {
benchmarkCommand :: CommandUI BenchmarkFlags
benchmarkCommand = makeCommand name shortDesc
longDesc defaultBenchmarkFlags options
longDesc noteDesc defaultBenchmarkFlags options
where
name = "bench"
shortDesc = "Run the benchmark, if any (configure with UserHooks)."
longDesc = Nothing
noteDesc = Nothing
options showOrParseArgs =
[ optionVerbosity benchmarkVerbosity
(\v flags -> flags { benchmarkVerbosity = v })
......
......@@ -153,6 +153,7 @@ globalCommand = CommandUI {
++ " " ++ pname ++ " install foo [--dry-run]\n\n"
++ "Occasionally you need to update the list of available packages:\n"
++ " " ++ pname ++ " update\n",
commandNotes = Nothing,
commandDefaultFlags = mempty,
commandOptions = \showOrParseArgs ->
(case showOrParseArgs of ShowArgs -> take 6; ParseArgs -> id)
......@@ -531,6 +532,7 @@ fetchCommand = CommandUI {
commandName = "fetch",
commandSynopsis = "Downloads packages for later installation.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = usagePackages "fetch",
commandDefaultFlags = defaultFetchFlags,
commandOptions = \ showOrParseArgs -> [
......@@ -604,6 +606,7 @@ freezeCommand = CommandUI {
commandName = "freeze",
commandSynopsis = "Freeze dependencies.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = usagePackages "freeze",
commandDefaultFlags = defaultFreezeFlags,
commandOptions = \ showOrParseArgs -> [
......@@ -645,6 +648,7 @@ updateCommand = CommandUI {
commandName = "update",
commandSynopsis = "Updates list of known packages.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = usageFlags "update",
commandDefaultFlags = toFlag normal,
commandOptions = \_ -> [optionVerbosity id const]
......@@ -676,6 +680,7 @@ checkCommand = CommandUI {
commandName = "check",
commandSynopsis = "Check the package for common mistakes.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = \pname -> "Usage: " ++ pname ++ " check\n",
commandDefaultFlags = toFlag normal,
commandOptions = \_ -> []
......@@ -686,6 +691,7 @@ formatCommand = CommandUI {
commandName = "format",
commandSynopsis = "Reformat the .cabal file using the standard style.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = \pname -> "Usage: " ++ pname ++ " format [FILE]\n",
commandDefaultFlags = toFlag normal,
commandOptions = \_ -> []
......@@ -696,10 +702,10 @@ runCommand = CommandUI {
commandName = "run",
commandSynopsis = "Runs the compiled executable.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage =
\pname -> "Usage: " ++ pname
++ " run [FLAGS] [EXECUTABLE] [-- EXECUTABLE_FLAGS]\n\n"
++ "Flags for run:",
++ " run [FLAGS] [EXECUTABLE] [-- EXECUTABLE_FLAGS]\n",
commandDefaultFlags = mempty,
commandOptions =
\showOrParseArgs -> liftOptions fst setFst
......@@ -735,10 +741,10 @@ reportCommand :: CommandUI ReportFlags
reportCommand = CommandUI {
commandName = "report",
commandSynopsis = "Upload build reports to a remote server.",
commandDescription = Just $ \_ ->
commandDescription = Nothing,
commandNotes = Just $ \_ ->
"You can store your Hackage login in the ~/.cabal/config file\n",
commandUsage = \pname -> "Usage: " ++ pname ++ " report [FLAGS]\n\n"
++ "Flags for upload:",
commandUsage = \pname -> "Usage: " ++ pname ++ " report [FLAGS]\n",
commandDefaultFlags = defaultReportFlags,
commandOptions = \_ ->
[optionVerbosity reportVerbosity (\v flags -> flags { reportVerbosity = v })
......@@ -798,6 +804,7 @@ getCommand = CommandUI {
++ "the source\ntarball and unpacks it in a local subdirectory. "
++ "Alternatively, with -s it will\nget the code from the source "
++ "repository specified by the package.\n",
commandNotes = Nothing,
commandUsage = usagePackages "get",
commandDefaultFlags = defaultGetFlags,
commandOptions = \_ -> [
......@@ -870,6 +877,7 @@ listCommand = CommandUI {
commandName = "list",
commandSynopsis = "List packages matching a search string.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = usageFlagsOrPackages "list",
commandDefaultFlags = defaultListFlags,
commandOptions = \_ -> [
......@@ -928,6 +936,7 @@ infoCommand = CommandUI {
commandName = "info",
commandSynopsis = "Display detailed information about a particular package.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = usagePackages "info",
commandDefaultFlags = defaultInfoFlags,
commandOptions = \_ -> [
......@@ -1049,11 +1058,11 @@ installCommand = CommandUI {
commandName = "install",
commandSynopsis = "Installs a list of packages.",
commandUsage = usageFlagsOrPackages "install",
commandDescription = Just $ \pname ->
let original = case commandDescription configureCommand of
Just desc -> desc pname ++ "\n"
Nothing -> ""
in original
commandDescription = Nothing,
commandNotes = Just $ \pname ->
( case commandNotes configureCommand of
Just desc -> desc pname ++ "\n"
Nothing -> "" )
++ "Examples:\n"
++ " " ++ pname ++ " install "
++ " Package in the current directory\n"
......@@ -1288,11 +1297,11 @@ uploadCommand :: CommandUI UploadFlags
uploadCommand = CommandUI {
commandName = "upload",
commandSynopsis = "Uploads source packages to Hackage.",
commandDescription = Just $ \_ ->
commandDescription = Nothing,
commandNotes = Just $ \_ ->
"You can store your Hackage login in the ~/.cabal/config file\n",
commandUsage = \pname ->
"Usage: " ++ pname ++ " upload [FLAGS] [TARFILES]\n\n"
++ "Flags for upload:",
"Usage: " ++ pname ++ " upload [FLAGS] [TARFILES]\n",
commandDefaultFlags = defaultUploadFlags,
commandOptions = \_ ->
[optionVerbosity uploadVerbosity (\v flags -> flags { uploadVerbosity = v })
......@@ -1354,9 +1363,9 @@ initCommand = CommandUI {
++ "arguments are provided for scripting purposes. "
++ "If you don't want interactive mode, be sure to pass "
++ "the -n flag.\n",
commandNotes = Nothing,
commandUsage = \pname ->
"Usage: " ++ pname ++ " init [FLAGS]\n\n"
++ "Flags for init:",
"Usage: " ++ pname ++ " init [FLAGS]\n",
commandDefaultFlags = defaultInitFlags,
commandOptions = \_ ->
[ option ['n'] ["non-interactive"]
......@@ -1585,9 +1594,9 @@ win32SelfUpgradeCommand = CommandUI {
commandName = "win32selfupgrade",
commandSynopsis = "Self-upgrade the executable on Windows",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = \pname ->
"Usage: " ++ pname ++ " win32selfupgrade PID PATH\n\n"
++ "Flags for win32selfupgrade:",
"Usage: " ++ pname ++ " win32selfupgrade PID PATH\n",
commandDefaultFlags = defaultWin32SelfUpgradeFlags,
commandOptions = \_ ->
[optionVerbosity win32SelfUpgradeVerbosity
......@@ -1630,13 +1639,13 @@ sandboxCommand = CommandUI {
commandName = "sandbox",
commandSynopsis = "Create/modify/delete a sandbox.",
commandDescription = Nothing,
commandNotes = Nothing,
commandUsage = \pname ->
"Usage: " ++ pname ++ " sandbox init\n"
++ " or: " ++ pname ++ " sandbox delete\n"
++ " or: " ++ pname ++ " sandbox add-source [PATHS]\n\n"
++ " or: " ++ pname ++ " sandbox hc-pkg -- [ARGS]\n"
++ " or: " ++ pname ++ " sandbox list-sources\n\n"
++ "Flags for sandbox:",
++ " or: " ++ pname ++ " sandbox list-sources\n",
commandDefaultFlags = defaultSandboxFlags,
commandOptions = \_ ->
......@@ -1685,15 +1694,16 @@ execCommand :: CommandUI ExecFlags
execCommand = CommandUI {
commandName = "exec",
commandSynopsis = "Execute a command in the context of the package",
commandDescription = Just $ \pname ->
commandDescription = Just $ \_ ->
"Execute the given command making the package's installed dependencies\n"
++ "available to GHC. When a sandbox is being used, this causes GHC to\n"
++ "use the sandbox package database as if it had been invoked directly\n"
++ "by cabal. If a sandbox is not being used, GHC is not affected.\n\n"
++ "Any cabal executable packages installed into either the user package\n"
++ "database or into the current package's sandbox (if there is a current\n"
++ "package and sandbox) are available on PATH.\n\n"
++ "Examples:\n"
++ "package and sandbox) are available on PATH.\n",
commandNotes = Just $ \pname ->
"Examples:\n"
++ " Install the executable package pandoc into a sandbox and run it:\n"
++ " " ++ pname ++ " sandbox init\n"
++ " " ++ pname ++ " install pandoc\n"
......@@ -1706,8 +1716,7 @@ execCommand = CommandUI {
++ " sandbox package database (if a sandbox is being used):\n"
++ " " ++ pname ++ " exec runghc Foo.hs\n",
commandUsage = \pname ->
"Usage: " ++ pname ++ " exec [FLAGS] COMMAND [-- [ARGS...]]\n\n"
++ "Flags for exec:",
"Usage: " ++ pname ++ " exec [FLAGS] COMMAND [-- [ARGS...]]\n",
commandDefaultFlags = defaultExecFlags,
commandOptions = \_ ->
......@@ -1753,6 +1762,7 @@ userConfigCommand = CommandUI {
++ "existing settings over the\ncurrent version of the default settings "
++ "and writes it back to ~/.cabal/config.\n",
commandNotes = Nothing,
commandUsage = \ pname ->
"Usage: " ++ pname ++ " user-config diff\n"
++ " " ++ pname ++ " user-config update\n",
......@@ -1828,18 +1838,15 @@ optionSolverFlags showOrParseArgs getmbj setmbj getrg setrg _getig _setig getsip
usageFlagsOrPackages :: String -> String -> String
usageFlagsOrPackages name pname =
"Usage: " ++ pname ++ " " ++ name ++ " [FLAGS]\n"
++ " or: " ++ pname ++ " " ++ name ++ " [PACKAGES]\n\n"
++ "Flags for " ++ name ++ ":"
++ " or: " ++ pname ++ " " ++ name ++ " [PACKAGES]\n"
usagePackages :: String -> String -> String
usagePackages name pname =
"Usage: " ++ pname ++ " " ++ name ++ " [PACKAGES]\n\n"
++ "Flags for " ++ name ++ ":"
"Usage: " ++ pname ++ " " ++ name ++ " [PACKAGES]\n"
usageFlags :: String -> String -> String
usageFlags name pname =
"Usage: " ++ pname ++ " " ++ name ++ " [FLAGS]\n\n"
++ "Flags for " ++ name ++ ":"
"Usage: " ++ pname ++ " " ++ name ++ " [FLAGS]\n"
--TODO: do we want to allow per-package flags?
parsePackageArgs :: [String] -> Either String [Dependency]
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment