Skip to content

Use list items for help option descriptions #12424

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
philderbeast wants to merge 7 commits into
base: master
Choose a base branch
from
+935 −426
Open

Use list items for help option descriptions #12424

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
71493fc
For test-show-details, list options
philderbeast Aug 6, 2026
99de0f4
Replace FILTER with values for test-show-details
philderbeast Aug 15, 2026
60ae9f0
Sublist for remote-build-reporting options
philderbeast Aug 15, 2026
3d05776
Indent help description list items
philderbeast Oct 8, 2026
950962a
Show help description list items
philderbeast Oct 8, 2026
2304dfb
Regenerate doc/cmd-*/*.txt
philderbeast Oct 8, 2026
6a6a8c6
Add changelog entry
philderbeast Oct 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 29 additions & 12 deletions Cabal/src/Distribution/GetOpt.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ module Distribution.GetOpt
import Distribution.Compat.Prelude
import Prelude ()

import Data.List (stripPrefix)

-- | What to do with options following non-options
data ArgOrder a
= -- | no option processing after first non-option
Expand Down Expand Up @@ -170,21 +172,36 @@ fmtLong (OptArg _ ad) lo =
let opt = "--" ++ lo
in opt ++ "[=" ++ ad ++ "]"

-- | Wrap text to the given width. Each line of the input is wrapped on its
-- own, so a description written with explicit line breaks, such as a list of
-- allowed values, keeps those breaks. A line that starts with a @- @ list
-- marker gets a hanging indent, so its continuation lines align with the text
-- after the marker.
wrapText :: Int -> String -> [String]
wrapText width = map unwords . wrap 0 [] . words
wrapText width = concatMap wrapLine . lines
where
wrap :: Int -> [String] -> [String] -> [[String]]
wrap 0 [] (w : ws)
| length w + 1 > width =
wrap (length w) [w] ws
wrap col line (w : ws)
| col + length w + 1 > width =
reverse line : wrap 0 [] (w : ws)
wrap col line (w : ws) =
wrapLine line = case stripPrefix listMarker line of
Just item ->
zipWith (++) (listMarker : repeat listIndent) (wrapWords (width - length listMarker) item)
Nothing -> wrapWords width line

listMarker = "- "
listIndent = map (const ' ') listMarker

wrapWords w = map unwords . wrap w 0 [] . words

wrap :: Int -> Int -> [String] -> [String] -> [[String]]
wrap width' 0 [] (w : ws)
| length w + 1 > width' =
wrap width' (length w) [w] ws
wrap width' col line (w : ws)
| col + length w + 1 > width' =
reverse line : wrap width' 0 [] (w : ws)
wrap width' col line (w : ws) =
let col' = col + length w + 1
in wrap col' (w : line) ws
wrap _ [] [] = []
wrap _ line [] = [reverse line]
in wrap width' col' (w : line) ws
wrap _ _ [] [] = []
wrap _ _ line [] = [reverse line]

-- |
-- Process the command-line, and return the list of values that matched
Expand Down
20 changes: 16 additions & 4 deletions Cabal/src/Distribution/Simple/Setup/Config.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -542,9 +542,7 @@ configureOptions showOrParseArgs =
, option
""
["profiling-detail"]
( "Profiling detail level for executable and library (default, "
++ "none, exported-functions, toplevel-functions, all-functions, late)."
)
("Profiling detail level for executable and library.\n" ++ profDetailLevelsHelp)
configProfDetail
(\v flags -> flags{configProfDetail = v})
( reqArg'
Expand All @@ -555,7 +553,7 @@ configureOptions showOrParseArgs =
, option
""
["library-profiling-detail"]
"Profiling detail level for libraries only."
("Profiling detail level for libraries only.\n" ++ profDetailLevelsHelp)
configProfLibDetail
(\v flags -> flags{configProfLibDetail = v})
( reqArg'
Expand Down Expand Up @@ -912,6 +910,20 @@ showProfDetailLevelFlag :: Flag ProfDetailLevel -> [String]
showProfDetailLevelFlag NoFlag = []
showProfDetailLevelFlag (Flag dl) = [showProfDetailLevel dl]

-- | Help text listing the known profiling detail levels, one per line with
-- any aliases, so that the option descriptions stay in step with
-- 'knownProfDetailLevels'.
profDetailLevelsHelp :: String
profDetailLevelsHelp =
unlines ("Allowed values:" : punctuate [item primary aliases | (primary, aliases, _) <- knownProfDetailLevels])
where
item primary [] = "- " ++ primary
item primary aliases = "- " ++ primary ++ " (or " ++ intercalate ", " aliases ++ ")"

punctuate [] = []
punctuate [x] = [x ++ "."]
punctuate (x : xs) = (x ++ ",") : punctuate xs

parsecPromisedComponent :: ParsecParser PromisedComponent
parsecPromisedComponent = do
pn <- parsec
Expand Down
15 changes: 9 additions & 6 deletions Cabal/src/Distribution/Simple/Setup/Test.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,16 +194,19 @@ testOptions' showOrParseArgs =
, option
[]
["show-details"]
( "'always': always show results of individual test cases. "
++ "'never': never show results of individual test cases. "
++ "'failures': show results of failing test cases. "
++ "'streaming': show results of test cases in real time."
++ "'direct': send results of test cases in real time; no log file."
( unlines
[ "Allowed values:"
, "- always: always show results of individual test cases,"
, "- never: never show results of individual test cases,"
, "- failures: show results of failing test cases,"
, "- streaming: show results of test cases in real time,"
, "- direct: send results of test cases in real time; no log file."
]
)
testShowDetails
(\v flags -> flags{testShowDetails = v})
( reqArg
"FILTER"
"always|never|failures|streaming|direct"
( parsecToReadE
( \_ ->
"--show-details flag expects one of "
Expand Down
46 changes: 32 additions & 14 deletions cabal-install/src/Distribution/Client/Setup.hs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -524,10 +524,10 @@ globalCommand commands =
, option
[]
["http-transport"]
"Set a transport for http(s) requests. Accepts 'curl', 'wget', 'powershell', and 'plain-http'. (default: 'curl')"
"Set a transport for http(s) requests (default: curl)."
globalHttpTransport
(\v flags -> flags{globalHttpTransport = v})
(reqArgFlag "HttpTransport")
(reqArgFlag "curl|wget|powershell|plain-http")
, option
[]
["store-dir", "storedir"]
Expand Down Expand Up @@ -1955,11 +1955,14 @@ getCommand =
, option
[]
["index-state"]
( "Use source package index state as it existed at a previous time. "
++ "Accepts unix-timestamps (e.g. '@1474732068'), ISO8601 UTC timestamps "
++ "(e.g. '2016-09-24T17:47:48Z'), or 'HEAD' (default: 'HEAD'). "
++ "This determines which package versions are available as well as "
++ ".cabal file revision is selected (unless --pristine is used)."
( unlines
[ "Use source package index state as it existed at a previous time. Accepts:"
, "- a unix timestamp, e.g. '@1474732068',"
, "- an ISO8601 UTC timestamp, e.g. '2016-09-24T17:47:48Z',"
, "- 'HEAD', the default."
, "This determines which package versions are available as well as "
++ ".cabal file revision is selected (unless --pristine is used)."
]
)
getIndexState
(\v flags -> flags{getIndexState = v})
Expand Down Expand Up @@ -2685,9 +2688,12 @@ installOptions showOrParseArgs =
, option
[]
["index-state"]
( "Use source package index state as it existed at a previous time. "
++ "Accepts unix-timestamps (e.g. '@1474732068'), ISO8601 UTC timestamps "
++ "(e.g. '2016-09-24T17:47:48Z'), or 'HEAD' (default: 'HEAD')."
( unlines
[ "Use source package index state as it existed at a previous time. Accepts:"
, "- a unix timestamp, e.g. '@1474732068',"
, "- an ISO8601 UTC timestamp, e.g. '2016-09-24T17:47:48Z',"
, "- 'HEAD', the default."
]
)
installIndexState
(\v flags -> flags{installIndexState = v})
Expand Down Expand Up @@ -2739,7 +2745,13 @@ installOptions showOrParseArgs =
, option
[]
["remote-build-reporting"]
"Generate build reports to send to a remote server (none, anonymous or detailed)."
( unlines
[ "Generate build reports to send to a remote server:"
, "- none: do not report,"
, "- anonymous: report without identifying information,"
, "- detailed: report with full details."
]
)
installBuildReports
(\v flags -> flags{installBuildReports = v})
( reqArg
Expand Down Expand Up @@ -3024,8 +3036,8 @@ initOptions _ =
[ option
['i']
["interactive"]
( "Interactive mode. Creates a prompt tree for project creation. \n"
++ "If -n/--non-interactive is issued, a simple project with inferred defaults \n"
( "Interactive mode. Creates a prompt tree for project creation. "
++ "If -n/--non-interactive is issued, a simple project with inferred defaults "
++ "is created. If --simple is issued, then sensible defaults will be chosen as well."
)
IT.interactive
Expand Down Expand Up @@ -3691,7 +3703,13 @@ optionSolverFlags
, option
[]
["prefer-version"]
"Select which version of a package that the solver should prefer. Oldest is useful to determine lower bounds in build-depends section. Latest will prefer the latest version. Installed-or-latest will prefer installed versions and the latest version otherwise."
( unlines
[ "Select which version of a package that the solver should prefer:"
, "- oldest: useful to determine lower bounds in the build-depends section,"
, "- latest: prefer the latest version,"
, "- installed-or-latest: prefer installed versions and the latest version otherwise."
]
)
getpo
setpo
( reqArg
Expand Down
18 changes: 18 additions & 0 deletions changelog.d/pr-12424.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
synopsis: Keep line breaks and indent list items in command help text
packages: [Cabal, cabal-install]
prs: 12424
issues: 12422
---

`Distribution.GetOpt.usageInfo` used to re-flow an option's description as a
single run of words, so a description written with explicit line breaks lost
them. It now wraps each line on its own, and a line that starts with a `- `
list marker gets a hanging indent, so its continuation lines align with the
text after the marker.

The descriptions of `--show-details`, `--remote-build-reporting`,
`--prefer-version`, `--index-state`, `--profiling-detail`,
`--library-profiling-detail` and `--http-transport` now list their allowed
values one per line, and the placeholders of `--show-details`,
`--remote-build-reporting` and `--http-transport` name those values.
17 changes: 15 additions & 2 deletions doc/cmd-v1-help/configure.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,10 +65,23 @@ Flags for v1-configure:
--disable-executable-profiling
# Disable Executable profiling (DEPRECATED)
--profiling-detail=level # Profiling detail level for executable and
library (default, none, exported-functions,
toplevel-functions, all-functions, late).
library.
Allowed values:
- default,
- none,
- exported-functions (or exported),
- toplevel-functions (or toplevel, top),
- all-functions (or all),
- late-toplevel (or late).
--library-profiling-detail=level
# Profiling detail level for libraries only.
Allowed values:
- default,
- none,
- exported-functions (or exported),
- toplevel-functions (or toplevel, top),
- all-functions (or all),
- late-toplevel (or late).
-O[n], --enable-optimization[=n]
# Build with optimization (n is 0--2, default is
1)
Expand Down
12 changes: 6 additions & 6 deletions doc/cmd-v1-help/freeze.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,12 +56,12 @@ Flags for v1-freeze:
section.
--prefer-version=oldest|latest|installed-or-latest
# Select which version of a package that the
solver should prefer. Oldest is useful to
determine lower bounds in build-depends
section. Latest will prefer the latest
version. Installed-or-latest will prefer
installed versions and the latest version
otherwise.
solver should prefer:
- oldest: useful to determine lower bounds in
the build-depends section,
- latest: prefer the latest version,
- installed-or-latest: prefer installed
versions and the latest version otherwise.
--shadow-installed-packages # If multiple package instances of the same
version are installed, treat all but one as
shadowed.
Expand Down
63 changes: 43 additions & 20 deletions doc/cmd-v1-help/install.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,10 +76,23 @@ Flags for v1-install:
--disable-executable-profiling
# Disable Executable profiling (DEPRECATED)
--profiling-detail=level # Profiling detail level for executable and
library (default, none, exported-functions,
toplevel-functions, all-functions, late).
library.
Allowed values:
- default,
- none,
- exported-functions (or exported),
- toplevel-functions (or toplevel, top),
- all-functions (or all),
- late-toplevel (or late).
--library-profiling-detail=level
# Profiling detail level for libraries only.
Allowed values:
- default,
- none,
- exported-functions (or exported),
- toplevel-functions (or toplevel, top),
- all-functions (or all),
- late-toplevel (or late).
-O[n], --enable-optimization[=n]
# Build with optimization (n is 0--2, default is
1)
Expand Down Expand Up @@ -251,12 +264,12 @@ Flags for v1-install:
section.
--prefer-version=oldest|latest|installed-or-latest
# Select which version of a package that the
solver should prefer. Oldest is useful to
determine lower bounds in build-depends
section. Latest will prefer the latest
version. Installed-or-latest will prefer
installed versions and the latest version
otherwise.
solver should prefer:
- oldest: useful to determine lower bounds in
the build-depends section,
- latest: prefer the latest version,
- installed-or-latest: prefer installed
versions and the latest version otherwise.
--shadow-installed-packages # If multiple package instances of the same
version are installed, treat all but one as
shadowed.
Expand All @@ -283,10 +296,11 @@ Flags for v1-install:
build the given packages
--dependencies-only # A synonym for --only-dependencies
--index-state=STATE # Use source package index state as it existed
at a previous time. Accepts unix-timestamps
(e.g. '@1474732068'), ISO8601 UTC timestamps
(e.g. '2016-09-24T17:47:48Z'), or 'HEAD'
(default: 'HEAD').
at a previous time. Accepts:
- a unix timestamp, e.g. '@1474732068',
- an ISO8601 UTC timestamp, e.g.
'2016-09-24T17:47:48Z',
- 'HEAD', the default.
--root-cmd=COMMAND # (No longer supported, do not use.)
--symlink-bindir=DIR # Add symlinks to installed executables into
this directory.
Expand All @@ -296,7 +310,11 @@ Flags for v1-install:
$pkgid, $compiler, $os, $arch)
--remote-build-reporting=LEVEL
# Generate build reports to send to a remote
server (none, anonymous or detailed).
server:
- none: do not report,
- anonymous: report without identifying
information,
- detailed: report with full details.
--report-planning-failure # Generate build reports when the dependency
solver fails. This is used by the Hackage
build bot.
Expand Down Expand Up @@ -344,13 +362,18 @@ Flags for v1-install:
--test-machine-log=TEMPLATE # Produce a machine-readable log file (name
template can use $pkgid, $compiler, $os,
$arch, $result)
--test-show-details=FILTER # 'always': always show results of individual
test cases. 'never': never show results of
individual test cases. 'failures': show
results of failing test cases. 'streaming':
show results of test cases in real
time.'direct': send results of test cases in
real time; no log file.
--test-show-details=always|never|failures|streaming|direct
# Allowed values:
- always: always show results of individual
test cases,
- never: never show results of individual test
cases,
- failures: show results of failing test
cases,
- streaming: show results of test cases in
real time,
- direct: send results of test cases in real
time; no log file.
--test-keep-tix-files # Keep .tix files for HPC between test runs
--test-wrapper=FILE # Run test through a wrapper.
--test-fail-when-no-test-suites
Expand Down
Loading
Loading