From e6a13393708ad1cfa8e1f472b3195b0b103b400e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 1 May 2014 07:22:44 -0700 Subject: [PATCH] cli: options help polish --- extra/hledger-rewrite.hs | 6 ++-- hledger-web/Hledger/Web/Options.hs | 6 ++-- hledger/Hledger/Cli/Accounts.hs | 8 ++--- hledger/Hledger/Cli/Balance.hs | 14 ++++----- hledger/Hledger/Cli/Balancesheet.hs | 4 +-- hledger/Hledger/Cli/Cashflow.hs | 4 +-- hledger/Hledger/Cli/Histogram.hs | 6 ++-- hledger/Hledger/Cli/Incomestatement.hs | 4 +-- hledger/Hledger/Cli/Options.hs | 43 +++++++++++++------------- hledger/Hledger/Cli/Register.hs | 6 ++-- hledger/Hledger/Cli/Stats.hs | 2 +- 11 files changed, 52 insertions(+), 51 deletions(-) diff --git a/extra/hledger-rewrite.hs b/extra/hledger-rewrite.hs index 0fdfe65fe..2d76737f4 100755 --- a/extra/hledger-rewrite.hs +++ b/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\"" - "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."] + ,groupUnnamed = [flagReq ["add-posting"] (\s opts -> Right $ setopt "add-posting" s opts) "'ACCT AMTEXPR'" + "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 = [] } } diff --git a/hledger-web/Hledger/Web/Options.hs b/hledger-web/Hledger/Web/Options.hs index a9d027aca..f4100aeb4 100644 --- a/hledger-web/Hledger/Web/Options.hs +++ b/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") - ,flagReq ["port"] (\s opts -> Right $ setopt "port" s opts) "PORT" ("listen on this tcp port (default: "++show defport++")") + flagNone ["server"] (setboolopt "server") ("log requests, and don't browse or auto-exit") + ,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])] diff --git a/hledger/Hledger/Cli/Accounts.hs b/hledger/Hledger/Cli/Accounts.hs index 6a252171b..134ae7189 100644 --- a/hledger/Hledger/Cli/Accounts.hs +++ b/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" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "in flat mode, omit this many leading account name components" + 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" "flat mode: omit N leading account name parts" ] ,groupHidden = [] ,groupNamed = [generalflagsgroup1] diff --git a/hledger/Hledger/Cli/Balance.hs b/hledger/Hledger/Cli/Balance.hs index 65465c3b7..9211577d2 100644 --- a/hledger/Hledger/Cli/Balance.hs +++ b/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 ["historical","H"] (\opts -> setboolopt "historical" opts) "with a reporting interval, show accurate historical ending balances" - ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default in multicolumn reports)" - ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree (default in simple reports)" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "in flat mode, omit this many leading account name components" - ,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 ["tree"] (\opts -> setboolopt "tree" opts) "show accounts as a tree (default in simple reports)" + ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list (default in multicolumn)" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" + ,flagReq ["format"] (\s opts -> Right $ setopt "format" s opts) "FORMATSTR" "tree mode: use this custom line format" + ,flagNone ["no-elide"] (\opts -> setboolopt "no-elide" opts) "tree mode: don't squash boring parent accounts" ,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] diff --git a/hledger/Hledger/Cli/Balancesheet.hs b/hledger/Hledger/Cli/Balancesheet.hs index abbe86fc7..87aaf8c2c 100644 --- a/hledger/Hledger/Cli/Balancesheet.hs +++ b/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" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "with --flat, omit this many leading account name components" + flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" ] ,groupHidden = [] ,groupNamed = [generalflagsgroup1] diff --git a/hledger/Hledger/Cli/Cashflow.hs b/hledger/Hledger/Cli/Cashflow.hs index 137a06267..93cbcd97f 100644 --- a/hledger/Hledger/Cli/Cashflow.hs +++ b/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" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "with --flat, omit this many leading account name components" + flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" ] ,groupHidden = [] ,groupNamed = [generalflagsgroup1] diff --git a/hledger/Hledger/Cli/Histogram.hs b/hledger/Hledger/Cli/Histogram.hs index aaa63cf0b..af88305b5 100644 --- a/hledger/Hledger/Cli/Histogram.hs +++ b/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 - ,modeHelpSuffix = ["The default interval is daily."] + modeHelp = "show an ascii barchart of posting counts per interval (default: daily)" `withAliases` aliases + ,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 diff --git a/hledger/Hledger/Cli/Incomestatement.hs b/hledger/Hledger/Cli/Incomestatement.hs index e86a9a3fb..1cc81164e 100644 --- a/hledger/Hledger/Cli/Incomestatement.hs +++ b/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" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "with --flat, omit this many leading account name components" + flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show accounts as a list" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" ] ,groupHidden = [] ,groupNamed = [generalflagsgroup1] diff --git a/hledger/Hledger/Cli/Options.hs b/hledger/Hledger/Cli/Options.hs index 5f88b603d..8ebc10791 100644 --- a/hledger/Hledger/Cli/Options.hs +++ b/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)" - ,flagNone ["version"] (setboolopt "version") "Print version information" + ,flagOpt "1" ["debug"] (\s opts -> Right $ setopt "debug" s opts) "N" "show debug output (increase N for more)" + ,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 ["rules-file"] (\s opts -> Right $ setopt "rules-file" s opts) "FILE" "conversion rules for CSV (default: FILE.rules)" + 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) "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 ["end","e"] (\s opts -> Right $ setopt "end" s opts) "DATE" "report on transactions 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) "report by day" - ,flagNone ["weekly","W"] (\opts -> setboolopt "weekly" opts) "report by week" - ,flagNone ["monthly","M"] (\opts -> setboolopt "monthly" opts) "report by month" - ,flagNone ["quarterly","Q"] (\opts -> setboolopt "quarterly" opts) "report by quarter" - ,flagNone ["yearly","Y"] (\opts -> setboolopt "yearly" opts) "report by year" - ,flagNone ["cleared","C"] (\opts -> setboolopt "cleared" opts) "report only on cleared transactions" - ,flagNone ["uncleared","U"] (\opts -> setboolopt "uncleared" opts) "report only on uncleared transactions" - ,flagNone ["cost","B"] (\opts -> setboolopt "cost" opts) "report cost of commodities" - ,flagReq ["depth"] (\s opts -> Right $ setopt "depth" s opts) "N" "hide accounts/transactions deeper than this" - ,flagNone ["date2","aux-date"] (\opts -> setboolopt "date2" opts) "use transactions' secondary dates, if any" - ,flagNone ["empty","E"] (\opts -> setboolopt "empty" opts) "show empty/zero things which are normally elided" - ,flagNone ["real","R"] (\opts -> setboolopt "real" opts) "report only on real (non-virtual) transactions" + 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" "include postings/txns before this date" + ,flagNone ["daily","D"] (\opts -> setboolopt "daily" opts) "multiperiod/multicolumn report by day" + ,flagNone ["weekly","W"] (\opts -> setboolopt "weekly" opts) "multiperiod/multicolumn report by week" + ,flagNone ["monthly","M"] (\opts -> setboolopt "monthly" opts) "multiperiod/multicolumn report by month" + ,flagNone ["quarterly","Q"] (\opts -> setboolopt "quarterly" opts) "multiperiod/multicolumn report by quarter" + ,flagNone ["yearly","Y"] (\opts -> setboolopt "yearly" opts) "multiperiod/multicolumn 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 ["date2","aux-date"] (\opts -> setboolopt "date2" opts) "use postings/txns' secondary dates instead" + + ,flagNone ["cleared","C"] (\opts -> setboolopt "cleared" opts) "include only cleared postings/txns" + ,flagNone ["uncleared","U"] (\opts -> setboolopt "uncleared" opts) "include only uncleared postings/txns" + ,flagNone ["real","R"] (\opts -> setboolopt "real" opts) "include only non-virtual postings" + ,flagReq ["depth"] (\s opts -> Right $ setopt "depth" s opts) "N" "hide accounts/postings deeper than N" + ,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 = [] } diff --git a/hledger/Hledger/Cli/Register.hs b/hledger/Hledger/Cli/Register.hs index 2ccb7cce6..5e460cb84 100644 --- a/hledger/Hledger/Cli/Register.hs +++ b/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] diff --git a/hledger/Hledger/Cli/Stats.hs b/hledger/Hledger/Cli/Stats.hs index 7f523fcfc..74e275292 100644 --- a/hledger/Hledger/Cli/Stats.hs +++ b/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 = []