slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: flags/usage/manual cleanups

Browse Source
This commit is contained in:
Simon Michael 2017-03-29 14:20:30 -07:00
parent f4b3f1c094
commit 7df15a8279
8 changed files with 95 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/lib.m4
View File

@ -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

25
hledger-api/doc/hledger-api.1.m4.md
View File

@ -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_({{

2
hledger-api/hledger-api.hs
View File

@ -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

8
hledger-ui/doc/hledger-ui.1.m4.md
View 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.

8
hledger-web/doc/hledger-web.1.m4.md
View File

@ -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

12
hledger/Hledger/Cli/CliOptions.hs
View File

@ -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...

2
hledger/Hledger/Cli/Main.hs
View File

@ -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

74
hledger/doc/options.m4.md
View File

@ -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