slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

lib: doc: journal: clarify periodic transactions

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2018-06-18 17:00:55 -07:00
parent c4d45cffc4
commit b04dc82125
1 changed files with 29 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
hledger-lib/hledger_journal.m4.md
View File

@ -916,11 +916,11 @@ Prior to hledger 1.0, legacy `account` and `end` spellings were also supported.
## Periodic transactions ## Periodic transactions
Periodic transaction rules describe transactions that recur. Periodic transaction rules describe transactions that recur.
They allow you to generate future transactions for forecast reports (with `--forecast`), They allow you to generate future transactions for forecasting,
without having to write them out explicitly in the journal. without having to write them out explicitly in the journal (with `--forecast`).
Secondly, they also can be used to define budget goals (with `--budget`). Secondly, they also can be used to define budget goals (with `--budget`).
A periodic transaction rule looks like a regular journal entry, A periodic transaction rule looks like a normal journal entry,
with the date replaced by a tilde (`~`) followed by a [period expression](manual.html#period-expressions) with the date replaced by a tilde (`~`) followed by a [period expression](manual.html#period-expressions)
(mnemonic: `~` looks like a repeating sine wave): (mnemonic: `~` looks like a repeating sine wave):
```journal ```journal
@ -932,9 +932,10 @@ There is an additional constraint on the period expression:
the start date must fall on a natural boundary of the interval. the start date must fall on a natural boundary of the interval.
Eg `monthly from 2018/1/1` is valid, but `monthly from 2018/1/15` is not. Eg `monthly from 2018/1/1` is valid, but `monthly from 2018/1/15` is not.
Also, if you write a transaction description or same-line comment, If you write a transaction description or same-line comment,
it must be separated from the period expression by **two or more spaces**. Eg: it must be separated from the period expression by **two or more spaces**. Eg:
```journal
```
; 2 or more spaces ; 2 or more spaces
; || ; ||
; vv ; vv
@ -943,24 +944,32 @@ it must be separated from the period expression by **two or more spaces**. Eg:
income:acme inc income:acme inc
``` ```
### Generating forecasts with periodic transactions ### Forecasting with periodic transactions
With the `--forecast` flag, With the `--forecast` flag, each periodic transaction rule generates
each periodic transaction rule generates future transactions recurring at the specified interval, future transactions recurring at the specified interval.
beginning the day after the latest recorded journal transaction (or today, if there are no transactions), These are not saved in the journal, but appear in all reports.
and ending 6 months from today (or at the report end date, if specified). They will look like normal transactions, but with an extra
The generated transactions will appear in all reports. [tag](manual.html#tags-1) named `recur`, whose value is the generating period expression.
They will have a "recur:" transaction tag added, with the generating period expression as its value.
This can be useful for forecasting balances into the future, Forecast transactions begin
and experimenting with different scenarios, without having to write a lot of journal entries. on or after the day after the latest normal (non-periodic) transaction in the journal,
It can also help with data entry (describe most of your transactions with periodic rules, or today if there are none.
and every so often copy the output of `print --forecast` to the journal).
You can generate one-time transactions too; They end on or before the report end date if specified, or 180 days from today if unspecified.
Forecasting can be useful for estimating balances into the future,
and experimenting with different scenarios.
Note the start date logic means that forecasted transactions are automatically replaced
by normal transactions as you add those.
Forecasting can also help with data entry:
describe most of your transactions with periodic rules,
and every so often copy the output of `print --forecast` to the journal.
You can generate one-time transactions too:
just write a period expression specifying a date with no report interval. just write a period expression specifying a date with no report interval.
You could use this to forecast an estimated transaction, that is automatically deactivated (You could also write a normal transaction with a future date, but remember this disables forecast transactions on previous dates.)
once the actual transaction (or any other transaction on or after that date) is recorded.
### Setting budget goals with periodic transactions ### Setting budget goals with periodic transactions
@ -980,7 +989,7 @@ and
Automated posting rules describe extra postings that should be added to certain transactions at report time, Automated posting rules describe extra postings that should be added to certain transactions at report time,
when the `--auto` flag is used. when the `--auto` flag is used.
An automated posting rule looks like a regular journal entry, An automated posting rule looks like a normal journal entry,
except the first line is an equal sign (`=`) followed by a [query](manual.html#queries) except the first line is an equal sign (`=`) followed by a [query](manual.html#queries)
(mnemonic: `=` looks like posting lines): (mnemonic: `=` looks like posting lines):
```journal ```journal