diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index c3e5e316a..9ddc256fb 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -3245,37 +3245,32 @@ Amount setting can get a bit complex. Assigning to `amount` is sufficient for si - **`amountN` sets a specific posting's amount from one CSV field or arbitrary value.**\ Assigning to `amountN` sets the amount of the Nth posting - and also causes that posting to be generated. N is most often 1 or 2 but can go up to 99, potentially generating a 99-posting transaction. - Posting numbers don't have to be consecutive; higher posting numbers - can sometimes be useful with conditional rules, to ensure a certain ordering of postings. + (Posting numbers don't have to be consecutive; higher posting numbers + can sometimes be useful with conditional rules, to ensure a certain ordering of postings.) - **`amountN-in/-out` sets a specific posting's amount from two CSV fields.**\ - When the amount must be obtained from two CSV fields ("Debit"/"Credit", "Deposit"/"Withdrawal", "Money In"/"Money Out" or similar), assign those to `amountN-in` and `amountN-out` respectively. Or possibly the other way round, depending on signs. - Assigning to `amountN-in` and `amountN-out` sets the Nth posting's amount to whichever of the two CSV field values is non-zero. Some notes: + When the amount is provided as two CSV fields - "Debit"/"Credit", "Deposit"/"Withdrawal", "Money In"/"Money Out" or similar - assign those fields to `amountN-in` and `amountN-out` respectively (or possibly the other way round, depending on signs). This will set the Nth posting's amount to whichever of the two CSV field values is non-zero. + Some notes: + - Don't mix `amountN` and `amountN-in`/`-out`. When you have one CSV amount field, use `amountN`. When you have two CSV amount fields, use `amountN-in`/`amountN-out`. + - `amountN-in` and `amountN-out` are always used together, as a pair. Assign to both of them. + - They do not generate two separate postings; rather, they generate the Nth posting's single amount, from the value found in one or other of the two CSV fields. + - In each record, at least one of the two CSV fields must contain a zero amount or be empty. + - hledger assumes the two CSV fields contain unsigned numbers, and it will automatically negate the -out amount. + - This variant can be convenient, but it doesn't handle every two-amount-field situation; if you need more flexibility, use an `if` rule (see "Setting amounts" below). - - Don't mix (1) `amountN` and (2) `amountN-in`/`amountN-out` in the same rules file. - - `amountN-in` and `amountN-out` are always used together, as a pair. Assign to both of them. - - They transform two CSV fields from the current CSV record into a single amount for the Nth posting. (They do not generate two separate postings.) - - In each record, at least one of the two CSV fields must contain a zero amount or be empty. - - hledger assumes these CSV fields contain unsigned numbers, and will automatically negate the -out value. (See also "Amount signs" below.) - - This won't work for every two-amount-field situation; if you need more flexibility, use an `if` rule (see "Setting amounts" below). - -The other variants are older legacy syntax, but still convenient sometimes, for simple transactions: +The other two variants are older and considered legacy syntax, but can still be convenient sometimes: - **`amount` sets posting 1 and 2's amounts from one CSV field or value.**\ Assigning to `amount`, with no posting number, - sets posting 1's amount (like `amount1`) - - sets posting 2's amount to the same amount but with opposite sign, and also converted to cost if it has a [cost price](#costs) + - sets posting 2's amount to the same amount but with opposite sign; and also converts it to cost if it has a [cost price](#costs) - can be overridden by `amount1` and/or `amount2` assignments. (This helps with incremental migration of old rules files to the newer syntax.) - **`amount-in/-out` sets posting 1 and 2's amounts from two CSV fields.**\ - Similarly, `amount-in` and `amount-out`, with no posting numbers, are to `amount` as `amountN-in`/`amountN-out` are to `amountN`. Assigning to `amount-in` and `amount-out`: + Assigning `amount-in` and `amount-out`, with no posting numbers, to two CSV fields reads whichever of the two values is non-zero as the amount, and then sets the first two posting amounts as above. - - sets posting 1's amount to whichever of the two values is non-zero (like `amount1-in`/`-out`) - - sets posting 2's amount to the same amount but with opposite sign, and also converted to cost if it has a [cost price](#costs) - - can be overridden by `amount1-in`/`-out` and/or `amount2-in`/`-out` assignments. (This helps with incremental migration of old rules files to the newer syntax.) - -We usually recommend you use only one of these variants within a rules file, rather than mixing them. And remember that a `fields` list can also do assignments, so eg naming a CSV field "amount" counts as an assignment to `amount`; if you don't want that, call it something else, like "amount_". +We recommend using only one of these variants within a rules file, rather than mixing them. And remember that a `fields` list can also do assignments, so eg naming a CSV field "amount" counts as an assignment to `amount`; if you don't want that, call it something else, like "amount_". In addition to this section, please see also the tips beginning at ["Working with CSV > Setting amounts"](#setting-amounts) below.