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

update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2018-06-08 19:52:45 -07:00
parent e3507ad944
commit 57f41697ba
3 changed files with 219 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
hledger-lib/hledger_journal.5
View File

@ -1218,48 +1218,88 @@ Prior to hledger 1.0, legacy \f[C]account\f[] and \f[C]end\f[] spellings
were also supported. were also supported.
.SS Periodic transactions .SS Periodic transactions
.PP .PP
Periodic transaction rules (enabled by \f[C]\-\-forecast\f[] or Periodic transaction rules describe transactions that recur.
\f[C]\-\-budget\f[]) describe recurring transactions. They allow you to generate future transactions for forecast reports
They look like a transaction where the first line is a tilde (with \f[C]\-\-forecast\f[]), without having to write them out
(\f[C]~\f[]) followed by a period expression (mnemonic: \f[C]~\f[] is explicitly in the journal.
like a recurring sine wave): Secondly, they also can be used to define budget goals (with
\f[C]\-\-budget\f[]).
.PP
A periodic transaction rule looks like a regular journal entry, with the
date replaced by a tilde (\f[C]~\f[]) followed by a period expression
(mnemonic: \f[C]~\f[] looks like a repeating sine wave):
.IP .IP
.nf .nf
\f[C] \f[C]
~\ weekly ~\ monthly
\ \ assets:bank:checking\ \ \ $400\ ;\ paycheck \ \ \ \ expenses:rent\ \ \ \ \ \ \ \ \ \ $2000
\ \ income:acme\ inc \ \ \ \ assets:bank:checking
\f[] \f[]
.fi .fi
.PP .PP
Periodic transactions have a dual purpose: There is an additional constraint on the period expression: the start
.IP \[bu] 2 date must fall on a natural boundary of the interval.
With \f[C]\-\-forecast\f[], each periodic transaction rule generates Eg \f[C]monthly\ from\ 2018/1/1\f[] is valid, but
future transactions, recurring at the specified interval, which can be \f[C]monthly\ from\ 2018/1/15\f[] is not.
seen in reports.
Forecast transactions begin the day after the latest recorded journal
transaction (or today, if there are no transactions) and end 6 months
from today (or at the report end date, if specified).
.IP \[bu] 2
With \f[C]\-\-budget\f[] (supported by the balance command), each
periodic transaction rule declares recurring budget goals for the
specified accounts, which can be seen in budget reports.
Eg the example above declares the goal of receiving $400 from
\f[C]income:acme\ inc\f[] (and also, depositing $400 into
\f[C]assets:bank:checking\f[]) every week.
.PP .PP
(Actually, you can generate one\-off transactions too, by writing a Also, if you write a transaction description or same\-line comment, it
period expression with no report interval.) must be separated from the period expression by \f[B]two or more
spaces\f[].
Eg:
.IP
.nf
\f[C]
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2\ or\ more\ spaces
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||
;\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ vv
~\ every\ 2\ weeks\ from\ 2018/6\ to\ 2018/9\ \ paycheck
\ \ \ \ assets:bank:checking\ \ \ $1500
\ \ \ \ income:acme\ inc
\f[]
.fi
.SS Generating forecasts with periodic transactions
.PP
With the \f[C]\-\-forecast\f[] flag, each periodic transaction rule
generates future transactions recurring at the specified interval,
beginning the day after the latest recorded journal transaction (or
today, if there are no transactions), and ending 6 months from today (or
at the report end date, if specified).
The generated transactions will appear in all reports.
They will have a \[lq]recur:\[rq] transaction tag added, with the
generating period expression as its value.
.PP
This can be useful for forecasting balances into the future, and
experimenting with different scenarios, without having to write a lot of
journal entries.
It can also help with data entry (describe most of your transactions
with periodic rules, and every so often copy the output of
\f[C]print\ \-\-forecast\f[] to the journal).
.PP
You can generate one\-time transactions too; 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 once the actual transaction (or any other
transaction on or after that date) is recorded.
.SS Setting budget goals with periodic transactions
.PP
With the \f[C]\-\-budget\f[] flag, currently supported by the balance
command, each periodic transaction rule declares recurring budget goals
for the specified accounts.
Eg the first example above declares a goal of spending $2000 on rent
(and also, a goal of depositing $2000 into checking) every month.
Goals and actual performance can then be compared in budget reports.
.PP .PP
For more details, see: balance: Budget report and Cookbook: Budgeting For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting. and Forecasting.
.SS Automated postings .SS Automated postings
.PP .PP
Automated postings (enabled by \f[C]\-\-auto\f[]) are postings added Automated posting rules describe extra postings that should be added to
automatically by rule to certain transactions. certain transactions at report time, when the \f[C]\-\-auto\f[] flag is
An automated posting rule looks like a transaction where the first line used.
is an equal sign (\f[C]=\f[]) followed by a query (mnemonic: \f[C]=\f[] .PP
tests for matching transactions, and also looks like posting lines): An automated posting rule looks like a regular journal entry, except the
first line is an equal sign (\f[C]=\f[]) followed by a query (mnemonic:
\f[C]=\f[] looks like posting lines):
.IP .IP
.nf .nf
\f[C] \f[C]

