diff --git a/doc/lib.m4 b/doc/lib.m4 index 8c155d231..d32894fd9 100644 --- a/doc/lib.m4 +++ b/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` -: organize reports by some tag's value instead of by account +}} )m4_dnl +m4_dnl +m4_define({{_generaloptions_}}, {{ -`--anon` -: show anonymized accounts and payees +_inputoptions_ + +_reportingoptions_ + +_helpoptions_ }} )m4_dnl m4_dnl diff --git a/hledger-api/doc/hledger-api.1.m4.md b/hledger-api/doc/hledger-api.1.m4.md index 7c6032626..81c8e5ac7 100644 --- a/hledger-api/doc/hledger-api.1.m4.md +++ b/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_({{ diff --git a/hledger-api/hledger-api.hs b/hledger-api/hledger-api.hs index 31b48d158..0c4f06caf 100644 --- a/hledger-api/hledger-api.hs +++ b/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 diff --git a/hledger-ui/doc/hledger-ui.1.m4.md b/hledger-ui/doc/hledger-ui.1.m4.md index eae3905a3..e95aadc75 100644 --- a/hledger-ui/doc/hledger-ui.1.m4.md +++ b/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. diff --git a/hledger-web/doc/hledger-web.1.m4.md b/hledger-web/doc/hledger-web.1.m4.md index f4859c70d..1a444da8b 100644 --- a/hledger-web/doc/hledger-web.1.m4.md +++ b/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 diff --git a/hledger/Hledger/Cli/CliOptions.hs b/hledger/Hledger/Cli/CliOptions.hs index 70c7a9caa..a4173fabd 100644 --- a/hledger/Hledger/Cli/CliOptions.hs +++ b/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 ["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" - ,flagNone ["ignore-assertions","I"] (setboolopt "ignore-assertions") "ignore any balance assertions in the journal" - ,flagReq ["pivot"] (\s opts -> Right $ setopt "pivot" s opts) "TAGNAME" "organize reports by some tag's value, not by account" + 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" "rename accounts named OLD to NEW" + ,flagNone ["anon"] (setboolopt "anon") "anonymize accounts and payees" + ,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... diff --git a/hledger/Hledger/Cli/Main.hs b/hledger/Hledger/Cli/Main.hs index 14242388a..dc546e231 100644 --- a/hledger/Hledger/Cli/Main.hs +++ b/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 diff --git a/hledger/doc/options.m4.md b/hledger/doc/options.m4.md index 17bd681e4..a04c74aba 100644 --- a/hledger/doc/options.m4.md +++ b/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 usage for a specific command: `hledger COMMAND -h`. +To see general usage help, including general options +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. - `hledger -h` shows these. Eg: `hledger --version`. +Additionally, if the command is an [add-on](#commands), +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. - These and all other non-general options must be written after COMMAND. - `hledger COMMAND -h` shows these. Eg: `hledger register --cleared`. +Most commands also accept arguments, which are often +a [query](#queries) filtering the data in some way. -- Command-specific options are also provided by some commands. - `hledger COMMAND -h` shows these too. Eg: `hledger register --average`. +## Special characters -- Some hledger commands come from separate [add-on executables](#commands), - 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 +Option and argument values which contain 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 -[regular expressions](#regular-expressions), like parentheses, -the pipe symbol and the dollar sign, must sometimes be double-escaped. -Eg, to match the dollar symbol: `hledger balance cur:'\$'` or +Characters which are significant both to the shell and in +[regular expressions](#regular-expressions) sometimes need to be double-escaped. +These include parentheses, the pipe symbol and the dollar sign. +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 -add-on executable get de-escaped once in the process. In this case you -might need triple-escaping. +There's more.. options and arguments get de-escaped when hledger +is passing them to an addon executable. In this case you 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, -the last one takes precedence. -Eg -p jan -p feb is equivalent to -p feb. +Note when multiple similar reporting options are provided, the last one takes precedence. +Eg `-p feb -p mar` is equivalent to `-p mar`. + +Some of these can also be written as [queries](#queries). ## Input files