doc: rewrite commands intro; drop command docs from man page
This commit is contained in:
Simon Michael
parent
e406cebcce
commit
6b4be651af
@ -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_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_dnl include in web manuals only
|
||||
m4_define({{_notman_}}, m4_ifdef({{MAN}},,{{$1}}) )m4_dnl
|
||||
m4_define({{_web_}}, m4_ifdef({{WEB}},{{$1}}) )m4_dnl
|
||||
m4_dnl include in info manuals only
|
||||
m4_define({{_notweb_}}, m4_ifdef({{WEB}},,{{$1}}) )m4_dnl
|
||||
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_define({{_notinfo_}}, m4_ifdef({{INFO}},,{{$1}}) )m4_dnl
|
||||
m4_dnl
|
||||
m4_dnl Two side-by-side columns.
|
||||
m4_define({{_col2_}},
|
||||
|
||||
@ -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`
|
||||
<!-- - man pages, eg: `man hledger-balance` -->
|
||||
- info manuals, eg: `hledger help --info hledger` -> Commands -> balance
|
||||
- web manuals, eg: <https://hledger.org/hledger.html#balance>
|
||||
|
||||
## 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)*
|
||||
|
||||
<!-- ### autosync -->
|
||||
|
||||
<!-- [hledger-autosync](https://github.com/simonmichael/hledger/blob/master/bin/hledger-autosync) -->
|
||||
<!-- is a symbolic link for easily running -->
|
||||
<!-- [ledger-autosync](https://pypi.python.org/pypi/ledger-autosync) if you make a symbolic -->
|
||||
<!-- ledger-autosync does deduplicating conversion of OFX data and some CSV formats, -->
|
||||
<!-- and can also download the data -->
|
||||
<!-- [if your bank offers OFX Direct Connect](http://wiki.gnucash.org/wiki/OFX_Direct_Connect_Bank_Settings). -->
|
||||
|
||||
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.
|
||||
|
||||
<!-- ### autosync -->
|
||||
|
||||
<!-- [hledger-autosync](https://github.com/simonmichael/hledger/blob/master/bin/hledger-autosync) -->
|
||||
<!-- is a symbolic link for easily running -->
|
||||
<!-- [ledger-autosync](https://pypi.python.org/pypi/ledger-autosync) if you make a symbolic -->
|
||||
<!-- ledger-autosync does deduplicating conversion of OFX data and some CSV formats, -->
|
||||
<!-- and can also download the data -->
|
||||
<!-- [if your bank offers OFX Direct Connect](http://wiki.gnucash.org/wiki/OFX_Direct_Connect_Bank_Settings). -->
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user