111
hledger-lib/hledger_journal.info
View File

@ -1127,32 +1127,78 @@ File: hledger_journal.info, Node: Periodic transactions, Next: Automated posti
1.15 Periodic transactions 1.15 Periodic transactions
========================== ==========================
Periodic transaction rules (enabled by '--forecast' or '--budget') Periodic transaction rules describe transactions that recur. They allow
describe recurring transactions. They look like a transaction where the you to generate future transactions for forecast reports (with
first line is a tilde ('~') followed by a period expression (mnemonic: '--forecast'), without having to write them out explicitly in the
'~' is like a recurring sine wave): journal. Secondly, they also can be used to define budget goals (with
'--budget').
~ weekly A periodic transaction rule looks like a regular journal entry, with
assets:bank:checking $400 ; paycheck the date replaced by a tilde ('~') followed by a period expression
income:acme inc (mnemonic: '~' looks like a repeating sine wave):
Periodic transactions have a dual purpose: ~ monthly
expenses:rent $2000
assets:bank:checking
* With '--forecast', each periodic transaction rule generates future There is an additional constraint on the period expression: the start
transactions, recurring at the specified interval, which can be date must fall on a natural boundary of the interval. Eg 'monthly from
seen in reports. Forecast transactions begin the day after the 2018/1/1' is valid, but 'monthly from 2018/1/15' is not.
latest recorded journal transaction (or today, if there are no
transactions) and end 6 months from today (or at the report end
date, if specified).
* With '--budget' (supported by the balance command), each periodic Also, if you write a transaction description or same-line comment, it
transaction rule declares recurring budget goals for the specified must be separated from the period expression by *two or more spaces*.
accounts, which can be seen in budget reports. Eg the example Eg:
above declares the goal of receiving $400 from 'income:acme inc'
(and also, depositing $400 into 'assets:bank:checking') every week.
(Actually, you can generate one-off transactions too, by writing a ; 2 or more spaces
period expression with no report interval.) ; ||
; vv
~ every 2 weeks from 2018/6 to 2018/9 paycheck
assets:bank:checking $1500
income:acme inc
* Menu:
* Generating forecasts with periodic transactions::
* Setting budget goals with periodic transactions::

File: hledger_journal.info, Node: Generating forecasts with periodic transactions, Next: Setting budget goals with periodic transactions, Up: Periodic transactions
1.15.1 Generating forecasts with periodic transactions
------------------------------------------------------
With the '--forecast' flag, each periodic transaction rule generates
future transactions recurring at the specified interval, beginning the
day after the latest recorded journal transaction (or today, if there
are no transactions), and ending 6 months from today (or at the report
end date, if specified). The generated transactions will appear in all
reports. 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, and
experimenting with different scenarios, without having to write a lot of
journal entries. It 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. You could use
this to forecast an estimated transaction, that is automatically
deactivated once the actual transaction (or any other transaction on or
after that date) is recorded.

File: hledger_journal.info, Node: Setting budget goals with periodic transactions, Prev: Generating forecasts with periodic transactions, Up: Periodic transactions
1.15.2 Setting budget goals with periodic transactions
------------------------------------------------------
With the '--budget' flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be
compared in budget reports.
For more details, see: balance: Budget report and Cookbook: Budgeting For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting. and Forecasting.
@ -1163,11 +1209,12 @@ File: hledger_journal.info, Node: Automated postings, Prev: Periodic transacti
1.16 Automated postings 1.16 Automated postings
======================= =======================
Automated postings (enabled by '--auto') are postings added Automated posting rules describe extra postings that should be added to
automatically by rule to certain transactions. An automated posting certain transactions at report time, when the '--auto' flag is used.
rule looks like a transaction where the first line is an equal sign
('=') followed by a query (mnemonic: '=' tests for matching An automated posting rule looks like a regular journal entry, except
transactions, and also looks like posting lines): the first line is an equal sign ('=') followed by a query (mnemonic: '='
looks like posting lines):
= expenses:gifts = expenses:gifts
budget:gifts *-1 budget:gifts *-1
@ -1308,9 +1355,13 @@ Node: Default parent account39362
Ref: #default-parent-account39530 Ref: #default-parent-account39530
Node: Periodic transactions40189 Node: Periodic transactions40189
Ref: #periodic-transactions40368 Ref: #periodic-transactions40368
Node: Automated postings41667 Node: Generating forecasts with periodic transactions41609
Ref: #automated-postings41821 Ref: #generating-forecasts-with-periodic-transactions41890
Node: EDITOR SUPPORT42954 Node: Setting budget goals with periodic transactions42983
Ref: #editor-support43072 Ref: #setting-budget-goals-with-periodic-transactions43264
Node: Automated postings43723
Ref: #automated-postings43877
Node: EDITOR SUPPORT45017
Ref: #editor-support45135
 
End Tag Table End Tag Table

104
hledger-lib/hledger_journal.txt
View File

