imp:cli: make mutually exclusive flags clearer in --help

hledger-ui/Hledger/UI/UIOptions.hs

@@ -45,11 +45,11 @@ prognameandversion =
 uiflags = [
    flagNone ["watch","w"] (setboolopt "watch") "watch for data and date changes and reload automatically"
   ,flagReq  ["theme"] (\s opts -> Right $ setopt "theme" s opts) "THEME" ("use this custom display theme ("++intercalate ", " themeNames++")")
-  ,flagNone ["cash"] (setboolopt "cash") "start in the cash accounts screen"
+  ,flagNone ["cash"] (setboolopt "cash") "start in: the cash accounts screen"
-  ,flagNone ["bs"] (setboolopt "bs") "start in the balance sheet accounts screen"
+  ,flagNone ["bs"] (setboolopt "bs") "start in: the balance sheet accounts screen"
-  ,flagNone ["is"] (setboolopt "is") "start in the income statement accounts screen"
+  ,flagNone ["is"] (setboolopt "is") "start in: the income statement accounts screen"
-  ,flagNone ["all"] (setboolopt "all") "start in the all accounts screen"
+  ,flagNone ["all"] (setboolopt "all") "start in: the all accounts screen"
-  ,flagReq  ["register"] (\s opts -> Right $ setopt "register" s opts) "ACCTREGEX" "start in the (first matched) account's register"
+  ,flagReq  ["register"] (\s opts -> Right $ setopt "register" s opts) "ACCTREGEX" "start in: the (first matched) account's register"
   ,flagNone ["change"] (setboolopt "change")
     "show period balances (changes) at startup instead of historical balances"
   -- ,flagNone ["cumulative"] (setboolopt "cumulative")

hledger-web/Hledger/Web/WebOptions.hs

@@ -108,7 +108,7 @@ webflags =
       "run hledger-web's tests and exit. hspec test runner args may follow a --, eg: hledger-web --test -- --help"
   ]
   where
-    serveprefix = ""
+    serveprefix = "server mode: "
 
 webmode :: Mode RawOpts
 webmode =

hledger/Hledger/Cli/CliOptions.hs

