[nongnu] elpa/csv2ledger a7b24edc4d 033/190: Start README.md

[ELPA Syncer]

branch: elpa/csv2ledger
commit a7b24edc4d1189ab2cc7b3af085037efa516a1ba
Author: Joost Kremers <joostkremers@fastmail.fm>
Commit: Joost Kremers <joostkremers@fastmail.fm>

    Start README.md
---
 README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 81 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 423d5745e6..78d2960dcb 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,82 @@
-# csv2ledger
+# csv2ledger #
+
+An Emacs Lisp package for converting csv files to ledger-cli entries.
+
+## Introduction ##
+
+The purpose of this small library is to read bank transactions in a CSV file 
and convert them to ledger entries. When properly configured, it can convert a 
CSV file automatically into a ledger file, taking a best guess at the target 
account to which transactions should be booked. When no target account can be 
deduced, a fallback account will be used, which you can change afterwards, or 
you can let Emacs show you each transaction and ask for a target account.
+
+## Setup ##
+
+Several user options must be configured before you can successfully use 
`csv2ledger`. Several other options can be configured to streamline the 
experience, but are not necessary.
+
+First, let's look at a typical ledger entry, just to get some terminology 
right:
+
+```
+2022-20-17 * Aldi Supermarket
+    Expenses:Groceries
+    Assets:Checkings Account         -€25.10
+```
+
+This could be a ledger entry created from a CSV file for the bank account 
that's behind the `Assets:Checkings Account` in this entry. I call this account 
the *base account*, just so that I can refer to it. The second account in this 
example, `Expenses:Groceries` is the *target* account, also mainly just to give 
it a name. Lastly, I label "Aldi Supermarket" the *title*. In the `ledger-cli` 
documentation, this is usually called the payee, but for transactions where I 
receive money, I'm the [...]
+
+With that out of the way, let us look at the options that we need. First, you 
should set `c2l-base-account` to the ledger account that is associated with the 
bank account for which you are converting the CSV file. This can be done in two 
ways: You can either set a single, default base account, which will then apply 
to any CSV file you wish to convert, or you can set a buffer-local base 
account, which only applies to the CSV file in the current buffer.
+
+Setting a default base file can be done through Customize or in your `init.el` 
file. In the latter case, make sure to use `setq-default`, not `setq`, or use 
the `:custom` directive of `use-package`.
+
+Setting a buffer-local value for `c2l-base-account` can be done through 
file-local or directory-local variables, but also with the command `M-x 
c2l-set-base-account`. Regardless of the method you use, the buffer-local value 
will override any default value you may have set, so it is possible to set a 
default base account and override it on a per-buffer basis if the need arises.
+
+The second option you should set is `c2l-csv-columns`. This defines the 
columns found in the CSV file. The default value for this variable is the 
following:
+
+```
+(date valuation description sender payee amount)
+```
+
+This means that the first column contains the date, the second the valuation, 
etc. You should change this list to whatever is correct for the CSV files you 
want to read. In order to create a proper ledger entry, your file should at 
least contain `date`, `sender`, `payee` and `amount`. The `valuation` and 
`description` fields can be added to the entry if they exist, but if not, they 
are left out.
+
+If there are columns in your CSV files that you do not need for the ledger 
entry, you can write and underscore for them. For example, this is the setting 
that I use for my CSV files:
+
+```
+(setq c2l-csv-columns '(date _ type description sender payee amount _))
+```
+
+I ignore the second field (which contains the valuation) and the last one, 
which contains the account balance. In addition to the standard fields there is 
also a `type` field, which does not become part of the ledger entry but which I 
use to determine the correct target account, as described below.
+
+These are the two options you must set in order to process any CSV files. 
There are a number of other options, however, which can make your life a bit 
easier if you configure them properly.
+
+The first of these is `c2l-account-holder`. This should be a string or regular 
expression that matches your name, whatever your bank puts in the CSV file when 
you receive money, i.e., when you are the payee. This is used by `csv2ledger` 
to determine what to use as the title of a transaction. If you are the payee, 
it uses the sender, otherwise it uses the payee.
+
+Second, you should set `c2l-fallback-account`. This is the account used as the 
target account when `csv2ledger` cannot determine a target account. This can 
be, but does not have to be a true ledger account. You can set it to e.g., 
`"TODO"`, so that after converting a CSV file you can go through the resulting 
ledger entries and search for the ones where you still need to provide a target 
account.
+
+If you do not set `c2l-fallback-account`, conversion of a CSV file will not be 
entirely automatic: each time `csv2ledger` cannot determine a target account 
itself (as described below), it will ask you for one. If you prefer this method 
of operation, leave `c2l-fallback-account` unset.
+
+The option `c2l-accounts-file` can be set to the path of a ledger file 
containing account declarations. Although `ledger-cli` does not require this, 
it is good style to define your accounts in a ledger file. Doing so and 
pointing `c2l-account-file` to it means that whenever `csv2ledger` asks you for 
an account, it uses completion.
+
+If you have set these options, you are basically good to go. `csv2ledger` will 
convert a CSV file to ledger entries without complaining. However, target 
accounts will not be set automatically, so you will either have a lot of 
correcting to do, or you are being pestered by Emacs at every transaction.
+
+## Automatic target account recognition ##
+
+The automatic target account recognition in `csv2ledger` is admittedly fairly 
simple, but it works well for me. Essentially, it just checks for the presence 
of certain strings in an entry's fields. Each search string is associated with 
a ledger account. The first string that is found provides the target account.
+
+To set this up, you first need to create a TSV file containing match strings 
and ledger accounts:
+
+```
+aldi          Expenses:Groceries
+lidl          Expenses:Groceries
+restaurant    Expenses:Leisure:Restaurant
+```
+
+The first column contains the match strings, the second column the ledger 
account. There can be multiple match strings associated with one account, as 
shown in the example.
+
+With this file set up, you should point the option `c2l-account-matchers-file` 
to it so that the matchers can be used to determine the target account.
+
+By default, `csv2ledger` only checks the `payee` and `description` fields in 
the CSV file for matches, but this can be configured with the option 
`c2l-title-match-fields`. I personally set this option to the following value:
+
+```
+(setq c2l-title-match-fields '(description payee sender type))
+```
+
+This means that the `description` field is checked first, then the `payee`, 
then the `sender` and lastly the `type` field. The `type` field is not part of 
the default setup, but it is listed in the CSV files I get from my bank and it 
indicates whether the transaction was a bank transfer, a recurrent order, an 
ATM withdrawal, a card payment at a store, etc. I have a matcher that captures 
ATM withdrawals that sets the target account to `Assets:Cash`. 
+
+Note that this is the *only* reason for including the `type` field in 
`c2l-csv-columns` above: I use its value to help determine the target account.
 
-Emacs Lisp library for converting csv files to ledger-cli entries.
\ No newline at end of file