cli: options help polish

extra/hledger-rewrite.hs

@@ -29,14 +29,14 @@ import Text.ParserCombinators.Parsec
 cmdmode :: Mode RawOpts
 cmdmode = (defCommandMode ["hledger-rewrite"]) {
    modeArgs = ([], Just $ argsFlag "[PATTERNS] --add-posting \"ACCT  AMTEXPR\" ...")
-  ,modeHelp = "show all journal entries, adding specified custom postings to matched ones"
+  ,modeHelp = "print all journal entries, with custom postings added to the matched ones"
   ,modeGroupFlags = Group {
      groupNamed = [("Input",     inputflags)
                   ,("Reporting", reportflags)
                   ,("Misc",      helpflags)
                  ]
-    ,groupUnnamed = [flagReq ["add-posting"] (\s opts -> Right $ setopt "add-posting" s opts) "\"ACCT  AMTEXPR\"" 
+    ,groupUnnamed = [flagReq ["add-posting"] (\s opts -> Right $ setopt "add-posting" s opts) "'ACCT  AMTEXPR'" 
-                     "add a posting to ACCT (can be parenthesised) with amount generated by an expression, which is: a literal amount, or * followed by a decimal multiplier (which multiplies the entry's first amount matched by PATTERNS). Two spaces are required between account and amount."]
+                     "add a posting to ACCT, which may be parenthesised. AMTEXPR is either a literal amount, or *N which means the transaction's first matched amount multiplied by N (a decimal number). Two spaces separate ACCT and AMTEXPR."]
     ,groupHidden = []
     }
   }

hledger-web/Hledger/Web/Options.hs

@@ -24,10 +24,10 @@ defbaseurlexample = (reverse $ drop 4 $ reverse $ defbaseurl defport) ++ "PORT"
 
 webflags :: [Flag [([Char], [Char])]]
 webflags = [
-  flagNone ["server"]   (setboolopt "server") ("log requests, don't browse or auto-exit")
+  flagNone ["server"]   (setboolopt "server") ("log requests, and don't browse or auto-exit")
- ,flagReq  ["port"]     (\s opts -> Right $ setopt "port" s opts) "PORT" ("listen on this tcp port (default: "++show defport++")")
+ ,flagReq  ["port"]     (\s opts -> Right $ setopt "port" s opts) "PORT" ("set the tcp port (default: "++show defport++")")
  ,flagReq  ["base-url"] (\s opts -> Right $ setopt "base-url" s opts) "BASEURL" ("set the base url (default: "++defbaseurlexample++")")
- ,flagReq  ["file-url"] (\s opts -> Right $ setopt "file-url" s opts) "FILEURL" ("set the url for static files (default: BASEURL/static)")
+ ,flagReq  ["file-url"] (\s opts -> Right $ setopt "file-url" s opts) "FILEURL" ("set the static files url (default: BASEURL/static)")
  ]
  
 webmode :: Mode [([Char], [Char])]

hledger/Hledger/Cli/Accounts.hs

@@ -30,13 +30,13 @@ import Hledger.Cli.Options
 accountsmode = (defCommandMode $ ["accounts"] ++ aliases) {
   modeHelp = "show account names" `withAliases` aliases
  ,modeHelpSuffix = [
-    "This command lists the accounts referenced by matched postings (and in tree mode, their parents as well). The accounts can be depth-clipped (--depth N or depth:N) or have their leading components dropped (--drop N)."
+    "This command lists the accounts referenced by matched postings (and in tree mode, their parents as well). The accounts can be depth-clipped (--depth N) or have their leading parts trimmed (--drop N)."
    ]
  ,modeGroupFlags = C.Group {
      groupUnnamed = [
-      flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default)"
+      flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree"
-     ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree"
+     ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default)"
-     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "in flat mode, omit this many leading account name components"
+     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"
      ]
     ,groupHidden = []
     ,groupNamed = [generalflagsgroup1]

hledger/Hledger/Cli/Balance.hs

