From bba79091651a06c278aee506d553e88640f605f7 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 6 Apr 2016 09:03:01 -0700 Subject: [PATCH] doc: m4-based man pages pt 2, missing files --- doc/.gitignore | 7 ++ doc/lib.m4 | 4 + hledger/doc/commands.md | 173 ++++++++++++++++++++++++++++++++++++ hledger/doc/description.md | 35 ++++++++ hledger/doc/examples.md | 62 +++++++++++++ hledger/doc/hledger.1.md.m4 | 59 ++++++++++++ hledger/doc/options.md | 102 +++++++++++++++++++++ hledger/doc/queries.md | 92 +++++++++++++++++++ tools/.gitignore | 7 -- 9 files changed, 534 insertions(+), 7 deletions(-) create mode 100644 doc/.gitignore create mode 100644 doc/lib.m4 create mode 100644 hledger/doc/commands.md create mode 100644 hledger/doc/description.md create mode 100644 hledger/doc/examples.md create mode 100644 hledger/doc/hledger.1.md.m4 create mode 100644 hledger/doc/options.md create mode 100644 hledger/doc/queries.md diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 000000000..e27154fd8 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,7 @@ +pandoc-capitalize-headers +pandoc-drop-html-blocks +pandoc-drop-html-inlines +pandoc-drop-links +pandoc-drop-man-blocks +pandoc-drop-notes +pandoc-drop-web-blocks diff --git a/doc/lib.m4 b/doc/lib.m4 new file mode 100644 index 000000000..2409311b5 --- /dev/null +++ b/doc/lib.m4 @@ -0,0 +1,4 @@ +m4_changequote({{,}})m4_dnl +m4_define({{_man_}}, m4_ifdef({{MAN}},{{$1}}))m4_dnl +m4_define({{_web_}}, m4_ifdef({{WEB}},{{$1}}))m4_dnl +m4_define({{_include_}}, m4_defn({{m4_include}}))m4_dnl diff --git a/hledger/doc/commands.md b/hledger/doc/commands.md new file mode 100644 index 000000000..c8f9da5c0 --- /dev/null +++ b/hledger/doc/commands.md @@ -0,0 +1,173 @@ +# COMMANDS + +COMMAND selects one of hledger's subcommands; omit it to list available commands. +To save typing, some commands have a short form; any unique prefix also works. + +Here is a summary (see http://hledger.org/manual#commands for the full command help): + +## Data entry: + +### add +prompt for transactions and add them to the journal. + +This is the only hledger command that writes to the journal file. +It appends only, existing transactions are not changed. + +`--no-new-accounts` +: don't allow creating new accounts; helps prevent typos when entering account names + +## Reporting: + +### accounts +show account names + +`--tree` +: show short account names, as a tree + +`--flat` +: show full account names, as a list (default) + +`--drop=N` +: in flat mode: omit N leading account name parts + +### activity +show an ascii barchart of posting counts per interval +(default: daily) + +### balance, bal +show accounts and balances + +`--tree` +: show short account names, as a tree + +`--flat` +: show full account names, as a list (default) + +`--drop=N` +: in flat mode: omit N leading account name parts + +`--format=LINEFORMAT` +: in single-column balance reports: use this custom line format + +`--no-elide` +: in tree mode: don't squash boring parent accounts + +`-H --historical` +: in multicolumn mode: show historical ending balances + +`--cumulative` +: in multicolumn mode: show accumulated ending balances + +`-A --average` +: in multicolumn mode: show a row average column + +`-T --row-total` +: in 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 FILE[.FMT] --output-file=FILE[.FMT]` +: write output to FILE instead of stdout. A recognised FMT suffix influences the format. + +`-O FMT --output-format=FMT ` +: select the output format. Supported formats: +txt, csv. + +### balancesheet, bs +show a balance sheet + +`--flat` +: show full account names, as a list (default) + +`--drop=N` +: in flat mode: omit N leading account name parts + +### cashflow, cf +show a cashflow statement + +`--flat` +: show full account names, as a list (default) + +`--drop=N` +: in flat mode: omit N leading account name parts + +### incomestatement, is +show an income statement + +`--flat` +: show full account names, as a list (default) + +`--drop=N` +: in flat mode: omit N leading account name parts + +### print +show transactions from the journal + +`-m STR --match=STR ` +: show the transaction whose description is most similar to STR, and is most recent + +`-o FILE[.FMT] --output-file=FILE[.FMT]` +: write output to FILE instead of stdout. A recognised FMT suffix influences the format. + +`-O FMT --output-format=FMT ` +: select the output format. Supported formats: +txt, csv. + +### register, reg +show postings and running total + +`-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 N --width=N` +: set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) + +`-o FILE[.FMT] --output-file=FILE[.FMT]` +: write output to FILE instead of stdout. A recognised FMT suffix influences the format. + +`-O FMT --output-format=FMT ` +: select the output format. Supported formats: +txt, csv. + +### stats +show some journal statistics + +`-o FILE[.FMT] --output-file=FILE[.FMT]` +: write output to FILE instead of stdout. A recognised FMT suffix influences the format. + +## Add-on commands: + +Additional commands will be available when executables or scripts +named "`hledger-`CMD" are installed in the PATH. These are often +provided by a package of the same name, or you can make your own custom scripts +(haskell scripts can use hledger-lib allowing tight integration). +Some available add-ons are: + +### autosync +download OFX bank data and/or convert OFX to hledger journal format + +### diff +show transactions present in one journal file but not another + +### interest +generate interest transactions + +### irr +calculate internal rate of return + +### ui +curses-style interface, see hledger-ui(1) + +### web +web interface, see hledger-web(1) + diff --git a/hledger/doc/description.md b/hledger/doc/description.md new file mode 100644 index 000000000..b9d9934fc --- /dev/null +++ b/hledger/doc/description.md @@ -0,0 +1,35 @@ +This is hledger’s command-line interface (there are also curses and web +interfaces). Its basic function is to read a plain text file describing +financial transactions (in accounting terms, a general journal) and +print useful reports on standard output, or export them as CSV. hledger +can also read CSV files, converting them semi-automatically to journal +format. Additionally, hledger lists other hledger-\* executables found +in the user’s \$PATH and can invoke them as subcommands. + +The journal file is `~/.hledger.journal` by default, or another file path +specified by `$LEDGER_FILE`. +(This should be a real environment variable, not a shell variable.) +You can also specify a file with `-f FILE`, +or standard input with `-f-`. + +Transactions are dated movements of money between two (or more) named +accounts, and are recorded with journal entries like this: + +```journal +2015/10/16 bought food + expenses:food $10 + assets:cash +``` + +For more about the format, see hledger_journal(5). + +Most users use a text editor to edit the journal, usually with an editor +mode such as ledger-mode for added convenience. hledger’s interactive +add command is another way to record new transactions. hledger never +changes existing transactions. + +To get started, you can either save some entries like the above in +`~/.hledger.journal`, or run `hledger add` and follow the prompts. Then +try some commands like `hledger print` or `hledger balance`. +See COMMANDS and EXAMPLES below. + diff --git a/hledger/doc/examples.md b/hledger/doc/examples.md new file mode 100644 index 000000000..13336e214 --- /dev/null +++ b/hledger/doc/examples.md @@ -0,0 +1,62 @@ +# EXAMPLES + +Two simple transactions in hledger journal format: + +```journal +2015/9/30 gift received + assets:cash $20 + income:gifts + +2015/10/16 farmers market + expenses:food $10 + assets:cash +``` + +Some basic reports: + +```shell +$ hledger print +2015/09/30 gift received + assets:cash $20 + income:gifts $-20 + +2015/10/16 farmers market + expenses:food $10 + assets:cash $-10 +``` +```shell +$ hledger accounts --tree +assets + cash +expenses + food +income + gifts +``` +```shell +$ hledger balance + $10 assets:cash + $10 expenses:food + $-20 income:gifts +-------------------- + 0 +``` +```shell +$ hledger register cash +2015/09/30 gift received assets:cash $20 $20 +2015/10/16 farmers market assets:cash $-10 $10 +``` + +```{.shell .bold} +$ hledger # show available commands +$ hledger add # add more transactions to the journal file +$ hledger balance # all accounts with aggregated balances +$ hledger balance --help # show help for balance command +$ hledger balance --depth 1 # only top-level accounts +$ hledger register # show account postings, with running total +$ hledger reg income # show postings to/from income accounts +$ hledger reg 'assets:some bank:checking' # show postings to/from this checking account +$ hledger print desc:shop # show transactions with shop in the description +$ hledger activity -W # show transaction counts per week as a bar chart +``` + diff --git a/hledger/doc/hledger.1.md.m4 b/hledger/doc/hledger.1.md.m4 new file mode 100644 index 000000000..c2ffb46d1 --- /dev/null +++ b/hledger/doc/hledger.1.md.m4 @@ -0,0 +1,59 @@ +% hledger(1) hledger 0.26.98 +% +% October 2015 + +_web_(* toc) +_man_({{ +# 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. It is inspired by and largely compatible with ledger(1). +hledger aims to be a reliable, practical tool for daily use. This man +page is a quick reference and introduction; for more complete docs, see +http://hledger.org/manual. +}}) +_include_(description.md) +_include_(options.md) +_include_(commands.md) +_include_(queries.md) +_include_(examples.md) +_man_({{ + +# ENVIRONMENT + +**LEDGER_FILE** +sets the default journal file path. If not set, it is `~/.hledger.journal`. + +**COLUMNS** +sets the default width used by the register command (normally the full terminal width). + +# FILES + +Reads data from a hledger journal file (`$LEDGER_FILE` or +`~/.hledger.journal` by default), or a CSV file plus associated CSV +rules file. + +# BUGS + +The need to precede options with `--` when invoked from hledger is awkward. + +hledger can't render non-ascii characters when run from a Windows command prompt (up to Windows 7 at least). + +When input data contains non-ascii characters, a suitable system locale must be configured (or there will be an unhelpful error). +Eg on POSIX, set LANG to something other than C. + +# REPORTING BUGS + +Report bugs at http://bugs.hledger.org. + +}}) diff --git a/hledger/doc/options.md b/hledger/doc/options.md new file mode 100644 index 000000000..e5964bc51 --- /dev/null +++ b/hledger/doc/options.md @@ -0,0 +1,102 @@ +# OPTIONS + +To see general help and the command list: `hledger --help` or `hledger` + +To see all options available with a command: `hledger COMMAND --help` + +Except for the General options below, options must be written after +COMMAND, not before it. + +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: +```{.shell .bold} +$ hledger ui -- --register cash +$ hledger-ui --register cash +``` + +Options and command arguments can be intermixed. Arguments are usually +interpreted as a search query which filters the data, see QUERIES. + +## General flags: + +These can appear anywhere in the command line. + +`-h --help` +: show general help or (after command) command help + +`--version` +: show version information + +`-f FILE --file=FILE` +: use a different input file. For stdin, use - + +`--rules-file=RULESFILE` +: Conversion rules file to use when reading CSV (default: FILE.rules) + +`--alias=OLD=NEW` +: display accounts named OLD as NEW + +`--ignore-assertions` +: ignore any failing balance assertions in the journal + +`--debug=N` +: : show debug output if N is 1-9 (default: 0) + +## Common reporting flags: + +These are supported by most commands, where applicable. +They must be written after the command name. +Additional command-specific flags are described in COMMANDS below. + +`-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 + +If a reporting option is repeated, the last one takes precedence. Eg -p jan -p +feb is equivalent to -p feb. + diff --git a/hledger/doc/queries.md b/hledger/doc/queries.md new file mode 100644 index 000000000..8a3e9af3a --- /dev/null +++ b/hledger/doc/queries.md @@ -0,0 +1,92 @@ +# QUERIES + +Most commands accept an optional query expression, written as arguments after the command name, +to filter the data by date, account name or other criteria. +The syntax is similar to a web search: +one or more space-separated search terms, +quotes to enclose whitespace, +optional prefixes to match specific fields. +Multiple search terms are combined as follows: + +All commands except print: show transactions/postings/accounts which match (or negatively match) + +- any of the description terms AND +- any of the account terms AND +- all the other terms. + +The print command: show transactions which + +- match any of the description terms AND +- have any postings matching any of the positive account terms AND +- have no postings matching any of the negative account terms AND +- match all the other terms. + +The following kinds of search terms can be used: + + +**`REGEX`** +: match account names by this regular expression + + +**`acct:REGEX`** +: same as above + + +**`amt:N, amt:N, amt:>=N`** +: match postings with a single-commodity amount that is equal to, less +than, or greater than N. (Multi-commodity amounts are not tested, and +will always match.) The comparison has two modes: if N is preceded by +a + or - sign (or is 0), the two signed numbers are +compared. Otherwise, the absolute magnitudes are compared, ignoring +sign. + + +**`code:REGEX`** +: match by transaction code (eg check number) + + +**`cur:REGEX`** +: match postings or transactions including any amounts whose +currency/commodity symbol is fully matched by REGEX. (For a partial +match, use `.*REGEX.*`). Note, to match characters which are +regex-significant, like the dollar sign (`$`), you need to prepend `\`. +And when using the command line you need to add one more level of +quoting to hide it from the shell, so eg do: `hledger print cur:'\$'` +or `hledger print cur:\\$`. + + +**`desc:REGEX`** +: match transaction descriptions + + +**`date:PERIODEXPR`** +: match dates within the specified period (which should not include a +reporting interval + + +**`date2:PERIODEXPR`** +: as above, but match secondary dates + + +**`depth:N`** +: match (or display, depending on command) accounts at or above this depth + + +**`real:, real:0`** +: match real or virtual postings respectively + + +**`status:*, status:!, status:`** +: match cleared, pending, or uncleared/pending transactions respectively + + +**`tag:REGEX[=REGEX]`** +: match by tag name, and optionally also by tag value. Note a +tag: query is considered to match a transaction if it matches any of +the postings. Also remember that postings inherit the tags of their +parent transaction. + + +**`not:`** +: before any of the above negates the match. + diff --git a/tools/.gitignore b/tools/.gitignore index a6540ad27..335da62aa 100644 --- a/tools/.gitignore +++ b/tools/.gitignore @@ -1,8 +1 @@ generatetimelog -pandocCapitalizeHeaders -pandocRemoveHtmlBlocks -pandocRemoveHtmlInlines -pandocRemoveLinks -pandocRemoveManonlyBlocks -pandocRemoveNotes -pandocRemoveWebonlyBlocks