branch: elpa/csv2ledger
commit 5f270d2ff072aba9d36d28ca11eb9da344756c68
Author: Joost Kremers <joostkrem...@fastmail.com>
Commit: Joost Kremers <joostkrem...@fastmail.com>
Update the README.
---
README.md | 18 ++++++++++--------
1 file changed, 10 insertions(+), 8 deletions(-)
diff --git a/README.md b/README.md
index 014b9c64e1..8366628db8 100644
--- a/README.md
+++ b/README.md
@@ -35,9 +35,7 @@ If you have this information in your CSV file, you can use it
and add it to the
For the moment, `csv2ledger` needs to be installed manually. Put the file
`csv2ledger.el` in your load path, byte-compile it if you wish, and `require`
it in your init file.
-Make sure to install the dependencies as well: `csv-mode` from GNU ELPA, and
`parse-csv` and `dash` from Melpa. Note that for `csv2ledger` to work properly,
CSV files must be opened in buffers with `csv-mode` as the major mode. This
should work automatically after installing `csv-mode`, but if you have issues,
make sure to check this.
-
-The advantage of `csv-mode` is that it will also handle CSV files that use
semicolon or TAB as separator (even if they have a `.csv` suffix). The
separator should be recognised automatically without any user intervention.
+Make sure to install the dependencies as well: `csv-mode` from GNU ELPA, and
`parse-csv` and `dash` from Melpa. Note that for `csv2ledger` to work properly,
CSV files must be opened in buffers with `csv-mode` as the major mode. This
should work automatically after installing the `csv-mode` package, but if you
have issues, make sure to check this.
## Customisation ##
@@ -58,7 +56,6 @@ Several customisation options are present. The full list with
a short explanatio
- `c2l-alignment-column` (`52`) — Column to which the amount is aligned.
-
## Setup ##
At the very least, you will need to set two user options: `c2l-base-account`
and `c2l-csv-columns`. `c2l-base-account` is the account that represents the
bank account in your ledger file. By default, it is set to the value
`"Assets:Checking"`.
@@ -100,6 +97,10 @@ With these options set up, it is possible to convert a CSV
file. To do so, open
There is also the command `c2l-csv-entry-as-kill`: this converts the single
entry that point is on and places the result in the kill ring. It also displays
the entry in the echo area so you can see what it is doing. This is an easy way
of testing if your conversion settings are correct.
+`csv2ledger` expects that `csv-mode` is used as the major mode for the buffer
visiting your CSV file, and `parse-csv` to parse the contents of the CSV file.
This means it is able to automatically handle CSV files that use a semicolon as
separator instead of a comma, and also TSV files, which use the TAB character
as separator. In addition, `csv2ledger` tries to determine if the first line of
the CSV file is a header line or not, by looking at the `amount`, `debit` and
`credit` fields and [...]
+
+You should make sure, however, that all the data in the file is CSV data. Some
banks place some additional information at the top of the file (such as account
number, total balance, etc.) that is not part of the CSV data. If this is the
case, `csv-mode` may have trouble determining the separator, so it is usually
best to remove this data and reread the file. Alternatively, do `M-x
csv-set-separator` to set the correct separator and then use
`c2l-convert-region` for the data that you want [...]
+
## Setting the target account ##
@@ -184,9 +185,9 @@ Another possible use of `c2l-field-modify-functions` is to
make sure the value o
### Modifying the transaction ###
-One potential disadvantage of the functions in `c2l-field-modify-functions` is
that they only take the value of a single field as argument. This is
insufficient if you want to modify a field value on the basis of some other
field or fields in the transaction. If you need to make such a change to the
transaction, you can set the option `c2l-transaction-modify-functions` to a
list of functions that take the entire transaction as its argument and return a
modified transaction.
+One limitation of the functions in `c2l-field-modify-functions` is that they
only take the value of a single field as argument. This is insufficient if you
want to modify a field value on the basis of some other field or fields in the
transaction. If you need to make such a change, you add a function to the
option `c2l-transaction-modify-functions`. This option holds a list of
functions that take the entire transaction as its argument and return a
modified transaction.
-The transaction is passed as an alist of field-value pairs. For example, for
the ledger entry shown above, the transaction would be as follows:
+The transaction is passed as an alist of field-value pairs, with the fields
being symbols and the values being strings. For example, for the ledger entry
shown above, the transaction would be as follows:
```
((date . "2022-20-17")
@@ -198,7 +199,7 @@ The transaction is passed as an alist of field-value pairs.
For example, for the
Note that the functions in `c2l-field-modify-functions` are applied before
`c2l-transaction-modify-functions`, which is why the values for `date` and
`amount` already appear in their modified forms here.
-Your function can make any change to the transaction you wish. The only
requirement is that after all functions in `c2l-transaction-modify-functions`
have been applied, the resulting transaction alist contains at least the fields
`date`, `payee`, `amount` and `account`, because `csv2ledger` needs them to
construct the ledger entry.
+Your function can make any change to the transaction you wish. The only
requirement is that after all functions in `c2l-transaction-modify-functions`
have been applied, the resulting transaction alist contains at least the fields
`date`, `title`, `amount` and `account`, because `csv2ledger` needs them to
construct the ledger entry. (Assuming you use the default function for creating
the text of the entry; see below for details.)
Note that the functions in `c2l-transaction-modify-functions` are applied in
the order in which they appear in the list. Each function is passed the return
value of the previous one, so you can add a field to the transaction in one
function and refer to it in a later function.
@@ -228,5 +229,6 @@ The third function in `c2l-transaction-modify-functions` is
`c2l-create-account`
### Creating the entry ###
-After all modification functions have been called, the resulting transaction
is passed to the function pointed to by the user option `c2l-entry-function` .
The default value of this option is the function `c2l-compose-entry`, which
creates entries in the form shown above. If that format does not suit your
needs, you can use a custom function instead. It should take the transaction as
an alist and return a string that can be inserted into a ledger buffer.
+After all modification functions have been called, the resulting transaction
is passed to the function pointed to by the user option `c2l-entry-function`.
The default value of this option is the function `c2l-compose-entry`, which
creates entries in the form shown above. If that format does not suit your
needs, you can use a custom function instead. It should take the transaction as
an alist and return a string that can be inserted into a ledger buffer.
+The function `c2l-compose-entry` requires that at least the `date`, `title`,
`amount` and `account` fields be present in the transaction. In addition, the
fields `description` and `posted` are used if they are present. If you write
your own custom function, that requirement no longer holds, of course. (In
fact, there is no real requirement that what the `c2l-entry-function` writes
out is an actual ledger entry. You could have it convert CSV entries into
whatever format you prefer.)