@@ -263,14 +263,14 @@ balancemode = (defCommandMode $ ["balance"] ++ aliases) { -- also accept but don
   modeHelp = "show accounts and balances" `withAliases` aliases
  ,modeGroupFlags = C.Group {
      groupUnnamed = [
-      flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) "with a reporting interval, show accumulated totals starting from 0"
+      flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree (default in simple reports)"
-     ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) "with a reporting interval, show accurate historical ending balances"
+     ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list (default in multicolumn)"
-     ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default in multicolumn reports)"
+     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"
-     ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree (default in simple reports)"
+     ,flagReq  ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "tree mode: use this custom line format"
-     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "in flat mode, omit this many leading account name components"
+     ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "tree mode: don't squash boring parent accounts"
-     ,flagReq  ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "use this custom line format"
-     ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "no eliding at all, stronger than --empty"
      ,flagNone ["no-total"] (\opts -> setboolopt "no-total" opts) "don't show the final total"
+     ,flagNone ["cumulative"] (\opts -> setboolopt "cumulative" opts) "multicolumn mode: show accumulated ending balances"
+     ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) "multicolumn mode: show historical ending balances"
      ]
     ,groupHidden = []
     ,groupNamed = [generalflagsgroup1]

hledger/Hledger/Cli/Balancesheet.hs

