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

doc: cli: rewrite options description

Browse Source
This commit is contained in:
Simon Michael 2016-06-11 21:33:56 -07:00
parent 060e89d3ee
commit f2cdceb28e
3 changed files with 257 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
hledger/doc/hledger.1
View File

@ -171,31 +171,74 @@ $\ hledger\ bal\ \-\-pivot\ member
.SH OPTIONS .SH OPTIONS
.PP .PP
To see general usage and the command list: \f[C]hledger\ \-h\f[] or just To see general usage and the command list: \f[C]hledger\ \-h\f[] or just
\f[C]hledger\f[] \f[C]hledger\f[].
To see usage for a specific command: \f[C]hledger\ COMMAND\ \-h\f[].
.PP .PP
To see usage for a specific command: \f[C]hledger\ COMMAND\ \-h\f[] hledger has several kinds of options:
.IP \[bu] 2
General options are always available and can appear anywhere on the
command line.
\f[C]hledger\ \-h\f[] shows these.
Eg: \f[C]hledger\ \-\-version\f[].
.IP \[bu] 2
Common reporting options are available with most commands.
These and all other non\-general options must be written after COMMAND.
\f[C]hledger\ COMMAND\ \-h\f[] shows these.
Eg: \f[C]hledger\ register\ \-\-cleared\f[].
.IP \[bu] 2
Command\-specific options are also provided by some commands.
\f[C]hledger\ COMMAND\ \-h\f[] shows these too.
Eg: \f[C]hledger\ register\ \-\-average\f[].
.IP \[bu] 2
Some hledger commands come from separate add\-on executables, which have
their own options.
\f[C]hledger\ COMMAND\ \-h\f[] shows these, as usual.
Such options, if not also supported by hledger, should be written
following a double hyphen argument (\f[C]\-\-\f[]) so that hledger\[aq]s
option parser does not complain.
Eg: \f[C]hledger\ ui\ \-\-\ \-\-register=checking\f[].
Or, you can just run the add\-on directly:
\f[C]hledger\-ui\ \-\-register=checking\f[].
.PP .PP
Except for the General options below, options must be written after Command arguments may also follow the command name.
COMMAND, not before it. In most cases these specify a query which filters the data.
Command options and arguments can be intermixed.
.PP .PP
Also, when invoking external add\-on commands, their options must be Option and argument values containing problematic characters should be
written after a double hyphen. escaped with double quotes, backslashes, or (best) single quotes.
(Or, you can invoke the external command directly.) Eg: This means spaces, but also characters which are significant to your
.IP command shell, such as less\-than/greater\-than.
.nf Eg:
\f[C] \f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[].
$\ hledger\ ui\ \-\-\ \-\-register\ cash
$\ hledger\-ui\ \-\-register\ cash
\f[]
.fi
.PP .PP
Options and command arguments can be intermixed. Characters which are significant to the shell and also in regular
Arguments are usually interpreted as a search query which filters the expressions, like parentheses, the pipe symbol and the dollar sign, must
data, see QUERIES. sometimes be double\-escaped.
Eg, to match the dollar symbol:
\f[C]hledger\ balance\ cur:\[aq]\\$\[aq]\f[] or
\f[C]hledger\ balance\ cur:\\\\$\f[].
.PP .PP
There are three kinds of options. There\[aq]s more..
General options are always available and can appear anywhere in the options and arguments being passed by hledger to an add\-on executable
command line: get de\-escaped once in the process.
In this case you might need triple\-escaping.
Eg: \f[C]hledger\ ui\ cur:\[aq]\\\\$\[aq]\f[] or
\f[C]hledger\ ui\ cur:\\\\\\\\$\f[].
.PP
If in doubt, keep things simple:
.IP \[bu] 2
write options after the command
.IP \[bu] 2
enclose problematic args in single quotes
.IP \[bu] 2
if needed, also add a backslash to escape regexp metacharacters
.IP \[bu] 2
run add\-on executables directly
.PP
If you\[aq]re really curious, add \f[C]\-\-debug\ 2\f[] for
troubleshooting.
.PP
\f[B]General options:\f[]
.TP .TP
.B \f[C]\-h\f[] .B \f[C]\-h\f[]
show general usage (or after COMMAND, the command\[aq]s usage) show general usage (or after COMMAND, the command\[aq]s usage)
@ -249,10 +292,7 @@ ignore any failing balance assertions in the journal
.RS .RS
.RE .RE
.PP .PP
Common reporting options are supported by most commands where \f[B]Common reporting options:\f[]
applicable, and individual commands may provide additional
command\-specific options.
Both of these must be written after the command name.
.TP .TP
.B \f[C]\-b\ \-\-begin=DATE\f[] .B \f[C]\-b\ \-\-begin=DATE\f[]
include postings/txns on or after this date include postings/txns on or after this date

