doc: csv: improve CSV conversion tips

[ci skip]

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
+order of same\-day transactions.
-day of data.
 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
+but when all CSV records have the same date it will assume they are
-first.
+oldest first.
 .SH CSV TIPS
-.PP
+.SS CSV ordering
-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.
 .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"

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
+order of same-day transactions.  It usually isn't needed, because
-of data.  It usually isn't needed, because hledger autodetects the CSV
+hledger autodetects the CSV order, but when all CSV records have the
-order, but if all the CSV records have the same date it assumes they are
+same date it will assume they are oldest first.
-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
+* Menu:
-'account2' respectively.  Currently it's not possible to generate
+
-entries with more than two postings.
+* 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'.
+'amount-in' and 'amount-out' pseudo fields instead.  (Whichever one has
-
+a value will be used, with appropriate sign.  If both contain a value,
-   If the CSV has the currency in a separate field, assign that to the
+it may not work so well.)
-'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.)
 
    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
+   If an amount value begins with a double minus sign, those will cancel
-order of same-day entries will be preserved, usually.
+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
+Node: CSV TIPS5538
-Ref: #csv-tips5606
+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

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 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.
+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.
+## CSV ordering
-Currently it's not possible to generate entries with more than two postings.
 
-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.
+## CSV accounts
-(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 
+Each journal entry will have two [postings](/journal.html#postings), to `account1` and `account2` respectively.
-to generate a [balance assertion](/journal.html#balance-assertions) on `account1` 
+It's not yet possible to generate entries with more than two postings.
-whenever the balance field is non-empty.
+It's conventional and recommended to use `account1` for the account whose CSV we are reading.
-(Eg to double-check your bank's balance calculation.)
 
-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 `amount` field sets the [amount](/journal.html#amounts) of the `account1` posting.
-The original order of same-day entries will be preserved, usually.
-<!-- (by reversing the CSV entries if they seem to be in reverse date order). -->
 
+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. 

hledger-lib/doc/hledger_csv.5.txt

@@ -126,35 +126,48 @@ CSV RULES
    newest-first
        newest-first
 
-       Consider adding this rule if: your CSV records are in  reverse  chrono-
+       Consider adding this rule if all of the following are true:  you  might
-       logical  order  (newest first), and you care about preserving the order
+       be  processing  just  one  day of data, your CSV records are in reverse
-       of same-day transactions, and you might be processing just one  day  of
+       chronological order (newest first), and you care about  preserving  the
-       data.   It  usually  isn't  needed, because hledger autodetects the CSV
+       order  of  same-day  transactions.   It  usually  isn't needed, because
-       order, but if all the CSV records have the same date  it  assumes  they
+       hledger autodetects the CSV order, but when all CSV  records  have  the
-       are oldest first.
+       same date it will assume they are oldest first.
 
 CSV TIPS
-       Each  generated  journal  entry will have two postings, to account1 and
+   CSV ordering
-       account2 respectively.  Currently it's not possible to generate entries
+       The  generated  journal  entries  will be sorted by date.  The order of
-       with more than two postings.
+       same-day entries will be preserved (except in the  special  case  where
+       you might need newest-first, see above).
+
+   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.
+
+   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.
+       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
-       If the CSV has the currency in a separate field,  assign  that  to  the
+       may not work so well.)
-       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  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  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
+       If an amount value begins with a double minus sign, those  will  cancel
-       order of same-day entries will be preserved, usually.
+       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.