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_dnl Author to show in man pages.
|
||||||
m4_define({{_author_}}, {{}})m4_dnl
|
m4_define({{_author_}}, {{}})m4_dnl
|
||||||
m4_dnl
|
m4_dnl
|
||||||
m4_dnl Macros for conditionally including format-specific content
|
m4_dnl Macros for conditionally including or excluding content based on the format
|
||||||
m4_dnl $1 is the manual's web slug: hledger, hledger-ui, journal, csv etc.
|
m4_dnl (man, web or info).
|
||||||
m4_dnl include in man pages only
|
|
||||||
m4_define({{_man_}}, m4_ifdef({{MAN}},{{$1}}) )m4_dnl
|
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_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_define({{_info_}}, m4_ifdef({{INFO}},{{$1}}) )m4_dnl
|
||||||
m4_dnl include in text manuals only - not implemented
|
m4_define({{_notinfo_}}, m4_ifdef({{INFO}},,{{$1}}) )m4_dnl
|
||||||
m4_dnl m4_define({{_txt_}}, m4_ifdef({{TXT}},{{$1}}) )m4_dnl
|
|
||||||
m4_dnl
|
m4_dnl
|
||||||
m4_dnl Two side-by-side columns.
|
m4_dnl Two side-by-side columns.
|
||||||
m4_define({{_col2_}},
|
m4_define({{_col2_}},
|
||||||
|
|||||||
@ -1571,21 +1571,134 @@ Related:
|
|||||||
|
|
||||||
# COMMANDS
|
# COMMANDS
|
||||||
|
|
||||||
hledger provides a number of subcommands; `hledger` with no arguments
|
hledger provides a number of commands for producing reports and managing your data.
|
||||||
shows a list.
|
Run `hledger` with no arguments to list the commands available.
|
||||||
|
|
||||||
If you install additional `hledger-*` packages, or if you put programs
|
To run a command, write its name as hledger's first argument (eg: `hledger balance`).
|
||||||
or scripts named `hledger-NAME` in your PATH, these will also be
|
Or, you can write one of the standard short aliases which are
|
||||||
listed as subcommands.
|
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
|
Each command's detailed help is available as one or more of:
|
||||||
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`).
|
|
||||||
|
|
||||||
Here are all the builtin commands in alphabetical order.
|
- command line help, eg: `hledger balance --help`
|
||||||
See also `hledger` for a more organised command list,
|
<!-- - man pages, eg: `man hledger-balance` -->
|
||||||
and `hledger CMD -h` for detailed command help.
|
- 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
|
## accounts
|
||||||
|
|
||||||
@ -1707,67 +1820,8 @@ _include_({{Hledger/Cli/Commands/Tags.md}})
|
|||||||
|
|
||||||
_include_({{Hledger/Cli/Commands/Test.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
|
# ENVIRONMENT
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user