249
hledger/doc/hledger.1.info
View File

@ -139,27 +139,63 @@ File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
********* *********
To see general usage and the command list: `hledger -h' or just To see general usage and the command list: `hledger -h' or just
`hledger' `hledger'. To see usage for a specific command: `hledger COMMAND -h'.
To see usage for a specific command: `hledger COMMAND -h' hledger has several kinds of options:
Except for the General options below, options must be written after * General options are always available and can appear anywhere on the
COMMAND, not before it. command line. `hledger -h' shows these. Eg: `hledger --version'.
Also, when invoking external add-on commands, their options must be * Common reporting options are available with most commands. These
written after a double hyphen. (Or, you can invoke the external command and all other non-general options must be written after COMMAND.
directly.) Eg: `hledger COMMAND -h' shows these. Eg: `hledger register --cleared'.
* Command-specific options are also provided by some commands.
`hledger COMMAND -h' shows these too. Eg: `hledger register
--average'.
* Some hledger commands come from separate add-on executables, 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'.
$ hledger ui -- --register cash Command arguments may also follow the command name. In most cases
$ hledger-ui --register cash these specify a query which filters the data. Command options and
arguments can be intermixed.
Options and command arguments can be intermixed. Arguments are Option and argument values containing problematic characters should
usually interpreted as a search query which filters the data, see be escaped with double quotes, backslashes, or (best) single quotes.
QUERIES. This means spaces, but 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'.
There are three kinds of options. General options are always Characters which are significant to the shell and also in regular
available and can appear anywhere in the command line: 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 `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. Eg: `hledger ui cur:'\\$'' or `hledger ui
cur:\\\\$'.
If in doubt, keep things simple:
* 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.
*General options:*
`-h' `-h'
show general usage (or after COMMAND, the command's usage) show general usage (or after COMMAND, the command's usage)
@ -192,10 +228,7 @@ available and can appear anywhere in the command line:
`--ignore-assertions' `--ignore-assertions'
ignore any failing balance assertions in the journal ignore any failing balance assertions in the journal
Common reporting options are supported by most commands where *Common reporting options:*
applicable, and individual commands may provide additional
command-specific options. Both of these must be written after the
command name.
`-b --begin=DATE' `-b --begin=DATE'
include postings/txns on or after this date include postings/txns on or after this date
@ -2046,95 +2079,95 @@ Node: EXAMPLES1875
Ref: #examples1977 Ref: #examples1977
Node: OPTIONS3981 Node: OPTIONS3981
Ref: #options4085 Ref: #options4085
Node: Multiple files7394 Node: Multiple files8956
Ref: #multiple-files7519 Ref: #multiple-files9081
Node: Repeated options7784 Node: Repeated options9346
Ref: #repeated-options7936 Ref: #repeated-options9498
Node: Depth limiting8056 Node: Depth limiting9618
Ref: #depth-limiting8201 Ref: #depth-limiting9763
Node: Smart dates8402 Node: Smart dates9964
Ref: #smart-dates8543 Ref: #smart-dates10105
Node: Reporting interval9540 Node: Reporting interval11102
Ref: #reporting-interval9699 Ref: #reporting-interval11261
Node: Period expressions10042 Node: Period expressions11604
Ref: #period-expressions10209 Ref: #period-expressions11771
Node: Regular Expressions12255 Node: Regular Expressions13817
Ref: #regular-expressions12397 Ref: #regular-expressions13959
Node: QUERIES13880 Node: QUERIES15442
Ref: #queries13984 Ref: #queries15546
Node: COMMANDS17286 Node: COMMANDS18848
Ref: #commands17400 Ref: #commands18962
Node: accounts18073 Node: accounts19635
Ref: #accounts18173 Ref: #accounts19735
Node: activity19155 Node: activity20717
Ref: #activity19267 Ref: #activity20829
Node: add19626 Node: add21188
Ref: #add19727 Ref: #add21289
Node: balance22386 Node: balance23948
Ref: #balance22499 Ref: #balance24061
Node: Flat mode25215 Node: Flat mode26777
Ref: #flat-mode25342 Ref: #flat-mode26904
Node: Depth limited balance reports25761 Node: Depth limited balance reports27323
Ref: #depth-limited-balance-reports25964 Ref: #depth-limited-balance-reports27526
Node: Multicolumn balance reports26385 Node: Multicolumn balance reports27947
Ref: #multicolumn-balance-reports26587 Ref: #multicolumn-balance-reports28149
Node: Market value31236 Node: Market value32798
Ref: #market-value31400 Ref: #market-value32962
Node: Custom balance output31893 Node: Custom balance output33455
Ref: #custom-balance-output32066 Ref: #custom-balance-output33628
Node: Output destination34170 Node: Output destination35732
Ref: #output-destination34335 Ref: #output-destination35897
Node: CSV output34605 Node: CSV output36167
Ref: #csv-output34724 Ref: #csv-output36286
Node: balancesheet35121 Node: balancesheet36683
Ref: #balancesheet35249 Ref: #balancesheet36811
Node: cashflow35901 Node: cashflow37463
Ref: #cashflow36018 Ref: #cashflow37580
Node: help36708 Node: help38270
Ref: #help36820 Ref: #help38382
Node: incomestatement37657 Node: incomestatement39219
Ref: #incomestatement37787 Ref: #incomestatement39349
Node: info38514 Node: info40076
Ref: #info38621 Ref: #info40183
Node: man38983 Node: man40545
Ref: #man39080 Ref: #man40642
Node: print39483 Node: print41045
Ref: #print39588 Ref: #print41150
Node: register40939 Node: register42501
Ref: #register41052 Ref: #register42614
Node: Custom register output45393 Node: Custom register output46955
Ref: #custom-register-output45524 Ref: #custom-register-output47086
Node: stats46821 Node: stats48383
Ref: #stats46927 Ref: #stats48489
Node: test47808 Node: test49370
Ref: #test47895 Ref: #test49457
Node: ADD-ON COMMANDS48262 Node: ADD-ON COMMANDS49824
Ref: #add-on-commands48398 Ref: #add-on-commands49960
Node: api49686 Node: api51248
Ref: #api49778 Ref: #api51340
Node: autosync49812 Node: autosync51374
Ref: #autosync49927 Ref: #autosync51489
Node: diff52242 Node: diff53804
Ref: #diff52352 Ref: #diff53914
Node: equity53016 Node: equity54578
Ref: #equity53130 Ref: #equity54692
Node: interest54458 Node: interest56020
Ref: #interest54575 Ref: #interest56137
Node: irr57659 Node: irr59221
Ref: #irr57772 Ref: #irr59334
Node: print-unique60147 Node: print-unique61709
Ref: #print-unique60277 Ref: #print-unique61839
Node: rewrite60535 Node: rewrite62097
Ref: #rewrite60654 Ref: #rewrite62216
Node: ui61183 Node: ui62745
Ref: #ui61283 Ref: #ui62845
Node: web61324 Node: web62886
Ref: #web61412 Ref: #web62974
Node: TROUBLESHOOTING61445 Node: TROUBLESHOOTING63007
Ref: #troubleshooting61564 Ref: #troubleshooting63126
Node: Run-time problems61618 Node: Run-time problems63180
Ref: #run-time-problems61761 Ref: #run-time-problems63323
Node: Known limitations63705 Node: Known limitations65267
Ref: #known-limitations63848 Ref: #known-limitations65410
 
