diff --git a/doc/common.m4 b/doc/common.m4 index 6672bb620..6973a9d00 100644 --- a/doc/common.m4 +++ b/doc/common.m4 @@ -13,16 +13,14 @@ m4_dnl m4_dnl Author to show in man pages. m4_define({{_author_}}, {{}})m4_dnl m4_dnl -m4_dnl Macros for conditionally including format-specific content -m4_dnl $1 is the manual's web slug: hledger, hledger-ui, journal, csv etc. -m4_dnl include in man pages only -m4_define({{_man_}}, m4_ifdef({{MAN}},{{$1}}) )m4_dnl -m4_dnl include in web manuals only -m4_define({{_web_}}, m4_ifdef({{WEB}},{{$1}}) )m4_dnl -m4_dnl include in info manuals only -m4_define({{_info_}}, m4_ifdef({{INFO}},{{$1}}) )m4_dnl -m4_dnl include in text manuals only - not implemented -m4_dnl m4_define({{_txt_}}, m4_ifdef({{TXT}},{{$1}}) )m4_dnl +m4_dnl Macros for conditionally including or excluding content based on the format +m4_dnl (man, web or info). +m4_define({{_man_}}, m4_ifdef({{MAN}},{{$1}}) )m4_dnl +m4_define({{_notman_}}, m4_ifdef({{MAN}},,{{$1}}) )m4_dnl +m4_define({{_web_}}, m4_ifdef({{WEB}},{{$1}}) )m4_dnl +m4_define({{_notweb_}}, m4_ifdef({{WEB}},,{{$1}}) )m4_dnl +m4_define({{_info_}}, m4_ifdef({{INFO}},{{$1}}) )m4_dnl +m4_define({{_notinfo_}}, m4_ifdef({{INFO}},,{{$1}}) )m4_dnl m4_dnl m4_dnl Two side-by-side columns. m4_define({{_col2_}}, diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index e6f9821f3..1ea309a4d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -1571,21 +1571,134 @@ Related: # COMMANDS -hledger provides a number of subcommands; `hledger` with no arguments -shows a list. +hledger provides a number of commands for producing reports and managing your data. +Run `hledger` with no arguments to list the commands available. -If you install additional `hledger-*` packages, or if you put programs -or scripts named `hledger-NAME` in your PATH, these will also be -listed as subcommands. +To run a command, write its name as hledger's first argument (eg: `hledger balance`). +Or, you can write one of the standard short aliases which are +shown in parentheses in the command list (eg: `hledger bal`); +or, any unambiguous prefix of a command name. -Run a subcommand by writing its name as first argument (eg `hledger -incomestatement`). You can also write one of the standard short aliases -displayed in parentheses in the command list (`hledger b`), or any -any unambiguous prefix of a command name (`hledger inc`). +Each command's detailed help is available as one or more of: -Here are all the builtin commands in alphabetical order. -See also `hledger` for a more organised command list, -and `hledger CMD -h` for detailed command help. +- command line help, eg: `hledger balance --help` + +- info manuals, eg: `hledger help --info hledger` -> Commands -> balance +- web manuals, eg: + +## Built-in commands + +**Data entry (these modify the journal file):** + +- [add](#add) add transactions using guided prompts +- [import](#import) add any new transactions from other files (eg csv) + +**Data management**: + +- [check](#check) check for various kinds of issue in the data +- [close](#close) (equity) generate balance-resetting transactions +- [diff](#diff) compare account transactions in two journal files +- [rewrite](#rewrite) generate extra postings, similar to print --auto + +**Financial statements:** + +- [aregister](#aregister) (areg) show transactions in a particular account +- [balancesheet](#balancesheet) (bs) show assets, liabilities and net worth +- [balancesheetequity](#balancesheetequity) (bse) show assets, liabilities and equity +- [cashflow](#cashflow) (cf) show changes in liquid assets +- [incomestatement](#incomestatement) (is) show revenues and expenses +- [roi](#roi) show return on investments + +**Miscellaneous reports:** + +- [accounts](#accounts) (a) show account names +- [activity](#activity) show postings-per-interval bar charts +- [balance](#balance) (b, bal) show balance changes/end balances/budgets in accounts +- [codes](#codes) show transaction codes +- [commodities](#commodities) show commodity/currency symbols +- [descriptions](#descriptions) show unique transaction descriptions +- [files](#files) show input file paths +- [notes](#notes) show unique note segments of transaction descriptions +- [payees](#payees) show unique payee segments of transaction descriptions +- [prices](#prices) show market price records +- [print](#print) (p, txns) show transactions (journal entries) +- [print-unique](#print-unique) show only transactions with unique descriptions +- [register](#register) (r, reg) show postings in one or more accounts & running total +- [register-match](#register-match) show a recent posting that best matches a description +- [stats](#stats) show journal statistics +- [tags](#tags) show tag names +- [test](#test) run self tests + +## Add-on commands + +Any programs or scripts in your PATH named named `hledger-SOMETHING` +will also appear in the commands list (with a `+` mark). +These are called add-on commands. + +These offical add-ons are maintained and released along with hledger: + +- [ui](hledger-ui.html) an efficient terminal interface for hledger (TUI) +- [web](hledger-web.html) a simple web interface for hledger (WUI) + +These add-ons are maintained separately: + +- [iadd](http://hackage.haskell.org/package/hledger-iadd) + a more interactive alternative for the [add](hledger.html#add) command +- [interest](http://hackage.haskell.org/package/hledger-interest) + generates interest transactions according to various schemes +- [stockquotes](http://hackage.haskell.org/package/hledger-stockquotes) + downloads market prices for your commodities from AlphaVantage *(experimental)* + + + + + + + + + + +Additional experimental add-ons, which may not be in a working state, +can be found in the bin/ directory in the hledger repo. + +## Add-on command flags + +In a hledger command line, add-on command flags must have a double dash (`--`) preceding them. +Eg you must write: +```shell +$ hledger web -- --serve +``` +and not: +```shell +$ hledger web --serve +``` +(because the `--serve` flag belongs to `hledger-web`, not `hledger`). + +The `-h/--help` and `--version` flags work without `--`, with their position deciding which program they refer to. +Eg `hledger -h web` shows hledger's help, `hledger web -h` shows hledger-web's help. + +If you have any trouble with this, remember you can always run the add-on program directly, eg: +```shell +$ hledger-web --serve +``` + +## Making add-on commands + +Add-on commands are programs or scripts in your PATH + +- whose name starts with `hledger-` +- whose name ends with a recognised file extension: + `.bat`,`.com`,`.exe`, `.hs`,`.lhs`,`.pl`,`.py`,`.rb`,`.rkt`,`.sh` or none +- and (on unix, mac) which are executable by the current user. + +Add-ons are a relatively easy way to add local features or experiment with new ideas. +They can be written in any language, but haskell scripts have a big advantage: +they can use the same hledger library functions that built-in commands use for command-line options, parsing and reporting. + +_notman_({{ +## Detailed command help + +Here are the detailed command docs, in alphabetical order. ## accounts @@ -1707,67 +1820,8 @@ _include_({{Hledger/Cli/Commands/Tags.md}}) _include_({{Hledger/Cli/Commands/Test.md}}) +}}) -## Add-on commands - -hledger also searches for external add-on commands, and will include these in the commands list. -These are programs or scripts in your PATH whose name starts with `hledger-` -and ends with a recognised file extension -(currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`). - -Add-ons can be invoked like any hledger command, but there are a few things to be aware of. -Eg if the `hledger-web` add-on is installed, - -- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help. - -- Flags specific to the add-on must have a preceding `--` to hide them from hledger. - So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`. - -- You can always run add-ons directly if preferred: `hledger-web --serve --port 9000`. - -Add-ons are a relatively easy way to add local features or experiment with new ideas. -They can be written in any language, but haskell scripts have a big advantage: -they can use the same hledger (and haskell) library functions that built-in commands do, -for command-line options, journal parsing, reporting, etc. - -Two important add-ons are the hledger-ui and hledger-web user interfaces. -These are maintained and released along with hledger: - -### ui -[hledger-ui](hledger-ui.html) provides an efficient terminal interface. - -### web -[hledger-web](hledger-web.html) provides a simple web interface. - -Third party add-ons, maintained separately from hledger, include: - -### iadd - -[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) -is a more interactive, terminal UI replacement for the [add command](hledger.html#add). - -### interest - -[hledger-interest](http://hackage.haskell.org/package/hledger-interest) -generates interest transactions for an account according to various schemes. - - - - - - - - - - -### stockquotes - -[hledger-stockquotes](http://hackage.haskell.org/package/hledger-stockquotes) -downloads market prices for the commodities in your journal from AlphaVantage. - - -A few more experimental or old add-ons can be found in hledger's bin/ -directory. These are typically prototypes and not guaranteed to work. # ENVIRONMENT