@@ -183,11 +183,11 @@ reportflags = [
   -- report period, interval, dates
   flagReq  ["begin","b"]     (\s opts -> Right $ setopt "begin" s opts) "DATE" "include postings/transactions on/after this date"
  ,flagReq  ["end","e"]       (\s opts -> Right $ setopt "end" s opts) "DATE" "include postings/transactions before this date (with a report interval, will be adjusted to following subperiod end)"
- ,flagNone ["daily","D"]     (setboolopt "daily")     "multiperiod report with 1 day interval"
+ ,flagNone ["daily","D"]     (setboolopt "daily")     "set report interval: 1 day"
- ,flagNone ["weekly","W"]    (setboolopt "weekly")    "multiperiod report with 1 week interval"
+ ,flagNone ["weekly","W"]    (setboolopt "weekly")    "set report interval: 1 week"
- ,flagNone ["monthly","M"]   (setboolopt "monthly")   "multiperiod report with 1 month interval"
+ ,flagNone ["monthly","M"]   (setboolopt "monthly")   "set report interval: 1 month"
- ,flagNone ["quarterly","Q"] (setboolopt "quarterly") "multiperiod report with 1 quarter interval"
+ ,flagNone ["quarterly","Q"] (setboolopt "quarterly") "set report interval: 1 quarter"
- ,flagNone ["yearly","Y"]    (setboolopt "yearly")    "multiperiod report with 1 year interval"
+ ,flagNone ["yearly","Y"]    (setboolopt "yearly")    "set report interval: 1 year"
  ,flagReq  ["period","p"]    (\s opts -> Right $ setopt "period" s opts) "PERIODEXP" "set begin date, end date, and/or report interval, with more flexibility"
  ,flagReq  ["today"]         (\s opts -> Right $ setopt "today" s opts) "DATE" "override today's date (affects relative dates)"
  ,flagNone ["date2"]         (setboolopt "date2") "match/use secondary dates instead (deprecated)"  -- see also hiddenflags
@@ -257,11 +257,13 @@ terminalflags = [
 flattreeflags :: Bool -> [Flag RawOpts]
 flattreeflags showamounthelp = [
    flagNone ["flat","l"] (setboolopt "flat")
-     ("show accounts as a flat list (default)"
+     (prefix ++ "show accounts as a flat list (default)"
       ++ if showamounthelp then ". Amounts exclude subaccount amounts, except where the account is depth-clipped." else "")
   ,flagNone ["tree","t"] (setboolopt "tree")
-    ("show accounts as a tree" ++ if showamounthelp then ". Amounts include subaccount amounts." else "")
+    (prefix ++ "show accounts as a tree" ++ if showamounthelp then ". Amounts include subaccount amounts." else "")
   ]
+  where
+    prefix = "list/tree mode: "
 
 -- | hledger CLI's --conf/--no-conf flags.
 confflags = [

hledger/Hledger/Cli/Commands/Aregister.hs

@@ -49,9 +49,9 @@ aregistermode = hledgerCommandMode
      "filter strictly by transaction date, not posting date. Warning: this can show a wrong running balance."
   ,flagNone ["no-elide"] (setboolopt "no-elide") "don't show only 2 commodities per amount"
   ,flagNone ["cumulative"] (setboolopt "cumulative")
-     "show running total from report start date"
+     (accumprefix ++ "show running total from report start date")
   ,flagNone ["historical","H"] (setboolopt "historical")
-     "show historical running total/balance (includes postings before report start date) (default)"
+     (accumprefix ++ "show historical running total/balance (includes postings before report start date) (default)")
   -- ,flagNone ["average","A"] (setboolopt "average")
   --    "show running average of posting amounts instead of total (implies --empty)"
   -- ,flagNone ["related","r"] (setboolopt "related") "show postings' siblings instead"
@@ -74,6 +74,8 @@ aregistermode = hledgerCommandMode
   cligeneralflagsgroups1
   hiddenflags
   ([], Just $ argsFlag "ACCTPAT [QUERY]")
+  where
+    accumprefix = "accumulation mode: "
 
 -- based on Hledger.UI.RegisterScreen:
 

hledger/Hledger/Cli/Commands/Balance.hs

@@ -317,39 +317,40 @@ balancemode = hledgerCommandMode
   (
     -- https://hledger.org/dev/hledger.html#calculation-type :
     [flagNone ["sum"] (setboolopt "sum")
-      "show sum of posting amounts (default)"
+      (calcprefix ++ "show sum of posting amounts (default)")
     ,flagNone ["valuechange"] (setboolopt "valuechange")
-      "show total change of value of period-end historical balances (caused by deposits, withdrawals, market price fluctuations)"
+      (calcprefix ++ "show total change of value of period-end historical balances (caused by deposits, withdrawals, market price fluctuations)")
     ,flagNone ["gain"] (setboolopt "gain")
-      "show unrealised capital gain/loss (historical balance value minus cost basis)"
+      (calcprefix ++ "show unrealised capital gain/loss (historical balance value minus cost basis)")
     -- XXX --budget[=DESCPAT], --forecast[=PERIODEXP], could be more consistent
     ,flagOpt "" ["budget"] (\s opts -> Right $ setopt "budget" s opts) "DESCPAT"
       (unlines
-      [ "show sum of posting amounts together with budget goals defined by periodic"
+      [ calcprefix ++ "show sum of posting amounts together with budget goals defined by periodic"
       , "transactions. With a DESCPAT argument (must be separated by = not space),"
       , "use only periodic transactions with matching description"
       , "(case insensitive substring match)."
       ])
-    ,flagNone ["count"] (setboolopt "count") "show the count of postings"
+    ,flagNone ["count"] (setboolopt "count")
+      (calcprefix ++ "show the count of postings")
 
     -- https://hledger.org/dev/hledger.html#accumulation-type :
     ,flagNone ["change"] (setboolopt "change")
-      "accumulate amounts from column start to column end (in multicolumn reports, default)"
+      (accumprefix ++ "accumulate amounts from column start to column end (in multicolumn reports, default)")
     ,flagNone ["cumulative"] (setboolopt "cumulative")
-      "accumulate amounts from report start (specified by e.g. -b/--begin) to column end"
+      (accumprefix ++ "accumulate amounts from report start (specified by e.g. -b/--begin) to column end")
     ,flagNone ["historical","H"] (setboolopt "historical")
-      "accumulate amounts from journal start to column end (includes postings before report start date)"
+      (accumprefix ++ "accumulate amounts from journal start to column end (includes postings before report start date)")
     ]
 
     -- other options specific to this command:
     ++ flattreeflags True ++
-    [flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "omit N leading account name parts (in flat mode)"
+    [flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "in list mode, omit N leading account name parts"
     ,flagNone ["declared"] (setboolopt "declared") "include non-parent declared accounts (best used with -E)"
     ,flagNone ["average","A"] (setboolopt "average") "show a row average column (in multicolumn reports)"
     ,flagNone ["row-total","T"] (setboolopt "row-total") "show a row total column (in multicolumn reports)"
     ,flagNone ["summary-only"] (setboolopt "summary-only") "display only row summaries (e.g. row total, average) (in multicolumn reports)"
     ,flagNone ["no-total","N"] (setboolopt "no-total") "omit the final total row"
-    ,flagNone ["no-elide"] (setboolopt "no-elide") "don't squash boring parent accounts (in tree mode)"
+    ,flagNone ["no-elide"] (setboolopt "no-elide") "in tree mode, don't squash boring parent accounts"
     ,flagReq  ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)"
     ,flagNone ["sort-amount","S"] (setboolopt "sort-amount") "sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed."
     ,flagNone ["percent", "%"] (setboolopt "percent") "express values in percentage of each column's total"
@@ -379,6 +380,10 @@ balancemode = hledgerCommandMode
     ])
   ([], Just $ argsFlag "[QUERY]")
 
+  where
+    calcprefix = "calculation mode: "
+    accumprefix = "accumulation mode: "
+
 -- | The balance command, prints a balance report.
 balance :: CliOpts -> Journal -> IO ()
 balance opts@CliOpts{reportspec_=rspec} j = case balancecalc_ ropts of

hledger/Hledger/Cli/Commands/Register.hs

@@ -47,9 +47,9 @@ import qualified System.IO as IO
 registermode = hledgerCommandMode
   $(embedFileRelative "Hledger/Cli/Commands/Register.txt")
   ([flagNone ["cumulative"] (setboolopt "cumulative")
-     "show running total from report start date (default)"
+     (accumprefix ++ "show running total from report start date (default)")
   ,flagNone ["historical","H"] (setboolopt "historical")
-     "show historical running total/balance (includes postings before report start date)"
+     (accumprefix ++ "show historical running total/balance (includes postings before report start date)")
   ,flagNone ["average","A"] (setboolopt "average")
      "show running average of posting amounts instead of total (implies --empty)"
   ,let arg = "DESC" in
@@ -77,6 +77,8 @@ registermode = hledgerCommandMode
   cligeneralflagsgroups1
   hiddenflags
   ([], Just $ argsFlag "[QUERY]")
+  where
+    accumprefix = "accumulation mode: "
 
 -- | Print a (posting) register report.
 register :: CliOpts -> Journal -> IO ()

hledger/Hledger/Cli/CompoundBalanceCommand.hs

@@ -69,37 +69,36 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
   hledgerCommandMode
    cbcdoc
    -- keep roughly consistent order with Balance.hs. XXX refactor
-
+   (
-   ([flagNone ["sum"] (setboolopt "sum")
+    -- https://hledger.org/dev/hledger.html#calculation-type :
-      "show sum of posting amounts (default)"
+    [flagNone ["sum"] (setboolopt "sum")
-   ,flagNone ["valuechange"] (setboolopt "valuechange")
+      (calcprefix ++ "show sum of posting amounts (default)")
-      "show total change of period-end historical balance value (caused by deposits, withdrawals, market price fluctuations)"
+    ,flagNone ["valuechange"] (setboolopt "valuechange")
+      (calcprefix ++ "show total change of value of period-end historical balances (caused by deposits, withdrawals, market price fluctuations)")
     ,flagNone ["gain"] (setboolopt "gain")
-      "show unrealised capital gain/loss (historical balance value minus cost basis)"
+      (calcprefix ++ "show unrealised capital gain/loss (historical balance value minus cost basis)")
   -- currently not supported by compound balance commands:
   --  ,flagNone ["budget"] (setboolopt "budget")
-  --     "show sum of posting amounts compared to budget goals defined by periodic transactions"
+  --     (calcprefix ++ "show sum of posting amounts compared to budget goals defined by periodic transactions")
-   ,flagNone ["count"] (setboolopt "count") "show the count of postings"
+   ,flagNone ["count"] (setboolopt "count") (calcprefix ++ "show the count of postings")
 
+    -- https://hledger.org/dev/hledger.html#accumulation-type :
    ,flagNone ["change"] (setboolopt "change")
-       ("accumulate amounts from column start to column end (in multicolumn reports)"
+      (accumprefix ++ "accumulate amounts from column start to column end (in multicolumn reports)" ++ defaultMarker PerPeriod)
-           ++ defaultMarker PerPeriod)
     ,flagNone ["cumulative"] (setboolopt "cumulative")
-       ("accumulate amounts from report start (specified by e.g. -b/--begin) to column end"
+      (accumprefix ++ "accumulate amounts from report start (specified by e.g. -b/--begin) to column end" ++ defaultMarker Cumulative)
-           ++ defaultMarker Cumulative)
     ,flagNone ["historical","H"] (setboolopt "historical")
-       ("accumulate amounts from journal start to column end (includes postings before report start date)"
+      (accumprefix ++ "accumulate amounts from journal start to column end (includes postings before report start date)" ++ defaultMarker Historical)
-           ++ defaultMarker Historical)
     ]
 
     ++ flattreeflags True ++
-    [flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"
+    [flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "in list mode, omit N leading account name parts"
     ,flagNone ["declared"] (setboolopt "declared") "include non-parent declared accounts (best used with -E)"
     ,flagNone ["average","A"] (setboolopt "average") "show a row average column (in multicolumn reports)"
     ,flagNone ["row-total","T"] (setboolopt "row-total") "show a row total column (in multicolumn reports)"
     ,flagNone ["summary-only"] (setboolopt "summary-only") "display only row summaries (e.g. row total, average) (in multicolumn reports)"
     ,flagNone ["no-total","N"] (setboolopt "no-total") "omit the final total row"
-    ,flagNone ["no-elide"] (setboolopt "no-elide") "don't squash boring parent accounts (in tree mode)"
+    ,flagNone ["no-elide"] (setboolopt "no-elide") "in tree mode, don't squash boring parent accounts"
     ,flagReq  ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format (in simple reports)"
     ,flagNone ["sort-amount","S"] (setboolopt "sort-amount") "sort by amount instead of account code/name"
     ,flagNone ["percent", "%"] (setboolopt "percent") "express values in percentage of each column's total"
@@ -123,9 +122,11 @@ compoundBalanceCommandMode CompoundBalanceCommandSpec{..} =
       ])
     ([], Just $ argsFlag "[QUERY]")
  where
-   defaultMarker :: BalanceAccumulation -> String
+  calcprefix = "calculation mode: "
-   defaultMarker bacc | bacc == cbcaccum = " (default)"
+  accumprefix = "accumulation mode: "
-                      | otherwise        = ""
+  defaultMarker :: BalanceAccumulation -> String
+  defaultMarker bacc | bacc == cbcaccum = " (default)"
+                     | otherwise        = ""
 
 -- | Generate a runnable command from a compound balance command specification.
 compoundBalanceCommand :: CompoundBalanceCommandSpec -> (CliOpts -> Journal -> IO ())

hledger/hledger.m4.md

@@ -268,6 +268,7 @@ eg you can write `--tl` instead of `--tldr` or `--dry` instead of `--dry-run`.
 
 If the same option appears more than once in a command line, usually the last (right-most) wins.
 Similarly, if mutually exclusive flags are used together, the right-most wins.
+(When flags are mutually exclusive, they'll usually have a group prefix in --help.)
 
 With most commands, arguments are interpreted as a hledger [query](hledger.md#queries) which filter the data.
 Some queries can be expressed either with options or with arguments.