@@ -26,8 +26,8 @@ balancesheetmode = (defCommandMode $ ["balancesheet"]++aliases) {
   modeHelp = "show a balance sheet" `withAliases` aliases
  ,modeGroupFlags = Group {
      groupUnnamed = [
-      flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, unindented"
+      flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list"
-     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "with --flat, omit this many leading account name components"
+     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"
      ]
     ,groupHidden = []
     ,groupNamed = [generalflagsgroup1]

hledger/Hledger/Cli/Cashflow.hs

@@ -29,8 +29,8 @@ cashflowmode = (defCommandMode ["cashflow","cf"]) {
   modeHelp = "show a cashflow statement" `withAliases` ["cf"]
  ,modeGroupFlags = Group {
      groupUnnamed = [
-      flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, unindented"
+      flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list"
-     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "with --flat, omit this many leading account name components"
+     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"
      ]
     ,groupHidden = []
     ,groupNamed = [generalflagsgroup1]

hledger/Hledger/Cli/Histogram.hs

@@ -21,8 +21,8 @@ import Hledger.Utils.UTF8IOCompat (putStr)
 
 
 activitymode = (defCommandMode $ ["activity"] ++ aliases) {
-  modeHelp = "show a barchart of transactions per interval" `withAliases` aliases
+  modeHelp = "show an ascii barchart of posting counts per interval (default: daily)" `withAliases` aliases
- ,modeHelpSuffix = ["The default interval is daily."]
+ ,modeHelpSuffix = []
  ,modeGroupFlags = Group {
      groupUnnamed = []
     ,groupHidden = []
@@ -57,6 +57,6 @@ showHistogram opts q j = concatMap (printDayWith countBar) spanps
           | queryEmpty q = id
           | otherwise = filter (not . isZeroMixedAmount . pamount)
 
-printDayWith f (DateSpan b _, ts) = printf "%s %s\n" (show $ fromJust b) (f ts)
+printDayWith f (DateSpan b _, ps) = printf "%s %s\n" (show $ fromJust b) (f ps)
 
 countBar ps = replicate (length ps) barchar

hledger/Hledger/Cli/Incomestatement.hs

@@ -26,8 +26,8 @@ incomestatementmode = (defCommandMode $ ["incomestatement"]++aliases) {
   modeHelp = "show an income statement" `withAliases` aliases
  ,modeGroupFlags = Group {
      groupUnnamed = [
-      flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, unindented"
+      flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list"
-     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "with --flat, omit this many leading account name components"
+     ,flagReq  ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts"
      ]
     ,groupHidden = []
     ,groupNamed = [generalflagsgroup1]

hledger/Hledger/Cli/Options.hs

@@ -79,38 +79,39 @@ import Hledger.Cli.Version
 -- | Common help flags: --help, --debug, --version...
 helpflags :: [Flag RawOpts]
 helpflags = [
-  flagNone ["help","h"] (setboolopt "help") "Display general help or (with --help after COMMAND) command help."
+  flagNone ["help","h"] (setboolopt "help") "show general help or (after command) command help"
  -- ,flagNone ["browse-args"] (setboolopt "browse-args") "use a web UI to select options and build up a command line"
- ,flagOpt "1" ["debug"] (\s opts -> Right $ setopt "debug" s opts) "N" "Show debug output (optional argument sets debug level)"
+ ,flagOpt "1" ["debug"] (\s opts -> Right $ setopt "debug" s opts) "N" "show debug output (increase N for more)"
- ,flagNone ["version"] (setboolopt "version") "Print version information"
+ ,flagNone ["version"] (setboolopt "version") "show version information"
  ]
 
 -- | Common input-related flags: --file, --rules-file, --alias...
 inputflags :: [Flag RawOpts]
 inputflags = [
-  flagReq ["file","f"]  (\s opts -> Right $ setopt "file" s opts) "FILE" "use a different journal file; - means stdin"
+  flagReq ["file","f"]  (\s opts -> Right $ setopt "file" s opts) "FILE" "use a different input file. For stdin, use -"
- ,flagReq ["rules-file"]  (\s opts -> Right $ setopt "rules-file" s opts) "FILE" "conversion rules for CSV (default: FILE.rules)"
+ ,flagReq ["rules-file"]  (\s opts -> Right $ setopt "rules-file" s opts) "RFILE" "CSV conversion rules file (default: FILE.rules)"
  ,flagReq ["alias"]  (\s opts -> Right $ setopt "alias" s opts)  "OLD=NEW" "display accounts named OLD as NEW"
  ]
 
 -- | Common report-related flags: --period, --cost, etc.
 reportflags :: [Flag RawOpts]
 reportflags = [
-  flagReq  ["begin","b"]     (\s opts -> Right $ setopt "begin" s opts) "DATE" "report on transactions on or after this date"
+  flagReq  ["begin","b"]     (\s opts -> Right $ setopt "begin" s opts) "DATE" "include postings/txns on or after this date"
- ,flagReq  ["end","e"]       (\s opts -> Right $ setopt "end" s opts) "DATE" "report on transactions before this date"
+ ,flagReq  ["end","e"]       (\s opts -> Right $ setopt "end" s opts) "DATE" "include postings/txns before this date"
- ,flagReq  ["period","p"]    (\s opts -> Right $ setopt "period" s opts) "PERIODEXP" "report on transactions during the specified period and/or with the specified reporting interval"
+ ,flagNone ["daily","D"]     (\opts -> setboolopt "daily" opts) "multiperiod/multicolumn report by day"
- ,flagNone ["daily","D"]     (\opts -> setboolopt "daily" opts) "report by day"
+ ,flagNone ["weekly","W"]    (\opts -> setboolopt "weekly" opts) "multiperiod/multicolumn report by week"
- ,flagNone ["weekly","W"]    (\opts -> setboolopt "weekly" opts) "report by week"
+ ,flagNone ["monthly","M"]   (\opts -> setboolopt "monthly" opts) "multiperiod/multicolumn report by month"
- ,flagNone ["monthly","M"]   (\opts -> setboolopt "monthly" opts) "report by month"
+ ,flagNone ["quarterly","Q"] (\opts -> setboolopt "quarterly" opts) "multiperiod/multicolumn report by quarter"
- ,flagNone ["quarterly","Q"] (\opts -> setboolopt "quarterly" opts) "report by quarter"
+ ,flagNone ["yearly","Y"]    (\opts -> setboolopt "yearly" opts) "multiperiod/multicolumn report by year"
- ,flagNone ["yearly","Y"]    (\opts -> setboolopt "yearly" opts) "report by year"
+ ,flagReq  ["period","p"]    (\s opts -> Right $ setopt "period" s opts) "PERIODEXP" "set start date, end date, and/or reporting interval all at once (overrides the flags above)"
- ,flagNone ["cleared","C"]   (\opts -> setboolopt "cleared" opts) "report only on cleared transactions"
+ ,flagNone ["date2","aux-date"] (\opts -> setboolopt "date2" opts) "use postings/txns' secondary dates instead"
- ,flagNone ["uncleared","U"] (\opts -> setboolopt "uncleared" opts) "report only on uncleared transactions"
+
- ,flagNone ["cost","B"]      (\opts -> setboolopt "cost" opts) "report cost of commodities"
+ ,flagNone ["cleared","C"]   (\opts -> setboolopt "cleared" opts) "include only cleared postings/txns"
- ,flagReq  ["depth"]         (\s opts -> Right $ setopt "depth" s opts) "N" "hide accounts/transactions deeper than this"
+ ,flagNone ["uncleared","U"] (\opts -> setboolopt "uncleared" opts) "include only uncleared postings/txns"
- ,flagNone ["date2","aux-date"] (\opts -> setboolopt "date2" opts) "use transactions' secondary dates, if any"
+ ,flagNone ["real","R"]      (\opts -> setboolopt "real" opts) "include only non-virtual postings"
- ,flagNone ["empty","E"]     (\opts -> setboolopt "empty" opts) "show empty/zero things which are normally elided"
+ ,flagReq  ["depth"]         (\s opts -> Right $ setopt "depth" s opts) "N" "hide accounts/postings deeper than N"
- ,flagNone ["real","R"]      (\opts -> setboolopt "real" opts) "report only on real (non-virtual) transactions"
+ ,flagNone ["empty","E"]     (\opts -> setboolopt "empty" opts) "show empty/zero things which are normally omitted"
+ ,flagNone ["cost","B"]      (\opts -> setboolopt "cost" opts) "show amounts in their cost price's commodity"
  ]
 
 argsFlag :: FlagHelp -> Arg RawOpts
@@ -139,7 +140,7 @@ defMode =   Mode {
  ,modeGroupFlags = Group {
      groupNamed = []
     ,groupUnnamed = [
-        flagNone ["help","h","?"] (setboolopt "help") "Display command help."
+        flagNone ["help","h","?"] (setboolopt "help") "Show command help."
         ]
     ,groupHidden = []
     }

hledger/Hledger/Cli/Register.hs

@@ -28,10 +28,10 @@ registermode = (defCommandMode $ ["register"] ++ aliases) {
   modeHelp = "show postings and running total" `withAliases` aliases
  ,modeGroupFlags = Group {
      groupUnnamed = [
-      flagOpt (show defaultWidthWithFlag) ["width","w"] (\s opts -> Right $ setopt "width" s opts) "N" "increase or set the output width (default: 80)"
+      flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) "include prior postings in the running total"
-     ,flagNone ["historical","H"] (\opts -> setboolopt "historical" opts) "include prior postings in the running total"
      ,flagNone ["average","A"] (\opts -> setboolopt "average" opts) "show a running average instead of the running total"
-     ,flagNone ["related","r"] (\opts -> setboolopt "related" opts) "show the sibling postings of those that would have been shown"
+     ,flagNone ["related","r"] (\opts -> setboolopt "related" opts) "show postings' siblings instead"
+     ,flagOpt (show defaultWidthWithFlag) ["width","w"] (\s opts -> Right $ setopt "width" s opts) "N" "set output width to 120, or N (default: 80)"
      ]
     ,groupHidden = []
     ,groupNamed = [generalflagsgroup1]

hledger/Hledger/Cli/Stats.hs

@@ -25,7 +25,7 @@ import Hledger.Utils.UTF8IOCompat (putStr)
 
 
 statsmode = (defCommandMode $ ["stats"] ++ aliases) {
-  modeHelp = "show quick journal statistics" `withAliases` aliases
+  modeHelp = "show some journal statistics" `withAliases` aliases
  ,modeGroupFlags = Group {
      groupUnnamed = []
     ,groupHidden = []