End Tag Table End Tag Table

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

@ -1,32 +1,66 @@
# OPTIONS # OPTIONS
To see general usage and the command list: `hledger -h` or just `hledger` 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 usage for a specific command: `hledger COMMAND -h` hledger has several kinds of options:
Except for the General options below, options must be written after - General options are always available and can appear anywhere on the command line.
COMMAND, not before it. `hledger -h` shows these. Eg: `hledger --version`.
Also, when invoking external add-on commands, their options must be - Common reporting options are available with most commands.
written after a double hyphen. (Or, you can invoke the external command These and all other non-general options must be written after COMMAND.
directly.) Eg: `hledger COMMAND -h` shows these. Eg: `hledger register --cleared`.
_shell_({{ - Command-specific options are also provided by some commands.
$ hledger ui -- --register cash `hledger COMMAND -h` shows these too. Eg: `hledger register --average`.
$ hledger-ui --register cash
}})
Options and command arguments can be intermixed. Arguments are usually - Some hledger commands come from separate [add-on executables](#commands),
interpreted as a search query which filters the data, see QUERIES. 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`.
There are three kinds of options. Command arguments may also follow the command name.
General options are always available and can appear anywhere in the command line: 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
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
`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.
Eg: `hledger ui cur:'\\$'` or `hledger ui cur:\\\\$`.
If in doubt, keep things simple:
- 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.
**General options:**
_generaloptions_ _generaloptions_
Common reporting options are supported by most commands where applicable, **Common reporting options:**
and individual commands may provide additional command-specific options.
Both of these must be written after the command name.
_reportingoptions_ _reportingoptions_