From f8e34e8723ac36185cbfbed23ec0cba0de7eef2e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 31 May 2023 18:42:29 -1000 Subject: [PATCH] ;doc:journal: improve virtual postings doc, mention inferring zero --- hledger/hledger.m4.md | 32 +++++++++++--------------------- 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index ec09b1eb0..3191c397a 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -2670,22 +2670,17 @@ hledger ignores these. ### Virtual postings -A posting with parentheses around the account name is called a *virtual posting* or *unbalanced posting*, -which means it is exempt from the usual rule that a transaction's postings must balance add up to zero. +A posting with parentheses around the account name (`(some:account)`) is called a *unbalanced virtual posting*. +Such postings do not participate in transaction balancing. +(And if you write them without an amount, a zero amount is always inferred.) +These can occasionally be convenient for special circumstances, +but they violate double entry bookkeeping and make your data less portable across applications, +so many people avoid using them at all. -This is not part of double entry bookkeeping, so you might choose to avoid this feature. -Or you can use it sparingly for certain special cases where it can be convenient. -Eg, you could set opening balances without using a balancing equity account: - -```journal -2022-01-01 opening balances - (assets:checking) $1000 - (assets:savings) $2000 -``` - -A posting with brackets around the account name is called a *balanced virtual posting*. -The balanced virtual postings in a transaction must add up to zero (separately from other postings). -Eg: +A posting with brackets around the account name (`[some:account]`) is called a *balanced virtual posting*. +The balanced virtual postings in a transaction must add up to zero, just like ordinary postings, +but separately from them. These are not part of double entry bookkeeping either, but they are at +least balanced. An example: ```journal 2022-01-01 buy food with cash, update budget envelope subaccounts, & something else @@ -2697,14 +2692,9 @@ Eg: (something:else) $5 ; <- this is not required to balance ``` -Postings whose account names are neither parenthesised nor bracketed are called *real postings*. +Ordinary postings, whose account names are neither parenthesised nor bracketed, are called *real postings*. You can exclude virtual postings from reports with the `-R/--real` flag or a `real:1` query. -Downsides: violates double entry bookkeeping, -can be used to avoid figuring out correct entries, -makes your financial data less portable and less trustworthy in an audit. - - ### Other Ledger directives These other Ledger directives are currently accepted but ignored.