doc: flags/usage/manual cleanups
This commit is contained in:
Simon Michael
parent
f4b3f1c094
commit
7df15a8279
30
doc/lib.m4
30
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
|
||||
|
||||
@ -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_({{
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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"
|
||||
,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 ["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...
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user