diff --git a/hledger-lib/doc/hledger_csv.5 b/hledger-lib/doc/hledger_csv.5 index 8918f599f..1a51534fe 100644 --- a/hledger-lib/doc/hledger_csv.5 +++ b/hledger-lib/doc/hledger_csv.5 @@ -199,39 +199,54 @@ include\ common.rules .PP \f[C]newest\-first\f[] .PP -Consider adding this rule if: your CSV records are in reverse +Consider adding this rule if all of the following are true: you might be +processing just one day of data, your CSV records are in reverse chronological order (newest first), and you care about preserving the -order of same\-day transactions, and you might be processing just one -day of data. +order of same\-day transactions. It usually isn\[aq]t needed, because hledger autodetects the CSV order, -but if all the CSV records have the same date it assumes they are oldest -first. +but when all CSV records have the same date it will assume they are +oldest first. .SH CSV TIPS -.PP -Each generated journal entry will have two postings, to -\f[C]account1\f[] and \f[C]account2\f[] respectively. -Currently it\[aq]s not possible to generate entries with more than two -postings. -.PP -If the CSV has debit/credit amounts in separate fields, assign to the -\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead of -\f[C]amount\f[]. -.PP -If the CSV has the currency in a separate field, assign that to the -\f[C]currency\f[] pseudo field which will be automatically prepended to -the amount. -(Or you can do the same thing with a field assignment.) -.PP -If the CSV includes a running balance, you can assign that to the -\f[C]balance\f[] pseudo field to generate a balance assertion on -\f[C]account1\f[] whenever the balance field is non\-empty. -(Eg to double\-check your bank\[aq]s balance calculation.) -.PP -If an amount value is parenthesised, it will be de\-parenthesised and -sign\-flipped automatically. +.SS CSV ordering .PP The generated journal entries will be sorted by date. -The original order of same\-day entries will be preserved, usually. +The order of same\-day entries will be preserved (except in the special +case where you might need \f[C]newest\-first\f[], see above). +.SS CSV accounts +.PP +Each journal entry will have two postings, to \f[C]account1\f[] and +\f[C]account2\f[] respectively. +It\[aq]s not yet possible to generate entries with more than two +postings. +It\[aq]s conventional and recommended to use \f[C]account1\f[] for the +account whose CSV we are reading. +.SS CSV amounts +.PP +The \f[C]amount\f[] field sets the amount of the \f[C]account1\f[] +posting. +.PP +If the CSV has debit/credit amounts in separate fields, assign to the +\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead. +(Whichever one has a value will be used, with appropriate sign. +If both contain a value, it may not work so well.) +.PP +If an amount value is parenthesised, it will be de\-parenthesised and +sign\-flipped. +.PP +If an amount value begins with a double minus sign, those will cancel +out and be removed. +.PP +If the CSV has the currency symbol in a separate field, assign that to +the \f[C]currency\f[] pseudo field to have it prepended to the amount. +Or, you can use a field assignment to \f[C]amount\f[] that interpolates +both CSV fields (giving more control, eg to put the currency symbol on +the right). +.SS CSV balance assertions +.PP +If the CSV includes a running balance, you can assign that to the +\f[C]balance\f[] pseudo field; whenever the running balance value is +non\-empty, it will be asserted as the balance after the +\f[C]account1\f[] posting. .SH "REPORTING BUGS" diff --git a/hledger-lib/doc/hledger_csv.5.info b/hledger-lib/doc/hledger_csv.5.info index 289816ef9..e2c57e859 100644 --- a/hledger-lib/doc/hledger_csv.5.info +++ b/hledger-lib/doc/hledger_csv.5.info @@ -179,12 +179,12 @@ File: hledger_csv.5.info, Node: newest-first, Prev: include, Up: CSV RULES 'newest-first' - Consider adding this rule if: your CSV records are in reverse + Consider adding this rule if all of the following are true: you might +be processing just one day of data, your CSV records are in reverse chronological order (newest first), and you care about preserving the -order of same-day transactions, and you might be processing just one day -of data. It usually isn't needed, because hledger autodetects the CSV -order, but if all the CSV records have the same date it assumes they are -oldest first. +order of same-day transactions. It usually isn't needed, because +hledger autodetects the CSV order, but when all CSV records have the +same date it will assume they are oldest first.  File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top @@ -192,27 +192,68 @@ File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top 2 CSV TIPS ********** -Each generated journal entry will have two postings, to 'account1' and -'account2' respectively. Currently it's not possible to generate -entries with more than two postings. +* Menu: + +* CSV ordering:: +* CSV accounts:: +* CSV amounts:: +* CSV balance assertions:: + + +File: hledger_csv.5.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS + +2.1 CSV ordering +================ + +The generated journal entries will be sorted by date. The order of +same-day entries will be preserved (except in the special case where you +might need 'newest-first', see above). + + +File: hledger_csv.5.info, Node: CSV accounts, Next: CSV amounts, Prev: CSV ordering, Up: CSV TIPS + +2.2 CSV accounts +================ + +Each journal entry will have two postings, to 'account1' and 'account2' +respectively. It's not yet possible to generate entries with more than +two postings. It's conventional and recommended to use 'account1' for +the account whose CSV we are reading. + + +File: hledger_csv.5.info, Node: CSV amounts, Next: CSV balance assertions, Prev: CSV accounts, Up: CSV TIPS + +2.3 CSV amounts +=============== + +The 'amount' field sets the amount of the 'account1' posting. If the CSV has debit/credit amounts in separate fields, assign to the -'amount-in' and 'amount-out' pseudo fields instead of 'amount'. - - If the CSV has the currency in a separate field, assign that to the -'currency' pseudo field which will be automatically prepended to the -amount. (Or you can do the same thing with a field assignment.) - - If the CSV includes a running balance, you can assign that to the -'balance' pseudo field to generate a balance assertion on 'account1' -whenever the balance field is non-empty. (Eg to double-check your -bank's balance calculation.) +'amount-in' and 'amount-out' pseudo fields instead. (Whichever one has +a value will be used, with appropriate sign. If both contain a value, +it may not work so well.) If an amount value is parenthesised, it will be de-parenthesised and -sign-flipped automatically. +sign-flipped. - The generated journal entries will be sorted by date. The original -order of same-day entries will be preserved, usually. + If an amount value begins with a double minus sign, those will cancel +out and be removed. + + If the CSV has the currency symbol in a separate field, assign that +to the 'currency' pseudo field to have it prepended to the amount. Or, +you can use a field assignment to 'amount' that interpolates both CSV +fields (giving more control, eg to put the currency symbol on the +right). + + +File: hledger_csv.5.info, Node: CSV balance assertions, Prev: CSV amounts, Up: CSV TIPS + +2.4 CSV balance assertions +========================== + +If the CSV includes a running balance, you can assign that to the +'balance' pseudo field; whenever the running balance value is non-empty, +it will be asserted as the balance after the 'account1' posting.  Tag Table: @@ -233,7 +274,15 @@ Node: include4648 Ref: #include4780 Node: newest-first5011 Ref: #newest-first5127 -Node: CSV TIPS5510 -Ref: #csv-tips5606 +Node: CSV TIPS5538 +Ref: #csv-tips5634 +Node: CSV ordering5721 +Ref: #csv-ordering5841 +Node: CSV accounts6022 +Ref: #csv-accounts6162 +Node: CSV amounts6416 +Ref: #csv-amounts6564 +Node: CSV balance assertions7339 +Ref: #csv-balance-assertions7488  End Tag Table diff --git a/hledger-lib/doc/hledger_csv.5.m4.md b/hledger-lib/doc/hledger_csv.5.m4.md index 40965eb57..61dd73b8b 100644 --- a/hledger-lib/doc/hledger_csv.5.m4.md +++ b/hledger-lib/doc/hledger_csv.5.m4.md @@ -161,31 +161,45 @@ include common.rules `newest-first` -Consider adding this rule if: +Consider adding this rule if all of the following are true: +you might be processing just one day of data, your CSV records are in reverse chronological order (newest first), -and you care about preserving the order of same-day transactions, -and you might be processing just one day of data. +and you care about preserving the order of same-day transactions. It usually isn't needed, because hledger autodetects the CSV order, -but if all the CSV records have the same date it assumes they are oldest first. +but when all CSV records have the same date it will assume they are oldest first. # CSV TIPS -Each generated journal entry will have two postings, to `account1` and `account2` respectively. -Currently it's not possible to generate entries with more than two postings. +## CSV ordering -If the CSV has debit/credit amounts in separate fields, assign to the `amount-in` and `amount-out` pseudo fields instead of `amount`. +The generated [journal entries](/journal.html#transactions) will be sorted by date. +The order of same-day entries will be preserved +(except in the special case where you might need [`newest-first`](#newest-first), see above). -If the CSV has the currency in a separate field, assign that to the `currency` pseudo field which will be automatically prepended to the amount. -(Or you can do the same thing with a field assignment.) +## CSV accounts -If the CSV includes a running balance, you can assign that to the `balance` pseudo field -to generate a [balance assertion](/journal.html#balance-assertions) on `account1` -whenever the balance field is non-empty. -(Eg to double-check your bank's balance calculation.) +Each journal entry will have two [postings](/journal.html#postings), to `account1` and `account2` respectively. +It's not yet possible to generate entries with more than two postings. +It's conventional and recommended to use `account1` for the account whose CSV we are reading. -If an amount value is parenthesised, it will be de-parenthesised and sign-flipped automatically. +## CSV amounts -The generated journal entries will be sorted by date. -The original order of same-day entries will be preserved, usually. - +The `amount` field sets the [amount](/journal.html#amounts) of the `account1` posting. +If the CSV has debit/credit amounts in separate fields, assign to the `amount-in` and `amount-out` pseudo fields instead. +(Whichever one has a value will be used, with appropriate sign. If both contain a value, it may not work so well.) + +If an amount value is parenthesised, it will be de-parenthesised and sign-flipped. + +If an amount value begins with a double minus sign, those will cancel out and be removed. + +If the CSV has the currency symbol in a separate field, +assign that to the `currency` pseudo field to have it prepended to the amount. +Or, you can use a [field assignment](#field-assignment) to `amount` that interpolates both CSV fields +(giving more control, eg to put the currency symbol on the right). + +## CSV balance assertions + +If the CSV includes a running balance, you can assign that to the `balance` pseudo field; +whenever the running balance value is non-empty, +it will be [asserted](/journal.html#balance-assertions) as the balance after the `account1` posting. diff --git a/hledger-lib/doc/hledger_csv.5.txt b/hledger-lib/doc/hledger_csv.5.txt index dd5ba3ac4..38f6eb55b 100644 --- a/hledger-lib/doc/hledger_csv.5.txt +++ b/hledger-lib/doc/hledger_csv.5.txt @@ -126,40 +126,53 @@ CSV RULES newest-first newest-first - Consider adding this rule if: your CSV records are in reverse chrono- - logical order (newest first), and you care about preserving the order - of same-day transactions, and you might be processing just one day of - data. It usually isn't needed, because hledger autodetects the CSV - order, but if all the CSV records have the same date it assumes they - are oldest first. + Consider adding this rule if all of the following are true: you might + be processing just one day of data, your CSV records are in reverse + chronological order (newest first), and you care about preserving the + order of same-day transactions. It usually isn't needed, because + hledger autodetects the CSV order, but when all CSV records have the + same date it will assume they are oldest first. CSV TIPS - Each generated journal entry will have two postings, to account1 and - account2 respectively. Currently it's not possible to generate entries - with more than two postings. + CSV ordering + The generated journal entries will be sorted by date. The order of + same-day entries will be preserved (except in the special case where + you might need newest-first, see above). - If the CSV has debit/credit amounts in separate fields, assign to the - amount-in and amount-out pseudo fields instead of amount. + CSV accounts + Each journal entry will have two postings, to account1 and account2 + respectively. It's not yet possible to generate entries with more than + two postings. It's conventional and recommended to use account1 for + the account whose CSV we are reading. - If the CSV has the currency in a separate field, assign that to the - currency pseudo field which will be automatically prepended to the - amount. (Or you can do the same thing with a field assignment.) + CSV amounts + The amount field sets the amount of the account1 posting. - If the CSV includes a running balance, you can assign that to the bal- - ance pseudo field to generate a balance assertion on account1 whenever - the balance field is non-empty. (Eg to double-check your bank's bal- - ance calculation.) + If the CSV has debit/credit amounts in separate fields, assign to the + amount-in and amount-out pseudo fields instead. (Whichever one has a + value will be used, with appropriate sign. If both contain a value, it + may not work so well.) If an amount value is parenthesised, it will be de-parenthesised and - sign-flipped automatically. + sign-flipped. - The generated journal entries will be sorted by date. The original - order of same-day entries will be preserved, usually. + If an amount value begins with a double minus sign, those will cancel + out and be removed. + + If the CSV has the currency symbol in a separate field, assign that to + the currency pseudo field to have it prepended to the amount. Or, you + can use a field assignment to amount that interpolates both CSV fields + (giving more control, eg to put the currency symbol on the right). + + CSV balance assertions + If the CSV includes a running balance, you can assign that to the bal- + ance pseudo field; whenever the running balance value is non-empty, it + will be asserted as the balance after the account1 posting. 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) @@ -173,7 +186,7 @@ COPYRIGHT 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- dot(5), ledger(1)