34 KiB
- 0.27
- 201511 ideas for shorter help
- general help: Flags moved to top, -h and –help split:
- -h shows just the command-specific flags:
- -h shows command-specific flags plus general flags in brief:
- -h shows command-specific flags in brief plus general flags in brief:
- -h shows specific flags and general flags in brief, together
- -h shows specific flags and general flags in brief, together, more compactly
- 1.1
- 201703 ideas
- wishes
- short help that fits more easily on a single screen
- avoid surprise due to difference between -h and -help
- avoid unexpected/excessive output/scrolling
- adapt to current terminal, pager, tools
- clear intuitive consistent maintainable UI without confusion/over-complexity
- organise commands by topic, usefulness, maturity, location
- use colour
- commands list help section
- hledger (commands list)
- hledger -h (usage/short help)
- hledger print -h (command usage)
- hledger print -hh (command full usage)
- hledger –help (manual/long help)
- wishes
- 201707 https://github.com/simonmichael/hledger/issues/579
- principles
- docs (usage, manuals, tutorials..) should be available reliably and instantly from the software you are running (without net or filesystem access and on windows too)
- docs should by default be provided in the native UI of the tool you request them from
- each tool should provide the full set of docs
- within a tool, there should be one clear way to call up any particular doc
- merge -h/–help, emphasize help command, provide full docs in hledger-ui and hledger-web also
- -h/–help will be synonyms for short context-sensitive usage help (ideally one screenful)
- hledger help will list/show all (8) manuals as plain text (or man pages or info manuals where supported)
- hledger-ui will include all manuals as help screens (or call out to man/info)
- hledger-web will include all manuals as web content
- examples
- principles
0.27
$ hledger –help hledger [COMMAND] … [OPTIONS] [ARGS]
Data entry commands: add prompt for transactions and add them to the journal
Reporting commands: print show transaction entries accounts show account names balance show accounts and balances (bal) register show postings and running total (reg) incomestatement show an income statement (is) balancesheet show a balance sheet (bs) cashflow show a cashflow statement (cf) activity show an ascii barchart of posting counts per interval (default: daily) stats show some journal statistics
Add-on commands: autosync chart generate simple balance pie charts check-dates check-dates1 convertdates diff equity show a transaction entry zeroing all accounts estimatedtax estimatedtax.hs interest generate interest transaction entries irr calculate internal rate of return print-unique print only transactions with unique descriptions register-match rewrite add specified postings to matched transaction entries ui ui1 vty start the curses-style interface web start the web interface webdev
General flags: -h –help show general help or (after command) command help –debug=N show debug output if N is 1-9 (default: 0) –version show version information
$ hledger accounts –help accounts [OPTIONS] [PATTERNS] show account names
Flags: –tree show short account names, as a tree –flat show full account names, as a list (default) –drop=N flat mode: omit N leading account name parts
General flags: -f –file=FILE use a different input file. For stdin, use - –rules-file=RFILE CSV conversion rules file (default: FILE.rules) –alias=OLD=NEW display accounts named OLD as NEW –ignore-assertions ignore any balance assertions in the journal -b –begin=DATE include postings/txns on or after this date -e –end=DATE include postings/txns before this date -D –daily multiperiod/multicolumn report by day -W –weekly multiperiod/multicolumn report by week -M –monthly multiperiod/multicolumn report by month -Q –quarterly multiperiod/multicolumn report by quarter -Y –yearly multiperiod/multicolumn report by year -p –period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) –date2 –aux-date use postings/txns' secondary dates instead -C –cleared include only cleared postings/txns –pending include only pending postings/txns -U –uncleared include only uncleared (and pending) postings/txns -R –real include only non-virtual postings –depth=N hide accounts/postings deeper than N -E –empty show empty/zero things which are normally omitted -B –cost show amounts in their cost price's commodity -h –help show general help or (after command) command help –debug=N show debug output if N is 1-9 (default: 0) –version show version information
This command lists the accounts referenced by matched postings (and in tree mode, their parents as well). The accounts can be depth-clipped (–depth N) or have their leading parts trimmed (–drop N).
$ hledger balance –help balance [OPTIONS] [PATTERNS] show accounts and balances (bal)
Flags: –tree show accounts as a tree (default in simple reports) –flat show accounts as a list (default in multicolumn mode) –drop=N flat mode: omit N leading account name parts –format=FORMATSTR singlecolumn mode: use this custom line format –no-elide tree mode: don't squash boring parent accounts -H –historical multicolumn mode: show historical ending balances –cumulative multicolumn mode: show accumulated ending balances -A –average multicolumn mode: show a row average column -T –row-total multicolumn mode: show a row total column -N –no-total don't show the final total row -V –value show amounts as their current market value in their default valuation commodity -o –output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O –output-format=FMT select the output format. Supported formats: txt, csv.
General flags: -f –file=FILE use a different input file. For stdin, use - –rules-file=RFILE CSV conversion rules file (default: FILE.rules) –alias=OLD=NEW display accounts named OLD as NEW –ignore-assertions ignore any balance assertions in the journal -b –begin=DATE include postings/txns on or after this date -e –end=DATE include postings/txns before this date -D –daily multiperiod/multicolumn report by day -W –weekly multiperiod/multicolumn report by week -M –monthly multiperiod/multicolumn report by month -Q –quarterly multiperiod/multicolumn report by quarter -Y –yearly multiperiod/multicolumn report by year -p –period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) –date2 –aux-date use postings/txns' secondary dates instead -C –cleared include only cleared postings/txns –pending include only pending postings/txns -U –uncleared include only uncleared (and pending) postings/txns -R –real include only non-virtual postings –depth=N hide accounts/postings deeper than N -E –empty show empty/zero things which are normally omitted -B –cost show amounts in their cost price's commodity -h –help show general help or (after command) command help –debug=N show debug output if N is 1-9 (default: 0) –version show version information
$ hledger print –help print [OPTIONS] [PATTERNS] show transaction entries
Flags: -m –match=STR show the transaction whose description is most similar to STR, and is most recent -o –output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O –output-format=FMT select the output format. Supported formats: txt, csv.
General flags: -f –file=FILE use a different input file. For stdin, use - –rules-file=RFILE CSV conversion rules file (default: FILE.rules) –alias=OLD=NEW display accounts named OLD as NEW –ignore-assertions ignore any balance assertions in the journal -b –begin=DATE include postings/txns on or after this date -e –end=DATE include postings/txns before this date -D –daily multiperiod/multicolumn report by day -W –weekly multiperiod/multicolumn report by week -M –monthly multiperiod/multicolumn report by month -Q –quarterly multiperiod/multicolumn report by quarter -Y –yearly multiperiod/multicolumn report by year -p –period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) –date2 –aux-date use postings/txns' secondary dates instead -C –cleared include only cleared postings/txns –pending include only pending postings/txns -U –uncleared include only uncleared (and pending) postings/txns -R –real include only non-virtual postings –depth=N hide accounts/postings deeper than N -E –empty show empty/zero things which are normally omitted -B –cost show amounts in their cost price's commodity -h –help show general help or (after command) command help –debug=N show debug output if N is 1-9 (default: 0) –version show version information
$ hledger register –help register [OPTIONS] [PATTERNS] show postings and running total (reg)
Flags: -H –historical include prior postings in the running total -A –average show a running average instead of the running total (implies –empty) -r –related show postings' siblings instead -w –width=N set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) -o –output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O –output-format=FMT select the output format. Supported formats: txt, csv.
General flags: -f –file=FILE use a different input file. For stdin, use - –rules-file=RFILE CSV conversion rules file (default: FILE.rules) –alias=OLD=NEW display accounts named OLD as NEW –ignore-assertions ignore any balance assertions in the journal -b –begin=DATE include postings/txns on or after this date -e –end=DATE include postings/txns before this date -D –daily multiperiod/multicolumn report by day -W –weekly multiperiod/multicolumn report by week -M –monthly multiperiod/multicolumn report by month -Q –quarterly multiperiod/multicolumn report by quarter -Y –yearly multiperiod/multicolumn report by year -p –period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) –date2 –aux-date use postings/txns' secondary dates instead -C –cleared include only cleared postings/txns –pending include only pending postings/txns -U –uncleared include only uncleared (and pending) postings/txns -R –real include only non-virtual postings –depth=N hide accounts/postings deeper than N -E –empty show empty/zero things which are normally omitted -B –cost show amounts in their cost price's commodity -h –help show general help or (after command) command help –debug=N show debug output if N is 1-9 (default: 0) –version show version information
$ hledger stats –help stats [OPTIONS] [PATTERNS] show some journal statistics
Flags: -o –output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format.
General flags: -f –file=FILE use a different input file. For stdin, use - –rules-file=RFILE CSV conversion rules file (default: FILE.rules) –alias=OLD=NEW display accounts named OLD as NEW –ignore-assertions ignore any balance assertions in the journal -b –begin=DATE include postings/txns on or after this date -e –end=DATE include postings/txns before this date -D –daily multiperiod/multicolumn report by day -W –weekly multiperiod/multicolumn report by week -M –monthly multiperiod/multicolumn report by month -Q –quarterly multiperiod/multicolumn report by quarter -Y –yearly multiperiod/multicolumn report by year -p –period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) –date2 –aux-date use postings/txns' secondary dates instead -C –cleared include only cleared postings/txns –pending include only pending postings/txns -U –uncleared include only uncleared (and pending) postings/txns -R –real include only non-virtual postings –depth=N hide accounts/postings deeper than N -E –empty show empty/zero things which are normally omitted -B –cost show amounts in their cost price's commodity -h –help show general help or (after command) command help –debug=N show debug output if N is 1-9 (default: 0) –version show version information
201511 ideas for shorter help
general help: Flags moved to top, -h and –help split:
$ hledger –help hledger [COMMAND] … [OPTIONS] [ARGS]
General flags: -h show short help (general or, after command, command-specific) –help show long help (general or command-specific) –debug=N show debug output if N is 1-9 (default: 0) –version show version information
Data entry commands: add prompt for transactions and add them to the journal
Reporting commands: print show transaction entries accounts show account names balance show accounts and balances (bal) register show postings and running total (reg) incomestatement show an income statement (is) balancesheet show a balance sheet (bs) cashflow show a cashflow statement (cf) activity show an ascii barchart of posting counts per interval (default: daily) stats show some journal statistics
Add-on commands: autosync chart generate simple balance pie charts check-dates check-dates1 convertdates diff equity show a transaction entry zeroing all accounts estimatedtax estimatedtax.hs interest generate interest transaction entries irr calculate internal rate of return print-unique print only transactions with unique descriptions register-match rewrite add specified postings to matched transaction entries ui ui1 vty start the curses-style interface web start the web interface webdev
-h shows just the command-specific flags:
$ hledger accounts -h accounts [OPTIONS] [PATTERNS] show account names
Flags: –tree show short account names, as a tree –flat show full account names, as a list (default) –drop=N flat mode: omit N leading account name parts
(To see all flags, use –help)
$ hledger balance -h balance [OPTIONS] [PATTERNS] show accounts and balances (bal)
Flags: –tree show accounts as a tree (default in simple reports) –flat show accounts as a list (default in multicolumn mode) –drop=N flat mode: omit N leading account name parts –format=FORMATSTR singlecolumn mode: use this custom line format –no-elide tree mode: don't squash boring parent accounts -H –historical multicolumn mode: show historical ending balances –cumulative multicolumn mode: show accumulated ending balances -A –average multicolumn mode: show a row average column -T –row-total multicolumn mode: show a row total column -N –no-total don't show the final total row -V –value show amounts as their current market value in their default valuation commodity -o –output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O –output-format=FMT select the output format. Supported formats: txt, csv.
(To see all flags, use –help)
-h shows command-specific flags plus general flags in brief:
$ hledger print -h print [OPTIONS] [PATTERNS] show transaction entries
Flags: -m –match=STR show the transaction whose description is most similar to STR, and is most recent -o –output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. -O –output-format=FMT select the output format. Supported formats: txt, csv.
General flags (for more detail, use –help): -f –file=FILE –rules-file=RFILE –alias=OLD=NEW –ignore-assertions -b –begin=DATE -e –end=DATE -D –daily -W –weekly -M –monthly -Q –quarterly -Y –yearly -p –period=PERIODEXP –date2 –aux-date -C –cleared –pending -U –uncleared -R –real –depth=N -E –empty -B –cost -h –help –debug=N –version
-h shows command-specific flags in brief plus general flags in brief:
$ hledger register -h register [OPTIONS] [PATTERNS] show postings and running total (reg)
Flags: -H –historical -A –average -r –related -w –width=N -o –output-file=FILE[.FMT] -O –output-format=FMT
General flags: -f –file=FILE –rules-file=RFILE –alias=OLD=NEW –ignore-assertions -b –begin=DATE -e –end=DATE -D –daily -W –weekly -M –monthly -Q –quarterly -Y –yearly -p –period=PERIODEXP –date2 –aux-date -C –cleared –pending -U –uncleared -R –real –depth=N -E –empty -B –cost -h –help –debug=N –version
(for more detail, use –help)
-h shows specific flags and general flags in brief, together
$ hledger stats -h stats [OPTIONS] [PATTERNS] show some journal statistics
Flags: -o –output-file=FILE[.FMT] -f –file=FILE –rules-file=RFILE –alias=OLD=NEW –ignore-assertions -b –begin=DATE -e –end=DATE -D –daily -W –weekly -M –monthly -Q –quarterly -Y –yearly -p –period=PERIODEXP –date2 –aux-date -C –cleared –pending -U –uncleared -R –real –depth=N -E –empty -B –cost -h –help –debug=N –version
(for more detail, use –help)
-h shows specific flags and general flags in brief, together, more compactly
$ hledger stats -h
stats [-o –output-file=FILE[.FMT] -f –file=FILE –rules-file=RFILE –alias=OLD=NEW –ignore-assertions -b –begin=DATE -e –end=DATE -D –daily -W –weekly -M –monthly -Q –quarterly -Y –yearly -p –period=PERIODEXP –date2 –aux-date -C –cleared –pending -U –uncleared -R –real –depth=N -E –empty -B –cost -h –help –debug=N –version] [PATTERNS]
show some journal statistics
(for more detail, use –help)
1.1
$ hledger hledger [COMMAND] … [OPTIONS] [ARGS]
Commands: help show any of the hledger manuals man show any of the hledger manuals with man info show any of the hledger manuals with info Data entry commands: add prompt for transactions and add them to the journal
Reporting commands: print show transaction entries accounts show account names balance show accounts and balances (bal) register show postings and running total (reg) incomestatement show an income statement (is) balancesheet show a balance sheet (bs) cashflow show a cashflow statement (cf) activity show an ascii barchart of posting counts per interval (default: daily) stats show some journal statistics
Add-on commands: api autosync budget chart generate simple balance pie charts check check-dates check dupes equity show a transaction entry zeroing all accounts estimatedtax iadd interest generate interest transaction entries invariant prices print-unique print only transactions with unique descriptions register-match rewrite add specified postings to matched transaction entries ui web start the web interface
General flags: -h show general usage or (after COMMAND, the command's usage –help show the current program's manual as plain text (or after an add-on COMMAND, the add-on's manual) –man show the current program's manual with man –info show the current program's manual with info –debug=[N] show debug output (levels 1-9, default: 1) –version show version information
201703 ideas
wishes
short help that fits more easily on a single screen
avoid surprise due to difference between -h and -help
avoid unexpected/excessive output/scrolling
adapt to current terminal, pager, tools
use pager if available and supported by terminal and output is long
use man (or info) if available and supported by terminal
clear intuitive consistent maintainable UI without confusion/over-complexity
organise commands by topic, usefulness, maturity, location
use colour
commands list help section
a
Get help: -h show general short help CMD -h show command's short help –help show manual –info show manual with info –man show manual with man help show any of the hledger manuals info show any of the hledger manuals with info man show any of the hledger manuals with man
b
Get help: (see also hledger -h, hledger CMD -h, hledger –help|–man|–info) help show any of the hledger manuals info show any of the hledger manuals with info man show any of the hledger manuals with man
c
Get help: help|man|info show any of the hledger manuals in text/info/man format see also -h, CMD -h, –help|–man|–info
d
Get help: (see also -h, CMD -h, –help|–man|–info) help|man|info show any of the hledger manuals in text/info/man format
hledger (commands list)
Commands available:
Standard reports: accounts show chart of accounts balancesheet (bs) show a balance sheet cashflow (cf) show a cashflow statement incomestatement (is) show an income statement transactions (txns) show transactions in some account
General reporting: activity show a bar chart of posting counts per interval balance (bal) show accounts and balances budget add automated postings/txns/bucket accts (experimental) chart generate simple balance pie charts (experimental) check check more powerful balance assertions check-dates check transactions are ordered by date check-dupes check for accounts with the same leaf name estimatedtax calculate estimated tax amounts for some revenue irr calculate internal rate of return of an investment prices show market price records print show transaction journal entries print-unique show only transactions with unique descriptions register (reg) show postings and running total register-match show best matching transaction for a description stats show some journal statistics
Interfaces: add console ui for adding transactions api web api server iadd curses ui for adding transactions ui curses ui web web ui
Misc: autosync download/deduplicate/convert OFX data equity generate transactions to zero & restore account balances interest generate interest transactions rewrite add automated postings to certain transactions
Help: (see also -h, CMD -h, –help|—man|–info) help|man|info show any of the hledger manuals in text/man/info format
hledger -h (usage/short help)
hledger [CMD] [OPTS] [ARGS] hledger's command line interface
General input flags: -f –file=FILE use a different input file. For stdin, use - –rules-file=RFILE CSV conversion rules file (default: FILE.rules) –alias=OLD=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 balance assertions
General reporting flags: -b –begin=DATE include postings/txns on or after this date -e –end=DATE include postings/txns before this date -D –daily multiperiod/multicolumn report by day -W –weekly multiperiod/multicolumn report by week -M –monthly multiperiod/multicolumn report by month -Q –quarterly multiperiod/multicolumn report by quarter -Y –yearly multiperiod/multicolumn report by year -p –period=PERIODEXP set start date, end date, and/or report interval all at once (overrides the flags above) –date2 show and match on secondary dates instead -C –cleared include only cleared postings/txns –pending include only pending postings/txns -U –uncleared include only uncleared (and pending) postings/txns -R –real include only non-virtual postings –depth=N hide accounts/postings deeper than N -E –empty show items with zero amount, normally hidden -B –cost convert amounts to their cost at transaction time (using the transaction price, if any) -V –value convert amounts to their market value on the report end date (using the most recent applicable market price, if any)
General flags: -h –usage show general usage or (after COMMAND, the command's usage –help show this program's manual (or after an add-on command, the add-on's manual) –man show the manual with man –info show the manual with info –debug=[N] show debug output (levels 1-9, default: 1) –version show version information
Examples:
hledger | list commands |
hledger CMD [–] [OPTS] [ARGS] | run a command. command-specific options must go after CMD, and – if its an addon |
hledger-CMD [OPTS] [ARGS] | or run an addon command directly |
hledger -h | hledger usage |
hledger CMD -h | command usage |
hledger –help | hledger manual |
hledger –man | hledger manual as man page |
hledger –info | hledger manual as info manual |
hledger help | list help topics |
hledger help TOPIC | TOPIC manual |
hledger man TOPIC | TOPIC manual as man page |
hledger info TOPIC | TOPIC manual as info manual |
hledger print -h (command usage)
print [OPTS] [QUERYARGS] show transaction journal entries
Flags: -m –match=STR show the transaction whose description is most similar to STR, and is most recent -x –explicit show all amounts explicitly -O –output-format=FMT select the output format. Supported formats: txt, csv. -o –output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format.
plus general flags, see "hledger -h" or "hledger print -hh".
hledger print -hh (command full usage)
print [OPTIONS] [QUERY] show transaction journal entries
Flags: -m –match=STR show the transaction whose description is most similar to STR, and is most recent -x –explicit show all amounts explicitly -O –output-format=FMT select the output format. Supported formats: txt, csv. -o –output-file=FILE write output to FILE. A file extension matching one of the above formats selects that format.
General input flags: -f –file=FILE use a different input file. For stdin, use - –rules-file=RFILE CSV conversion rules file (default: FILE.rules) –alias=OLD=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 balance assertions
General reporting flags: -b –begin=DATE include postings/txns on or after this date -e –end=DATE include postings/txns before this date -D –daily multiperiod/multicolumn report by day -W –weekly multiperiod/multicolumn report by week -M –monthly multiperiod/multicolumn report by month -Q –quarterly multiperiod/multicolumn report by quarter -Y –yearly multiperiod/multicolumn report by year -p –period=PERIODEXP set start date, end date, and/or report interval all at once (overrides the flags above) –date2 show and match on secondary dates instead -C –cleared include only cleared postings/txns –pending include only pending postings/txns -U –uncleared include only uncleared (and pending) postings/txns -R –real include only non-virtual postings –depth=N hide accounts/postings deeper than N -E –empty show items with zero amount, normally hidden -B –cost convert amounts to their cost at transaction time (using the transaction price, if any) -V –value convert amounts to their market value on the report end date (using the most recent applicable market price, if any)
General flags: -h –usage show general usage or (after COMMAND, the command's usage –help show this program's manual (or after an add-on command, the add-on's manual) –man show the current program's manual with man –info show the current program's manual with info –debug=[N] show debug output (levels 1-9, default: 1) –version show version information
hledger –help (manual/long help)
hledger(1) hledger User Manuals hledger(1)
NAME hledger - a command-line accounting tool
SYNOPSIS hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS] hledger [-f FILE] ADDONCMD – [OPTIONS] [CMDARGS]
DESCRIPTION hledger is a cross-platform program for tracking money, time, or any other commodity, using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with ….
201707 https://github.com/simonmichael/hledger/issues/579
principles
docs (usage, manuals, tutorials..) should be available reliably and instantly from the software you are running (without net or filesystem access and on windows too)
docs should by default be provided in the native UI of the tool you request them from
if you're using hledger, you'll see docs as plain text printed to the console (possibly with a pager).
if you're using hledger-ui, you'll see them as tui screens or dialogs.
if you're using hledger-web, you'll see them as built-in web content.
if you're using the web, you'll see them as web pages.
each tool should provide the full set of docs
within a tool, there should be one clear way to call up any particular doc
merge -h/–help, emphasize help command, provide full docs in hledger-ui and hledger-web also
-h/–help will be synonyms for short context-sensitive usage help (ideally one screenful)
hledger help will list/show all (8) manuals as plain text (or man pages or info manuals where supported)
hledger
hledger-ui
hledger-web
hledger-api
journal-format
csv-format
timeclock-format
timedot-format
hledger-ui will include all manuals as help screens (or call out to man/info)
hledger-web will include all manuals as web content
examples
``` hledger -h/–help general usage hledger CMD -h/–help command usage hledger help list manuals/topics hledger help [–man|–info] MANUAL/TOPIC show MANUAL/TOPIC as plain text[/man page/info manual] hledger-ui, hledger-web (manuals provided in-app) ```