From f2cdceb28ec5343a83f8f4f2aee79ac6d34e61bc Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 11 Jun 2016 21:33:56 -0700 Subject: [PATCH] doc: cli: rewrite options description --- hledger/doc/hledger.1 | 88 +++++++++---- hledger/doc/hledger.1.info | 249 +++++++++++++++++++++---------------- hledger/doc/options.m4.md | 70 ++++++++--- 3 files changed, 257 insertions(+), 150 deletions(-) diff --git a/hledger/doc/hledger.1 b/hledger/doc/hledger.1 index 370e2a3cb..482c4cc18 100644 --- a/hledger/doc/hledger.1 +++ b/hledger/doc/hledger.1 @@ -171,31 +171,74 @@ $\ hledger\ bal\ \-\-pivot\ member .SH OPTIONS .PP 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 -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 -Except for the General options below, options must be written after -COMMAND, not before it. +Command arguments may also follow the command name. +In most cases these specify a query which filters the data. +Command options and arguments can be intermixed. .PP -Also, when invoking external add\-on commands, their options must be -written after a double hyphen. -(Or, you can invoke the external command directly.) Eg: -.IP -.nf -\f[C] -$\ hledger\ ui\ \-\-\ \-\-register\ cash -$\ hledger\-ui\ \-\-register\ cash -\f[] -.fi +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: +\f[C]hledger\ register\ \-p\ \[aq]last\ year\[aq]\ "accounts\ receivable\ (receivable|payable)"\ amt:\\>100\f[]. .PP -Options and command arguments can be intermixed. -Arguments are usually interpreted as a search query which filters the -data, see QUERIES. +Characters which are significant to the shell and also in regular +expressions, like parentheses, the pipe symbol and the dollar sign, must +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 -There are three kinds of options. -General options are always available and can appear anywhere in the -command line: +There\[aq]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: \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 .B \f[C]\-h\f[] show general usage (or after COMMAND, the command\[aq]s usage) @@ -249,10 +292,7 @@ ignore any failing balance assertions in the journal .RS .RE .PP -Common reporting options are supported by most commands where -applicable, and individual commands may provide additional -command\-specific options. -Both of these must be written after the command name. +\f[B]Common reporting options:\f[] .TP .B \f[C]\-b\ \-\-begin=DATE\f[] include postings/txns on or after this date diff --git a/hledger/doc/hledger.1.info b/hledger/doc/hledger.1.info index f098f9c99..e15c73136 100644 --- a/hledger/doc/hledger.1.info +++ b/hledger/doc/hledger.1.info @@ -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 -`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 -COMMAND, not before it. + * General options are always available and can appear anywhere on the + command line. `hledger -h' shows these. Eg: `hledger --version'. - Also, when invoking external add-on commands, their options must be -written after a double hyphen. (Or, you can invoke the external command -directly.) Eg: + * 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'. + + * 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 -$ hledger-ui --register cash + Command arguments may also follow the command name. In most cases +these specify a query which filters the data. Command options and +arguments can be intermixed. - Options and command arguments can be intermixed. Arguments are -usually interpreted as a search query which filters the data, see -QUERIES. + 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'. - There are three kinds of options. General options are always -available and can appear anywhere in the command line: + Characters which are significant to the shell and also in 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:* `-h' 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 any failing balance assertions in the journal - Common reporting options are supported by most commands where -applicable, and individual commands may provide additional -command-specific options. Both of these must be written after the -command name. + *Common reporting options:* `-b --begin=DATE' include postings/txns on or after this date @@ -2046,95 +2079,95 @@ Node: EXAMPLES1875 Ref: #examples1977 Node: OPTIONS3981 Ref: #options4085 -Node: Multiple files7394 -Ref: #multiple-files7519 -Node: Repeated options7784 -Ref: #repeated-options7936 -Node: Depth limiting8056 -Ref: #depth-limiting8201 -Node: Smart dates8402 -Ref: #smart-dates8543 -Node: Reporting interval9540 -Ref: #reporting-interval9699 -Node: Period expressions10042 -Ref: #period-expressions10209 -Node: Regular Expressions12255 -Ref: #regular-expressions12397 -Node: QUERIES13880 -Ref: #queries13984 -Node: COMMANDS17286 -Ref: #commands17400 -Node: accounts18073 -Ref: #accounts18173 -Node: activity19155 -Ref: #activity19267 -Node: add19626 -Ref: #add19727 -Node: balance22386 -Ref: #balance22499 -Node: Flat mode25215 -Ref: #flat-mode25342 -Node: Depth limited balance reports25761 -Ref: #depth-limited-balance-reports25964 -Node: Multicolumn balance reports26385 -Ref: #multicolumn-balance-reports26587 -Node: Market value31236 -Ref: #market-value31400 -Node: Custom balance output31893 -Ref: #custom-balance-output32066 -Node: Output destination34170 -Ref: #output-destination34335 -Node: CSV output34605 -Ref: #csv-output34724 -Node: balancesheet35121 -Ref: #balancesheet35249 -Node: cashflow35901 -Ref: #cashflow36018 -Node: help36708 -Ref: #help36820 -Node: incomestatement37657 -Ref: #incomestatement37787 -Node: info38514 -Ref: #info38621 -Node: man38983 -Ref: #man39080 -Node: print39483 -Ref: #print39588 -Node: register40939 -Ref: #register41052 -Node: Custom register output45393 -Ref: #custom-register-output45524 -Node: stats46821 -Ref: #stats46927 -Node: test47808 -Ref: #test47895 -Node: ADD-ON COMMANDS48262 -Ref: #add-on-commands48398 -Node: api49686 -Ref: #api49778 -Node: autosync49812 -Ref: #autosync49927 -Node: diff52242 -Ref: #diff52352 -Node: equity53016 -Ref: #equity53130 -Node: interest54458 -Ref: #interest54575 -Node: irr57659 -Ref: #irr57772 -Node: print-unique60147 -Ref: #print-unique60277 -Node: rewrite60535 -Ref: #rewrite60654 -Node: ui61183 -Ref: #ui61283 -Node: web61324 -Ref: #web61412 -Node: TROUBLESHOOTING61445 -Ref: #troubleshooting61564 -Node: Run-time problems61618 -Ref: #run-time-problems61761 -Node: Known limitations63705 -Ref: #known-limitations63848 +Node: Multiple files8956 +Ref: #multiple-files9081 +Node: Repeated options9346 +Ref: #repeated-options9498 +Node: Depth limiting9618 +Ref: #depth-limiting9763 +Node: Smart dates9964 +Ref: #smart-dates10105 +Node: Reporting interval11102 +Ref: #reporting-interval11261 +Node: Period expressions11604 +Ref: #period-expressions11771 +Node: Regular Expressions13817 +Ref: #regular-expressions13959 +Node: QUERIES15442 +Ref: #queries15546 +Node: COMMANDS18848 +Ref: #commands18962 +Node: accounts19635 +Ref: #accounts19735 +Node: activity20717 +Ref: #activity20829 +Node: add21188 +Ref: #add21289 +Node: balance23948 +Ref: #balance24061 +Node: Flat mode26777 +Ref: #flat-mode26904 +Node: Depth limited balance reports27323 +Ref: #depth-limited-balance-reports27526 +Node: Multicolumn balance reports27947 +Ref: #multicolumn-balance-reports28149 +Node: Market value32798 +Ref: #market-value32962 +Node: Custom balance output33455 +Ref: #custom-balance-output33628 +Node: Output destination35732 +Ref: #output-destination35897 +Node: CSV output36167 +Ref: #csv-output36286 +Node: balancesheet36683 +Ref: #balancesheet36811 +Node: cashflow37463 +Ref: #cashflow37580 +Node: help38270 +Ref: #help38382 +Node: incomestatement39219 +Ref: #incomestatement39349 +Node: info40076 +Ref: #info40183 +Node: man40545 +Ref: #man40642 +Node: print41045 +Ref: #print41150 +Node: register42501 +Ref: #register42614 +Node: Custom register output46955 +Ref: #custom-register-output47086 +Node: stats48383 +Ref: #stats48489 +Node: test49370 +Ref: #test49457 +Node: ADD-ON COMMANDS49824 +Ref: #add-on-commands49960 +Node: api51248 +Ref: #api51340 +Node: autosync51374 +Ref: #autosync51489 +Node: diff53804 +Ref: #diff53914 +Node: equity54578 +Ref: #equity54692 +Node: interest56020 +Ref: #interest56137 +Node: irr59221 +Ref: #irr59334 +Node: print-unique61709 +Ref: #print-unique61839 +Node: rewrite62097 +Ref: #rewrite62216 +Node: ui62745 +Ref: #ui62845 +Node: web62886 +Ref: #web62974 +Node: TROUBLESHOOTING63007 +Ref: #troubleshooting63126 +Node: Run-time problems63180 +Ref: #run-time-problems63323 +Node: Known limitations65267 +Ref: #known-limitations65410  End Tag Table diff --git a/hledger/doc/options.m4.md b/hledger/doc/options.m4.md index 0a729c22d..ddb353c7c 100644 --- a/hledger/doc/options.m4.md +++ b/hledger/doc/options.m4.md @@ -1,32 +1,66 @@ # 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 -COMMAND, not before it. +- General options are always available and can appear anywhere on the command line. + `hledger -h` shows these. Eg: `hledger --version`. -Also, when invoking external add-on commands, their options must be -written after a double hyphen. (Or, you can invoke the external command -directly.) Eg: +- 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`. -_shell_({{ -$ hledger ui -- --register cash -$ hledger-ui --register cash -}}) +- Command-specific options are also provided by some commands. + `hledger COMMAND -h` shows these too. Eg: `hledger register --average`. -Options and command arguments can be intermixed. Arguments are usually -interpreted as a search query which filters the data, see QUERIES. +- 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`. -There are three kinds of options. -General options are always available and can appear anywhere in the command line: +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 +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_ -Common reporting options are supported by most commands where applicable, -and individual commands may provide additional command-specific options. -Both of these must be written after the command name. +**Common reporting options:** _reportingoptions_