doc: csv tweaks

hledger-lib/doc/hledger_csv.5

@@ -18,7 +18,7 @@ hledger will create it if necessary, with some default rules which
 you\[aq]ll need to adjust.
 At minimum, the rules file must specify the \f[C]date\f[] and
 \f[C]amount\f[] fields.
-For an example, see How to read CSV files.
+For an example, see Cookbook: convert CSV files.
 .PP
 To learn about \f[I]exporting\f[] CSV, see CSV output.
 .SH CSV RULES
@@ -90,7 +90,7 @@ to journal entry fields if you use any of these standard field names:
 \f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[],
 \f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[],
 \f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[],
-\f[C]amount\-out\f[], \f[C]currency\f[].
+\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[].
 Eg:
 .IP
 .nf
@@ -195,7 +195,7 @@ Eg:
 include\ common.rules
 \f[]
 .fi
-.SH TIPS
+.SH CSV TIPS
 .PP
 Each generated journal entry will have two postings, to
 \f[C]account1\f[] and \f[C]account2\f[] respectively.
@@ -211,6 +211,11 @@ If the CSV has the currency in a separate field, assign that to the
 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

hledger-lib/doc/hledger_csv.5.info

@@ -13,16 +13,16 @@ file".  This file should be named like the CSV file with an additional
 with '--rules-file PATH'.  hledger will create it if necessary, with
 some default rules which you'll need to adjust.  At minimum, the rules
 file must specify the 'date' and 'amount' fields.  For an example, see
-How to read CSV files.
+Cookbook: convert CSV files.
 
    To learn about _exporting_ CSV, see CSV output.
 * Menu:
 
 * CSV RULES::
-* TIPS::
+* CSV TIPS::
 
 
-File: hledger_csv.5.info,  Node: CSV RULES,  Next: TIPS,  Prev: Top,  Up: Top
+File: hledger_csv.5.info,  Node: CSV RULES,  Next: CSV TIPS,  Prev: Top,  Up: Top
 
 1 CSV RULES
 ***********
@@ -89,7 +89,8 @@ File: hledger_csv.5.info,  Node: field list,  Next: field assignment,  Prev: dat
 whitespace; uninteresting names may be left blank), and (b) assigns them
 to journal entry fields if you use any of these standard field names:
 'date', 'date2', 'status', 'code', 'description', 'comment', 'account1',
-'account2', 'amount', 'amount-in', 'amount-out', 'currency'.  Eg:
+'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'.
+Eg:
 
 # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
 # and give the 7th and 8th fields meaningful names for later reference:
@@ -170,10 +171,10 @@ Eg:
 include common.rules
 
 
-File: hledger_csv.5.info,  Node: TIPS,  Prev: CSV RULES,  Up: Top
+File: hledger_csv.5.info,  Node: CSV TIPS,  Prev: CSV RULES,  Up: Top
 
-2 TIPS
+2 CSV TIPS
-******
+**********
 
 Each generated journal entry will have two postings, to 'account1' and
 'account2' respectively.  Currently it's not possible to generate
@@ -186,6 +187,11 @@ entries with more than two postings.
 '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.
 
@@ -195,21 +201,21 @@ order of same-day entries will be preserved, usually.
 
 Tag Table:
 Node: Top74
-Node: CSV RULES800
+Node: CSV RULES810
-Ref: #csv-rules906
+Ref: #csv-rules920
-Node: skip1149
+Node: skip1163
-Ref: #skip1245
+Ref: #skip1259
-Node: date-format1417
+Node: date-format1431
-Ref: #date-format1546
+Ref: #date-format1560
-Node: field list2052
+Node: field list2066
-Ref: #field-list2191
+Ref: #field-list2205
-Node: field assignment2886
+Node: field assignment2910
-Ref: #field-assignment3043
+Ref: #field-assignment3067
-Node: conditional block3547
+Node: conditional block3571
-Ref: #conditional-block3703
+Ref: #conditional-block3727
-Node: include4599
+Node: include4623
-Ref: #include4710
+Ref: #include4734
-Node: TIPS4941
+Node: CSV TIPS4965
-Ref: #tips5025
+Ref: #csv-tips5061
 
 End Tag Table

hledger-lib/doc/hledger_csv.5.m4.md

