doc: flags/usage/manual cleanups

doc/lib.m4

@@ -63,7 +63,7 @@ m4_define({{_rules_}},     {{```rules$1```}}          )m4_dnl
 m4_define({{_timeclock_}}, {{```timeclock$1```}}      )m4_dnl
 m4_define({{_timedot_}},   {{```timedot$1```}}        )m4_dnl
 m4_dnl
-m4_define({{_generaloptions_}}, {{
+m4_define({{_helpoptions_}}, {{
 
 `-h`
 : show general usage (or after COMMAND, the command's usage)
@@ -83,17 +83,27 @@ m4_define({{_generaloptions_}}, {{
 `--debug[=N]`
 : show debug output (levels 1-9, default: 1)
 
+}} )m4_dnl
+m4_dnl
+m4_define({{_inputoptions_}}, {{
+
 `-f FILE --file=FILE`
-: use a different input file. For stdin, use -
+: use a different input file. For stdin, use - (default: `$LEDGER_FILE` or `$HOME/.hledger.journal`)
 
 `--rules-file=RULESFILE`
 : Conversion rules file to use when reading CSV (default: FILE.rules)
 
 `--alias=OLD=NEW`
-: display accounts named OLD as NEW
+: rename accounts named OLD to NEW
+
+`--anon`
+: anonymize accounts and payees
+
+`--pivot TAGNAME`
+: use some other field/tag for account names
 
 `-I --ignore-assertions`
-: ignore any failing balance assertions in the journal
+: ignore any failing balance assertions
 
 }} )m4_dnl
 m4_dnl
@@ -152,11 +162,15 @@ m4_define({{_reportingoptions_}}, {{
 : convert amounts to their market value on the report end date
 (using the most recent applicable [market price](journal.html#market-prices), if any)
 
-`--pivot TAGNAME`
+}} )m4_dnl
-: organize reports by some tag's value instead of by account
+m4_dnl
+m4_define({{_generaloptions_}}, {{
 
-`--anon`
+_inputoptions_
-: show anonymized accounts and payees
+
+_reportingoptions_
+
+_helpoptions_
 
 }} )m4_dnl
 m4_dnl

hledger-api/doc/hledger-api.1.m4.md

@@ -15,7 +15,6 @@ hledger-api - web API server for the hledger accounting tool
 # SYNOPSIS
 
 `hledger-api [OPTIONS]`\
-`hledger-api --swagger`\
 `hledger api -- [OPTIONS]`
 
 # DESCRIPTION
@@ -43,18 +42,36 @@ the API docs will be printed in Swagger 2.0 format.
 
 Note: if invoking hledger-api as a hledger subcommand, write `--` before options as shown above.
 
+`-f --file=FILE`
+: use a different input file. For stdin, use - (default: `$LEDGER_FILE` or `$HOME/.hledger.journal`)
+
 `-d --static-dir=DIR`
 : serve files from a different directory (default: `.`)
 
+`--host=IPADDR`
+: listen on this IP address (default: 127.0.0.1)
+
 `-p --port=PORT`
-: use a different TCP port (default: 8001)
+: listen on this TCP port (default: 8001)
 
 `--swagger`
 : print API docs in Swagger 2.0 format, and exit
 
-hledger general options:
+`--version`
+: show version
+
+`-h`
+: show usage
+
+`--help`
+: show manual as plain text
+
+`--man`
+: show manual with man
+
+`--info`
+: show manual with info
 
-_generaloptions_
 
 _man_({{
 

hledger-api/hledger-api.hs

@@ -50,7 +50,7 @@ Usage:
   hledger-api --swagger
     print API docs in Swagger 2.0 format
   hledger-api --version
-  hledger-api -h|--help|--info
+  hledger-api -h|--help|--man|--info
 
 Options:
   -f --file FILE   use a different input file

hledger-ui/doc/hledger-ui.1.m4.md

@@ -69,14 +69,18 @@ Any QUERYARGS are interpreted as a hledger search query which filters the data.
 `--flat`
 : show full account names, unindented
 
-hledger general options:
+hledger input options:
 
-_generaloptions_
+_inputoptions_
 
 hledger reporting options:
 
 _reportingoptions_
 
+hledger help options:
+
+_helpoptions_
+
 # KEYS
 
 `?` shows a help dialog listing all keys. 

hledger-web/doc/hledger-web.1.m4.md

@@ -124,14 +124,18 @@ You would change this when sharing over the network, or integrating within a lar
 hledger-web normally serves static files itself, but if you wanted to
 serve them from another server for efficiency, you would set the url with this.
 
-hledger general options:
+hledger input options:
 
-_generaloptions_
+_inputoptions_
 
 hledger reporting options:
 
 _reportingoptions_
 
+hledger help options:
+
+_helpoptions_
+
 _man_({{
 
 # ENVIRONMENT

hledger/Hledger/Cli/CliOptions.hs

@@ -118,11 +118,12 @@ detailedversionflag = flagNone ["version+"] (setboolopt "version+") "show versio
 -- | 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 input file. For stdin, use -"
+  flagReq  ["file","f"]      (\s opts -> Right $ setopt "file" s opts) "FILE" "use a different input file. For stdin, use - (default: $LEDGER_FILE or $HOME/.hledger.journal)"
  ,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"
+ ,flagReq  ["alias"]         (\s opts -> Right $ setopt "alias" s opts)  "OLD=NEW" "rename accounts named OLD to NEW"
- ,flagNone ["ignore-assertions","I"] (setboolopt "ignore-assertions") "ignore any balance assertions in the journal"
+ ,flagNone ["anon"]          (setboolopt "anon") "anonymize accounts and payees"
- ,flagReq ["pivot"]  (\s opts -> Right $ setopt "pivot" s opts)  "TAGNAME" "organize reports by some tag's value, not by account"
+ ,flagReq  ["pivot"]         (\s opts -> Right $ setopt "pivot" s opts)  "TAGNAME" "use some other field/tag for account names"
+ ,flagNone ["ignore-assertions","I"] (setboolopt "ignore-assertions") "ignore any balance assertions"
  ]
 
 -- | Common report-related flags: --period, --cost, etc.
@@ -146,7 +147,6 @@ reportflags = [
  ,flagNone ["empty","E"]     (setboolopt "empty") "show items with zero amount, normally hidden"
  ,flagNone ["cost","B"]      (setboolopt "cost") "convert amounts to their cost at transaction time (using the transaction price, if any)"
  ,flagNone ["value","V"]     (setboolopt "value") "convert amounts to their market value on the report end date (using the most recent applicable market price, if any)"
- ,flagNone ["anon"]              (setboolopt "anon") "output ledger with anonymized accounts and payees."
  ]
 
 -- | Common output-related flags: --output-file, --output-format...

hledger/Hledger/Cli/Main.hs

@@ -127,7 +127,7 @@ mainmode addons = defMode {
 PROGNAME                         list commands
 PROGNAME CMD [--] [OPTS] [ARGS]  run a command (use -- with addon commands)
 PROGNAME-CMD [OPTS] [ARGS]       or run addon commands directly
-PROGNAME -h                      hledger usage
+PROGNAME -h                      general usage
 PROGNAME CMD -h                  command usage
 PROGNAME --help                  PROGNAME manual
 PROGNAME --man                   PROGNAME manual as man page

hledger/doc/options.m4.md

@@ -1,76 +1,66 @@
 # OPTIONS
 
-To see general usage and the command list: `hledger -h` or just `hledger`.
+To see general usage help, including general options 
-To see usage for a specific command: `hledger COMMAND -h`.
+which are supported by most hledger commands, run `hledger -h`.
+(Note -h and --help are different, like git.)
+These options can appear anywhere on the command line, and are listed below.
 
-hledger has several kinds of options:
+To see usage for a specific command, run: `hledger COMMAND -h`.
+Command-specific options must be written after the command name, eg: `hledger print -x`.
 
-- General options are always available and can appear anywhere on the command line.
+Additionally, if the command is an [add-on](#commands), 
-  `hledger -h` shows these. Eg: `hledger --version`.
+you may need to put its options after a double-hyphen, eg: `hledger ui -- --watch`.
+Or, you can run the add-on executable directly, eg: `hledger-ui --watch`.
 
-- Common reporting options are available with most commands. 
+Most commands also accept arguments, which are often 
-  These and all other non-general options must be written after COMMAND.
+a [query](#queries) filtering the data in some way. 
-  `hledger COMMAND -h` shows these. Eg: `hledger register --cleared`.
 
-- Command-specific options are also provided by some commands. 
+## Special characters
-  `hledger COMMAND -h` shows these too. Eg: `hledger register --average`.
 
-- Some hledger commands come from separate [add-on executables](#commands),
+Option and argument values which contain problematic characters
-  which have their own options. 
-  `hledger COMMAND -h` shows these, as usual. 
-  Such options, if not also supported by hledger, 
-  should be written following a double hyphen argument (`--`)
-  so that hledger's option parser does not complain.
-  Eg: `hledger ui -- --register=checking`.
-  Or, you can just run the add-on directly:
-  `hledger-ui --register=checking`.
-
-Command arguments may also follow the command name.
-In most cases these specify a [query](#queries) which filters the data. 
-Command options and arguments can be intermixed.
-
-Option and argument values containing problematic characters
 should be escaped with double quotes, backslashes, or (best) single quotes.
-This means spaces, but also characters which are significant to your 
+Problematic characters means spaces, and also characters which are significant to your 
 command shell, such as less-than/greater-than.
 Eg: `hledger register -p 'last year' "accounts receivable (receivable|payable)" amt:\>100`.
 
-Characters which are significant to the shell and also in 
+Characters which are significant both to the shell and in 
-[regular expressions](#regular-expressions), like parentheses, 
+[regular expressions](#regular-expressions) sometimes need to be double-escaped.
-the pipe symbol and the dollar sign, must sometimes be double-escaped.
+These include parentheses, the pipe symbol and the dollar sign.
-Eg, to match the dollar symbol: `hledger balance cur:'\$'` or 
+Eg, to match the dollar symbol, bash users should do: `hledger balance cur:'\$'` or 
 `hledger balance cur:\\$`.
 
-There's more.. options and arguments being passed by hledger to an
+There's more.. options and arguments get de-escaped when hledger 
-add-on executable get de-escaped once in the process. In this case you 
+is passing them to an addon executable. In this case you might need *triple*-escaping.
-might need triple-escaping.
 Eg: `hledger ui cur:'\\$'` or `hledger ui cur:\\\\$`.
 
 If in doubt, keep things simple:
 
+- run add-on executables directly
 - write options after the command
 - enclose problematic args in single quotes
 - if needed, also add a backslash to escape regexp metacharacters
-- run add-on executables directly
 
-If you're really curious, add `--debug=2` for troubleshooting.
+If you're really stumped, add `--debug=2` to troubleshoot.
 
 
 ## General options
 
-Always available, can be written before or after COMMAND. 
+### General help options
 
-_generaloptions_
+_helpoptions_
 
-## Reporting options
+### General input options
 
-Common reporting options, must be written after COMMAND.
+_inputoptions_
+
+### General reporting options
 
 _reportingoptions_
 
-If a reporting option occurs more than once on the command line, 
+Note when multiple similar reporting options are provided, the last one takes precedence.
-the last one takes precedence.
+Eg `-p feb -p mar` is equivalent to `-p mar`.
-Eg -p jan -p feb is equivalent to -p feb.
+
+Some of these can also be written as [queries](#queries).
 
 ## Input files