diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index 137404eb9..f1a710c22 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -487,34 +487,53 @@ hledger\[aq]s journal format. \f[C]description\f[R], \f[C]comment\f[R] can be used to form the transaction\[aq]s first line. .SS Posting field names +.SS account +.PP +\f[C]accountN\f[R], where N is 1 to 9, causes a posting to be generated, +with that account name. .PP -\f[C]accountN\f[R], where N is 1 to 9, generates a posting, with that -account name. Most often there are two postings, so you\[aq]ll want to set \f[C]account1\f[R] and \f[C]account2\f[R]. -If a posting\[aq]s account name is left unset but its amount is set, a -default account name will be chosen (like expenses:unknown or -income:unknown). +.PP +If a posting\[aq]s account name is left unset but its amount is set (see +below), a default account name will be chosen (like +\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]). +.SS amount .PP \f[C]amountN\f[R] sets posting N\[aq]s amount. -Or, \f[C]amount\f[R] with no N sets posting 1\[aq]s. -If the CSV has debits and credits in separate fields, use -\f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead. -Or \f[C]amount-in\f[R] and \f[C]amount-out\f[R] with no N for posting 1. .PP -For convenience and backwards compatibility, if you set the amount of -posting 1 only, a second posting with the negative amount will be -generated automatically. +Or if the CSV has debits and credits in two separate fields, use +\f[C]amountN-in\f[R] and \f[C]amountN-out\f[R] instead. +.PP +Some aliases and special behaviour exist to support older CSV rules +(before hledger 1.17): +.IP \[bu] 2 +if \f[C]amount1\f[R] is the only posting amount assigned, then a second +posting with the balancing amount will be generated automatically. (Unless the account name is parenthesised indicating an unbalanced posting.) +.IP \[bu] 2 +\f[C]amount\f[R] is an alias for \f[C]amount1\f[R] +.IP \[bu] 2 +\f[C]amount-in\f[R]/\f[C]amount-out\f[R] are aliases for +\f[C]amount1-in\f[R]/\f[C]amount1-out\f[R] .PP -If the CSV has the currency symbol in a separate field, you can use -\f[C]currencyN\f[R] to prepend it to posting N\[aq]s amount. -\f[C]currency\f[R] with no N affects ALL postings. +This can occasionally get in the way. +For example, currently it\[aq]s possible to generate a transaction with +a blank amount1, but not one with a blank amount2. +.SS currency +.PP +If the CSV has the currency symbol in a separate field (ie, not part of +the amount field), you can use \f[C]currencyN\f[R] to prepend it to +posting N\[aq]s amount. +Or, \f[C]currency\f[R] affects all postings. +.SS balance .PP \f[C]balanceN\f[R] sets a balance assertion amount (or if the posting amount is left empty, a balance assignment). -You may need to adjust this with the \f[C]balance-type\f[R] rule. +You may need to adjust this with the \f[C]balance-type\f[R] rule (see +below). +.SS comment .PP Finally, \f[C]commentN\f[R] sets a comment on the Nth posting. Comments can also contain tags, as usual. diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index 65bde531c..6ec76f934 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -451,31 +451,82 @@ File: hledger_csv.info, Node: Posting field names, Prev: Transaction field nam 2.2.2 Posting field names ------------------------- -'accountN', where N is 1 to 9, generates a posting, with that account -name. Most often there are two postings, so you'll want to set -'account1' and 'account2'. If a posting's account name is left unset -but its amount is set, a default account name will be chosen (like -expenses:unknown or income:unknown). +* Menu: - 'amountN' sets posting N's amount. Or, 'amount' with no N sets -posting 1's. If the CSV has debits and credits in separate fields, use -'amountN-in' and 'amountN-out' instead. Or 'amount-in' and 'amount-out' -with no N for posting 1. +* account:: +* amount:: +* currency:: +* balance:: +* comment:: - For convenience and backwards compatibility, if you set the amount of -posting 1 only, a second posting with the negative amount will be -generated automatically. (Unless the account name is parenthesised -indicating an unbalanced posting.) + +File: hledger_csv.info, Node: account, Next: amount, Up: Posting field names - If the CSV has the currency symbol in a separate field, you can use -'currencyN' to prepend it to posting N's amount. 'currency' with no N -affects ALL postings. +2.2.2.1 account +............... - 'balanceN' sets a balance assertion amount (or if the posting amount -is left empty, a balance assignment). You may need to adjust this with -the 'balance-type' rule. +'accountN', where N is 1 to 9, causes a posting to be generated, with +that account name. - Finally, 'commentN' sets a comment on the Nth posting. Comments can + Most often there are two postings, so you'll want to set 'account1' +and 'account2'. + + If a posting's account name is left unset but its amount is set (see +below), a default account name will be chosen (like "expenses:unknown" +or "income:unknown"). + + +File: hledger_csv.info, Node: amount, Next: currency, Prev: account, Up: Posting field names + +2.2.2.2 amount +.............. + +'amountN' sets posting N's amount. + + Or if the CSV has debits and credits in two separate fields, use +'amountN-in' and 'amountN-out' instead. + + Some aliases and special behaviour exist to support older CSV rules +(before hledger 1.17): + + * if 'amount1' is the only posting amount assigned, then a second + posting with the balancing amount will be generated automatically. + (Unless the account name is parenthesised indicating an unbalanced + posting.) + * 'amount' is an alias for 'amount1' + * 'amount-in'/'amount-out' are aliases for 'amount1-in'/'amount1-out' + + This can occasionally get in the way. For example, currently it's +possible to generate a transaction with a blank amount1, but not one +with a blank amount2. + + +File: hledger_csv.info, Node: currency, Next: balance, Prev: amount, Up: Posting field names + +2.2.2.3 currency +................ + +If the CSV has the currency symbol in a separate field (ie, not part of +the amount field), you can use 'currencyN' to prepend it to posting N's +amount. Or, 'currency' affects all postings. + + +File: hledger_csv.info, Node: balance, Next: comment, Prev: currency, Up: Posting field names + +2.2.2.4 balance +............... + +'balanceN' sets a balance assertion amount (or if the posting amount is +left empty, a balance assignment). You may need to adjust this with the +'balance-type' rule (see below). + + +File: hledger_csv.info, Node: comment, Prev: balance, Up: Posting field names + +2.2.2.5 comment +............... + +Finally, 'commentN' sets a comment on the Nth posting. Comments can also contain tags, as usual. See TIPS below for more about setting amounts and currency. @@ -991,44 +1042,54 @@ Node: Transaction field names16367 Ref: #transaction-field-names16527 Node: Posting field names16638 Ref: #posting-field-names16790 -Node: field assignment18081 -Ref: #field-assignment18224 -Node: separator19042 -Ref: #separator19171 -Node: if19582 -Ref: #if19684 -Node: end21603 -Ref: #end21709 -Node: date-format21933 -Ref: #date-format22065 -Node: newest-first22814 -Ref: #newest-first22952 -Node: include23635 -Ref: #include23764 -Node: balance-type24208 -Ref: #balance-type24328 -Node: TIPS25028 -Ref: #tips25110 -Node: Rapid feedback25366 -Ref: #rapid-feedback25483 -Node: Valid CSV25943 -Ref: #valid-csv26073 -Node: File Extension26265 -Ref: #file-extension26417 -Node: Reading multiple CSV files26827 -Ref: #reading-multiple-csv-files27012 -Node: Valid transactions27253 -Ref: #valid-transactions27431 -Node: Deduplicating importing28059 -Ref: #deduplicating-importing28238 -Node: Setting amounts29271 -Ref: #setting-amounts29440 -Node: Setting currency/commodity30426 -Ref: #setting-currencycommodity30618 -Node: Referencing other fields31421 -Ref: #referencing-other-fields31621 -Node: How CSV rules are evaluated32518 -Ref: #how-csv-rules-are-evaluated32691 +Node: account16860 +Ref: #account16976 +Node: amount17320 +Ref: #amount17451 +Node: currency18195 +Ref: #currency18330 +Node: balance18521 +Ref: #balance18655 +Node: comment18834 +Ref: #comment18951 +Node: field assignment19114 +Ref: #field-assignment19257 +Node: separator20075 +Ref: #separator20204 +Node: if20615 +Ref: #if20717 +Node: end22636 +Ref: #end22742 +Node: date-format22966 +Ref: #date-format23098 +Node: newest-first23847 +Ref: #newest-first23985 +Node: include24668 +Ref: #include24797 +Node: balance-type25241 +Ref: #balance-type25361 +Node: TIPS26061 +Ref: #tips26143 +Node: Rapid feedback26399 +Ref: #rapid-feedback26516 +Node: Valid CSV26976 +Ref: #valid-csv27106 +Node: File Extension27298 +Ref: #file-extension27450 +Node: Reading multiple CSV files27860 +Ref: #reading-multiple-csv-files28045 +Node: Valid transactions28286 +Ref: #valid-transactions28464 +Node: Deduplicating importing29092 +Ref: #deduplicating-importing29271 +Node: Setting amounts30304 +Ref: #setting-amounts30473 +Node: Setting currency/commodity31459 +Ref: #setting-currencycommodity31651 +Node: Referencing other fields32454 +Ref: #referencing-other-fields32654 +Node: How CSV rules are evaluated33551 +Ref: #how-csv-rules-are-evaluated33724  End Tag Table diff --git a/hledger-lib/hledger_csv.m4.md b/hledger-lib/hledger_csv.m4.md index 8162389df..99fd1186f 100644 --- a/hledger-lib/hledger_csv.m4.md +++ b/hledger-lib/hledger_csv.m4.md @@ -412,30 +412,46 @@ For more about the transaction parts they refer to, see the manual for hledger's ### Posting field names -`accountN`, where N is 1 to 9, generates a -[posting](journal.html#postings), with that account name. +#### account + +`accountN`, where N is 1 to 9, causes a [posting](journal.html#postings) to be generated, +with that account name. + Most often there are two postings, so you'll want to set `account1` and `account2`. -If a posting's account name is left unset but its amount is set, -a default account name will be chosen (like expenses:unknown or income:unknown). -`amountN` sets posting N's amount. Or, `amount` with no N sets posting -1's. If the CSV has debits and credits in separate fields, use -`amountN-in` and `amountN-out` instead. Or `amount-in` and -`amount-out` with no N for posting 1. +If a posting's account name is left unset but its amount is set (see below), +a default account name will be chosen (like "expenses:unknown" or "income:unknown"). -For convenience and backwards compatibility, if you set the amount of -posting 1 only, a second posting with the negative amount will be -generated automatically. -(Unless the account name is parenthesised indicating an -[unbalanced posting](journal.html#virtual-postings).) +#### amount -If the CSV has the currency symbol in a separate field, you can use -`currencyN` to prepend it to posting N's amount. `currency` with no N -affects ALL postings. +`amountN` sets posting N's amount. + +Or if the CSV has debits and credits in two separate fields, use `amountN-in` and `amountN-out` instead. + +Some aliases and special behaviour exist to support older CSV rules (before hledger 1.17): + +- if `amount1` is the only posting amount assigned, then a second posting + with the balancing amount will be generated automatically. + (Unless the account name is parenthesised indicating an [unbalanced posting](journal.html#virtual-postings).) +- `amount` is an alias for `amount1` +- `amount-in`/`amount-out` are aliases for `amount1-in`/`amount1-out` + +This can occasionally get in the way. For example, currently it's possible to generate +a transaction with a blank amount1, but not one with a blank amount2. + +#### currency + +If the CSV has the currency symbol in a separate field (ie, not part +of the amount field), you can use `currencyN` to prepend it to posting +N's amount. Or, `currency` affects all postings. + +#### balance `balanceN` sets a [balance assertion](journal.html#balance-assertions) amount (or if the posting amount is left empty, a [balance assignment](journal.html#balance-assignments)). -You may need to adjust this with the [`balance-type` rule](#balance-type). +You may need to adjust this with the [`balance-type` rule](#balance-type) (see below). + +#### comment Finally, `commentN` sets a [comment](journal.html#comments) on the Nth posting. Comments can also contain [tags](journal.html#tags), as usual. diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 99be109d1..4719bdc96 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -376,30 +376,49 @@ CSV RULES transaction's first line. Posting field names - accountN, where N is 1 to 9, generates a posting, with that account - name. Most often there are two postings, so you'll want to set ac- - count1 and account2. If a posting's account name is left unset but its - amount is set, a default account name will be chosen (like expenses:un- - known or income:unknown). + account + accountN, where N is 1 to 9, causes a posting to be generated, with + that account name. - amountN sets posting N's amount. Or, amount with no N sets posting - 1's. If the CSV has debits and credits in separate fields, use - amountN-in and amountN-out instead. Or amount-in and amount-out with - no N for posting 1. + Most often there are two postings, so you'll want to set account1 and + account2. - For convenience and backwards compatibility, if you set the amount of - posting 1 only, a second posting with the negative amount will be gen- - erated automatically. (Unless the account name is parenthesised indi- - cating an unbalanced posting.) + If a posting's account name is left unset but its amount is set (see + below), a default account name will be chosen (like "expenses:unknown" + or "income:unknown"). - If the CSV has the currency symbol in a separate field, you can use - currencyN to prepend it to posting N's amount. currency with no N af- - fects ALL postings. + amount + amountN sets posting N's amount. + Or if the CSV has debits and credits in two separate fields, use + amountN-in and amountN-out instead. + + Some aliases and special behaviour exist to support older CSV rules + (before hledger 1.17): + + o if amount1 is the only posting amount assigned, then a second posting + with the balancing amount will be generated automatically. (Unless + the account name is parenthesised indicating an unbalanced posting.) + + o amount is an alias for amount1 + + o amount-in/amount-out are aliases for amount1-in/amount1-out + + This can occasionally get in the way. For example, currently it's pos- + sible to generate a transaction with a blank amount1, but not one with + a blank amount2. + + currency + If the CSV has the currency symbol in a separate field (ie, not part of + the amount field), you can use currencyN to prepend it to posting N's + amount. Or, currency affects all postings. + + balance balanceN sets a balance assertion amount (or if the posting amount is left empty, a balance assignment). You may need to adjust this with - the balance-type rule. + the balance-type rule (see below). + comment Finally, commentN sets a comment on the Nth posting. Comments can also contain tags, as usual.