@@ -24,7 +24,7 @@ This file should be named like the CSV file with an additional `.rules` suffix (
 or, you can specify the file with `--rules-file PATH`.
 hledger will create it if necessary, with some default rules which you'll need to adjust.
 At minimum, the rules file must specify the `date` and `amount` fields.
-For an example, see [How to read CSV files](how-to-read-csv-files.html).
+For an example, see [Cookbook: convert CSV files](csv-import.html).
 
 To learn about *exporting* CSV, see [CSV output](hledger.html#csv-output).
 
@@ -157,7 +157,7 @@ a path relative to the current file's directory. Eg:
 include common.rules
 ```
 
-# TIPS
+# 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.
@@ -167,10 +167,14 @@ If the CSV has debit/credit amounts in separate fields, assign to the `amount-in
 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](/journal.html#balance-assertoins) 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.
 
 The generated journal entries will be sorted by date.
 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 you assign anything to the `balance` pseudo field, it would become an assertion of the balance of `account1`. If you assign empty string to it, no assertion will be generated (this can be used to omit balance assertions on some transactions).

hledger-lib/doc/hledger_csv.5.txt

@@ -13,8 +13,8 @@ DESCRIPTION
        .rules suffix (eg: mybank.csv.rules); or, you can specify the file with
        --rules-file PATH.   hledger  will  create  it  if necessary, with some
        default rules which you'll need to adjust.  At minimum, the rules  file
-       must  specify  the  date and amount fields.  For an example, see How to
+       must specify the date and amount fields.  For an example, see Cookbook:
-       read CSV files.
+       convert CSV files.
 
        To learn about exporting CSV, see CSV output.
 
@@ -58,7 +58,7 @@ CSV RULES
        space; uninteresting names may be left blank), and (b) assigns them  to
        journal  entry  fields  if  you  use any of these standard field names:
        date, date2, status, code, description,  comment,  account1,  account2,
-       amount, amount-in, amount-out, currency.  Eg:
+       amount, amount-in, amount-out, currency, balance.  Eg:
 
               # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
               # and give the 7th and 8th fields meaningful names for later reference:
@@ -123,7 +123,7 @@ CSV RULES
               # rules reused with several CSV files
               include common.rules
 
-TIPS
+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.
@@ -135,6 +135,11 @@ TIPS
        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.
 

hledger-lib/doc/hledger_journal.5

@@ -739,8 +739,7 @@ alias\ checking\ =\ assets:bank:wells\ fargo:checking
 .SS Regex aliases
 .PP
 There is also a more powerful variant that uses a regular expression,
-indicated by the forward slashes.
+indicated by the forward slashes:
-(This was the default behaviour in hledger 0.24\-0.25):
 .IP
 .nf
 \f[C]

hledger-lib/doc/hledger_journal.5.info

@@ -736,8 +736,7 @@ File: hledger_journal.5.info,  Node: Regex aliases,  Next: Multiple aliases,  Pr
 ......................
 
 There is also a more powerful variant that uses a regular expression,
-indicated by the forward slashes.  (This was the default behaviour in
+indicated by the forward slashes:
-hledger 0.24-0.25):
 
 alias /REGEX/ = REPLACEMENT
 
@@ -1018,25 +1017,25 @@ Node: Basic aliases25540
 Ref: #basic-aliases25685
 Node: Regex aliases26375
 Ref: #regex-aliases26545
-Node: Multiple aliases27316
+Node: Multiple aliases27260
-Ref: #multiple-aliases27490
+Ref: #multiple-aliases27434
-Node: end aliases27988
+Node: end aliases27932
-Ref: #end-aliases28130
+Ref: #end-aliases28074
-Node: account directive28231
+Node: account directive28175
-Ref: #account-directive28413
+Ref: #account-directive28357
-Node: apply account directive28709
+Node: apply account directive28653
-Ref: #apply-account-directive28907
+Ref: #apply-account-directive28851
-Node: Multi-line comments29566
+Node: Multi-line comments29510
-Ref: #multi-line-comments29758
+Ref: #multi-line-comments29702
-Node: commodity directive29886
+Node: commodity directive29830
-Ref: #commodity-directive30072
+Ref: #commodity-directive30016
-Node: Default commodity30944
+Node: Default commodity30888
-Ref: #default-commodity31119
+Ref: #default-commodity31063
-Node: Default year31656
+Node: Default year31600
-Ref: #default-year31823
+Ref: #default-year31767
-Node: Including other files32246
+Node: Including other files32190
-Ref: #including-other-files32405
+Ref: #including-other-files32349
-Node: EDITOR SUPPORT32802
+Node: EDITOR SUPPORT32746
-Ref: #editor-support32922
+Ref: #editor-support32866
 
 End Tag Table

hledger-lib/doc/hledger_journal.5.txt

@@ -559,8 +559,7 @@ FILE FORMAT
 
    Regex aliases
        There  is  also a more powerful variant that uses a regular expression,
-       indicated by the forward slashes.  (This was the default  behaviour  in
+       indicated by the forward slashes:
-       hledger 0.24-0.25):
 
               alias /REGEX/ = REPLACEMENT
 

site/csv-import.md

@@ -55,3 +55,5 @@ using conversion rules file checking.csv.rules
 --------------------
                    0
 ```
+
+Here are more [CSV rules examples](http://code.hledger.org/tree/master/examples/csv).