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

;doc: journal: periodic transactions: more fixes, clarifications

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-09-09 07:45:09 -07:00
parent 901e5174d7
commit 94d3eb1cfb
1 changed files with 20 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1163,16 +1163,22 @@ They allow you to generate future transactions for forecasting,
without having to write them out explicitly in the journal (with `--forecast`). 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`).
These can be a little tricky, so take note of these tips before you move on: These can be a little tricky, so before you use them, read this whole section - or at least these tips:
1. Two spaces accidentally added or omitted will cause you trouble - read about this below. 1. Two spaces accidentally added or omitted will cause you trouble - read about this below.
2. For troubleshooting, use `print --forecast tag:generated` or `register --forecast tag:generated` to see the generated transactions. 2. For troubleshooting, show the generated transactions with `hledger print --forecast tag:generated` or `hledger register --forecast tag:generated`.
3. [period expressions](hledger.html#period-expressions) can be tricky. Their documentation needs improvement, but is worth studying. 3. Forecasted transactions will begin only after the last non-forecasted transaction's date.
4. Some period expressions with a repeating interval must begin on a natural boundary of that interval. Eg in `weekly from DATE`, DATE must be a monday; `~ weekly from 2019/9/8` will give an error. 4. Forecasted transactions will end 6 months from today, by default. See below for the exact start/end rules.
5. Other period expressions with an interval are automatically expanded to cover a whole number of that interval. 5. [period expressions](hledger.html#period-expressions) can be tricky. Their documentation needs improvement, but is worth studying.
(This is done for reporting purposes, but also affects periodic transactions.) 6. Some period expressions with a repeating interval must begin on a natural boundary of that interval.
Eg `~ every 10th day of month from 2020/01/10` starts on 2010/01/01, Eg in `weekly from DATE`, DATE must be a monday; `~ weekly from 2019/10/1` (a tuesday) will give an error.
but `~ every 10th day of month from 2020/01` will be adjusted to start on 2019/12/01. 7. Other period expressions with an interval are automatically expanded to cover a whole number of that interval.
(This is done for reporting purposes, but also affects periodic transactions. Yes, this is a bit inconsistent with the above, currently.)
Eg `~ every 10th day of month from 2020/01/10` starts on 2020/01/10,
but `~ every 10th day of month from 2020/01`, which is equivalent to `~ every 10th day of month from 2020/01/01`,
will be adjusted to start on 2019/12/10.
### Periodic rule syntax
A periodic transaction rule looks like a normal journal entry, A periodic transaction rule looks like a normal journal entry,
with the date replaced by a tilde (`~`) followed by a [period expression](hledger.html#period-expressions) with the date replaced by a tilde (`~`) followed by a [period expression](hledger.html#period-expressions)
@ -1190,7 +1196,7 @@ Partial or relative dates (M/D, D, tomorrow, last week) in the period expression
can work (useful or not). They will be relative to today's date, unless can work (useful or not). They will be relative to today's date, unless
a Y default year directive is in effect, in which case they will be relative to Y/1/1. a Y default year directive is in effect, in which case they will be relative to Y/1/1.
### Two spaces after the period expression ### Two spaces between period expression and description!
If the period expression is followed by a transaction description, If the period expression is followed by a transaction description,
these must be separated by **two or more spaces**. these must be separated by **two or more spaces**.
@ -1206,6 +1212,11 @@ can not accidentally alter their meaning, as in this example:
income:acme inc income:acme inc
``` ```
So,
- Do write two spaces between your period expression and your transaction description, if any.
- Don't accidentally write two spaces in the middle of your period expression.
### Forecasting with periodic transactions ### Forecasting with periodic transactions
With the `--forecast` flag, each periodic transaction rule generates With the `--forecast` flag, each periodic transaction rule generates