From 54571ede209a8a9cad7d8e6611de76512454014c Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 3 Jun 2016 10:21:09 -0700 Subject: [PATCH] doc: journal: describe postings & their cleared flag --- hledger-lib/doc/hledger_journal.5 | 20 +++- hledger-lib/doc/hledger_journal.5.info | 140 +++++++++++++----------- hledger-lib/doc/hledger_journal.5.m4.md | 20 ++-- hledger-lib/doc/hledger_journal.5.txt | 20 +++- 4 files changed, 115 insertions(+), 85 deletions(-) diff --git a/hledger-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5 index 32e3cb9c6..32fdf8122 100644 --- a/hledger-lib/doc/hledger_journal.5 +++ b/hledger-lib/doc/hledger_journal.5 @@ -72,13 +72,21 @@ a transaction code (eg a check number), .IP \[bu] 2 and/or a description .PP -then some number of postings, of some amount to some account, each on -its own line. -Usually there are at least two postings, though one or even none is -possible. +then some number of postings, of some amount to some account. +Each posting is on its own line, consisting of: +.IP \[bu] 2 +indentation of one or more spaces (or tabs) +.IP \[bu] 2 +optionally, a \f[C]!\f[] or \f[C]*\f[] status flag followed by a space +.IP \[bu] 2 +an account name, optionally containing single spaces +.IP \[bu] 2 +optionally, two or more spaces or tabs followed by an amount .PP -The (real) posting amounts within a transaction must always balance, ie -add up to 0. +Usually there are two or more postings, though one or none is also +possible. +The posting amounts within a transaction must always balance, ie add up +to 0. Optionally one amount can be left blank, in which case it will be inferred. .SS Dates diff --git a/hledger-lib/doc/hledger_journal.5.info b/hledger-lib/doc/hledger_journal.5.info index ba97eb4a5..2db81a986 100644 --- a/hledger-lib/doc/hledger_journal.5.info +++ b/hledger-lib/doc/hledger_journal.5.info @@ -92,11 +92,19 @@ between them: * and/or a description - then some number of postings, of some amount to some account, each on -its own line. Usually there are at least two postings, though one or -even none is possible. + then some number of postings, of some amount to some account. Each +posting is on its own line, consisting of: - The (real) posting amounts within a transaction must always balance, + * indentation of one or more spaces (or tabs) + + * optionally, a `!' or `*' status flag followed by a space + + * an account name, optionally containing single spaces + + * optionally, two or more spaces or tabs followed by an amount + + Usually there are two or more postings, though one or none is also +possible. The posting amounts within a transaction must always balance, ie add up to 0. Optionally one amount can be left blank, in which case it will be inferred. @@ -912,67 +920,67 @@ Node: FILE FORMAT2286 Ref: #file-format2412 Node: Transactions2571 Ref: #transactions2691 -Node: Dates3377 -Ref: #dates3505 -Node: Simple dates3570 -Ref: #simple-dates3698 -Node: Secondary dates4062 -Ref: #secondary-dates4218 -Node: Posting dates5779 -Ref: #posting-dates5910 -Node: Account names7281 -Ref: #account-names7420 -Node: Amounts7905 -Ref: #amounts8043 -Node: Virtual Postings10041 -Ref: #virtual-postings10202 -Node: Balance Assertions11422 -Ref: #balance-assertions11586 -Node: Assertions and ordering12408 -Ref: #assertions-and-ordering12593 -Node: Assertions and commodities13624 -Ref: #assertions-and-commodities13850 -Node: Assertions and subaccounts14542 -Ref: #assertions-and-subaccounts14776 -Node: Assertions and virtual postings15298 -Ref: #assertions-and-virtual-postings15507 -Node: Prices15648 -Ref: #prices15780 -Node: Transaction prices15831 -Ref: #transaction-prices15976 -Node: Market prices17583 -Ref: #market-prices17718 -Node: Comments18606 -Ref: #comments18728 -Node: Tags19840 -Ref: #tags19958 -Node: Directives20881 -Ref: #directives20996 -Node: Account aliases21189 -Ref: #account-aliases21335 -Node: Basic aliases21937 -Ref: #basic-aliases22082 -Node: Regex aliases22770 -Ref: #regex-aliases22940 -Node: Multiple aliases23710 -Ref: #multiple-aliases23884 -Node: end aliases24380 -Ref: #end-aliases24522 -Node: account directive24624 -Ref: #account-directive24806 -Node: apply account directive25102 -Ref: #apply-account-directive25300 -Node: Multi-line comments25961 -Ref: #multi-line-comments26153 -Node: commodity directive26280 -Ref: #commodity-directive26466 -Node: Default commodity27339 -Ref: #default-commodity27514 -Node: Default year27835 -Ref: #default-year28002 -Node: Including other files28425 -Ref: #including-other-files28584 -Node: EDITOR SUPPORT28980 -Ref: #editor-support29100 +Node: Dates3634 +Ref: #dates3762 +Node: Simple dates3827 +Ref: #simple-dates3955 +Node: Secondary dates4319 +Ref: #secondary-dates4475 +Node: Posting dates6036 +Ref: #posting-dates6167 +Node: Account names7538 +Ref: #account-names7677 +Node: Amounts8162 +Ref: #amounts8300 +Node: Virtual Postings10298 +Ref: #virtual-postings10459 +Node: Balance Assertions11679 +Ref: #balance-assertions11843 +Node: Assertions and ordering12665 +Ref: #assertions-and-ordering12850 +Node: Assertions and commodities13881 +Ref: #assertions-and-commodities14107 +Node: Assertions and subaccounts14799 +Ref: #assertions-and-subaccounts15033 +Node: Assertions and virtual postings15555 +Ref: #assertions-and-virtual-postings15764 +Node: Prices15905 +Ref: #prices16037 +Node: Transaction prices16088 +Ref: #transaction-prices16233 +Node: Market prices17840 +Ref: #market-prices17975 +Node: Comments18863 +Ref: #comments18985 +Node: Tags20097 +Ref: #tags20215 +Node: Directives21138 +Ref: #directives21253 +Node: Account aliases21446 +Ref: #account-aliases21592 +Node: Basic aliases22194 +Ref: #basic-aliases22339 +Node: Regex aliases23027 +Ref: #regex-aliases23197 +Node: Multiple aliases23967 +Ref: #multiple-aliases24141 +Node: end aliases24637 +Ref: #end-aliases24779 +Node: account directive24881 +Ref: #account-directive25063 +Node: apply account directive25359 +Ref: #apply-account-directive25557 +Node: Multi-line comments26218 +Ref: #multi-line-comments26410 +Node: commodity directive26537 +Ref: #commodity-directive26723 +Node: Default commodity27596 +Ref: #default-commodity27771 +Node: Default year28092 +Ref: #default-year28259 +Node: Including other files28682 +Ref: #including-other-files28841 +Node: EDITOR SUPPORT29237 +Ref: #editor-support29357  End Tag Table diff --git a/hledger-lib/doc/hledger_journal.5.m4.md b/hledger-lib/doc/hledger_journal.5.m4.md index 54de184bd..62ef339d0 100644 --- a/hledger-lib/doc/hledger_journal.5.m4.md +++ b/hledger-lib/doc/hledger_journal.5.m4.md @@ -69,17 +69,23 @@ Transactions are represented by journal entries. Each begins with a [simple date](#simple-dates) in column 0, followed by three optional fields with spaces between them: -- a status flag, which can be empty or `!` or `*` (meaning "uncleared", "pending" and "cleared", or whatever you want) +- a status flag, which can be empty or `!` or `*` (meaning "uncleared", + "pending" and "cleared", or whatever you want) - a transaction code (eg a check number), - and/or a description -then some number of postings, of some amount to some account, each on -its own line. Usually there are at least two postings, though one or -even none is possible. +then some number of postings, of some amount to some account. Each +posting is on its own line, consisting of: -The ([real](#virtual-postings)) posting amounts within a transaction -must always balance, ie add up to 0. Optionally one amount can be -left blank, in which case it will be inferred. +- indentation of one or more spaces (or tabs) +- optionally, a `!` or `*` status flag followed by a space +- an account name, optionally containing single spaces +- optionally, two or more spaces or tabs followed by an amount + +Usually there are two or more postings, though one or none is also +possible. The posting amounts within a transaction must always balance, +ie add up to 0. Optionally one amount can be left blank, in which case +it will be inferred. ## Dates diff --git a/hledger-lib/doc/hledger_journal.5.txt b/hledger-lib/doc/hledger_journal.5.txt index bf5eca0aa..8b4e35b55 100644 --- a/hledger-lib/doc/hledger_journal.5.txt +++ b/hledger-lib/doc/hledger_journal.5.txt @@ -64,13 +64,21 @@ FFIILLEE FFOORRMMAATT +o and/or a description - then some number of postings, of some amount to some account, each on - its own line. Usually there are at least two postings, though one or - even none is possible. + then some number of postings, of some amount to some account. Each + posting is on its own line, consisting of: - The (real) posting amounts within a transaction must always balance, ie - add up to 0. Optionally one amount can be left blank, in which case it - will be inferred. + +o indentation of one or more spaces (or tabs) + + +o optionally, a ! or * status flag followed by a space + + +o an account name, optionally containing single spaces + + +o optionally, two or more spaces or tabs followed by an amount + + Usually there are two or more postings, though one or none is also pos- + sible. The posting amounts within a transaction must always balance, + ie add up to 0. Optionally one amount can be left blank, in which case + it will be inferred. DDaatteess SSiimmppllee ddaatteess