@ -886,54 +886,86 @@ FILE FORMAT
ported. ported.
Periodic transactions Periodic transactions
Periodic transaction rules (enabled by --forecast or --budget) describe Periodic transaction rules describe transactions that recur. They
recurring transactions. They look like a transaction where the first allow you to generate future transactions for forecast reports (with
line is a tilde (~) followed by a period expression (mnemonic: ~ is --forecast), without having to write them out explicitly in the jour-
like a recurring sine wave): nal. Secondly, they also can be used to define budget goals (with
--budget).
~ weekly A periodic transaction rule looks like a regular journal entry, with
assets:bank:checking $400 ; paycheck the date replaced by a tilde (~) followed by a period expression
income:acme inc (mnemonic: ~ looks like a repeating sine wave):
Periodic transactions have a dual purpose: ~ monthly
expenses:rent $2000
assets:bank:checking
o With --forecast, each periodic transaction rule generates future There is an additional constraint on the period expression: the start
transactions, recurring at the specified interval, which can be seen date must fall on a natural boundary of the interval. Eg
in reports. Forecast transactions begin the day after the latest monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not.
recorded journal transaction (or today, if there are no transactions)
and end 6 months from today (or at the report end date, if speci-
fied).
o With --budget (supported by the balance command), each periodic Also, if you write a transaction description or same-line comment, it
transaction rule declares recurring budget goals for the specified must be separated from the period expression by two or more spaces.
accounts, which can be seen in budget reports. Eg the example above Eg:
declares the goal of receiving $400 from income:acme inc (and also,
depositing $400 into assets:bank:checking) every week.
(Actually, you can generate one-off transactions too, by writing a ; 2 or more spaces
period expression with no report interval.) ; ||
; vv
~ every 2 weeks from 2018/6 to 2018/9 paycheck
assets:bank:checking $1500
income:acme inc
Generating forecasts with periodic transactions
With the --forecast flag, each periodic transaction rule generates
future transactions recurring at the specified interval, beginning the
day after the latest recorded journal transaction (or today, if there
are no transactions), and ending 6 months from today (or at the report
end date, if specified). The generated transactions will appear in all
reports. 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, and exper-
imenting with different scenarios, without having to write a lot of
journal entries. It can also help with data entry (describe most of
your transactions with periodic rules, and every so often copy the out-
put of print --forecast to the journal).
You can generate one-time transactions too; just write a period expres-
sion specifying a date with no report interval. You could use this to
forecast an estimated transaction, that is automatically deactivated
once the actual transaction (or any other transaction on or after that
date) is recorded.
Setting budget goals with periodic transactions
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
pared in budget reports.
For more details, see: balance: Budget report and Cookbook: Budgeting For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting. and Forecasting.
Automated postings Automated postings
Automated postings (enabled by --auto) are postings added automatically Automated posting rules describe extra postings that should be added to
by rule to certain transactions. An automated posting rule looks like certain transactions at report time, when the --auto flag is used.
a transaction where the first line is an equal sign (=) followed by a
query (mnemonic: = tests for matching transactions, and also looks like An automated posting rule looks like a regular journal entry, except
posting lines): the first line is an equal sign (=) followed by a query (mnemonic: =
looks like posting lines):
= expenses:gifts = expenses:gifts
budget:gifts *-1 budget:gifts *-1
assets:budget *1 assets:budget *1
The posting amounts can be of the form *N, which means "the amount of The posting amounts can be of the form *N, which means "the amount of
the matched transaction's first posting, multiplied by N". They can the matched transaction's first posting, multiplied by N". They can
also be ordinary fixed amounts. Fixed amounts with no commodity symbol also be ordinary fixed amounts. Fixed amounts with no commodity symbol
will be given the same commodity as the matched transaction's first will be given the same commodity as the matched transaction's first
posting. posting.
This example adds a corresponding (unbalanced) budget posting to every This example adds a corresponding (unbalanced) budget posting to every
transaction involving the expenses:gifts account: transaction involving the expenses:gifts account:
= expenses:gifts = expenses:gifts
@ -949,16 +981,16 @@ FILE FORMAT
(budget:gifts) $-20 (budget:gifts) $-20
assets assets
Like postings recorded by hand, automated postings participate in Like postings recorded by hand, automated postings participate in
transaction balancing, missing amount inference and balance assertions. transaction balancing, missing amount inference and balance assertions.
EDITOR SUPPORT EDITOR SUPPORT
Add-on modes exist for various text editors, to make working with jour- Add-on modes exist for various text editors, to make working with jour-
nal files easier. They add colour, navigation aids and helpful com- nal files easier. They add colour, navigation aids and helpful com-
mands. For hledger users who edit the journal file directly (the mands. For hledger users who edit the journal file directly (the
majority), using one of these modes is quite recommended. majority), using one of these modes is quite recommended.
These were written with Ledger in mind, but also work with hledger These were written with Ledger in mind, but also work with hledger
files: files:
@ -977,7 +1009,7 @@ EDITOR SUPPORT
REPORTING BUGS REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list) or hledger mail list)
@ -991,7 +1023,7 @@ COPYRIGHT
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1) dot(5), ledger(1)