[nongnu] elpa/csv2ledger 03e33d295f 107/190: Replace README with a placeholder.

[ELPA Syncer]

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

    Replace README with a placeholder.
---
 README.md | 200 +-------------------------------------------------------------
 1 file changed, 2 insertions(+), 198 deletions(-)

diff --git a/README.md b/README.md
index 02ed4bc0f2..2b3c07c016 100644
--- a/README.md
+++ b/README.md
@@ -1,203 +1,7 @@
 # csv2ledger #
 
-An Emacs Lisp package for converting csv files to ledger-cli entries.
+An Emacs Lisp package for converting CSV files to 
[ledger-cli](https://www.ledger-cli.org/) 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.
-
-`csv2ledger` creates ledger entries of the following form:
-
-```
-2022-20-17 Aldi Supermarket
-    ; Desc: Referenz 9999999XXX999 ALDI SAGT DANKE
-    Expenses:Groceries
-    Assets:Checkings                                         -€25.10
-```
-
-The description is optional, you can leave it out if you prefer. The format 
used for the amount is also configurable. By default, `csv2ledger` just copies 
the amount from the CSV file, but you can apply a conversion to it if you like.
-
-For ease of reference, I will use the following terms to refer to the various 
parts of the entry. The account associated with the bank account for the CSV 
file is called the *base* account. In the example here, it is 
`Assets:Checkings`. The other account, here `Expenses:Groceries`, is the 
*balancing account*, though I also refer to it as the *target account*. The 
real-life entity associated with the balancing account, here "Aldi Supermarket" 
is often called the payee, but since `csv2ledg [...]
-
-Not indicated in the above example is the *effective* date (also called 
*posted*). This is the date that may follow the booking date, separated by an 
equal sign:
-
-```
-2022-20-17=2022-20-19 * Aldi Supermarket
-    ; Desc: Referenz 9999999XXX999 ALDI SAGT DANKE
-    Expenses:Groceries
-    Assets:Checkings                                         -€25.10
-```
-
-If you have this information in your CSV file, you can use it and add it to 
the entry. If such an effective date is found, the entry is also marked as 
cleared, i.e., an asterisk appears between the date and the title.
-
-
-## Setup ##
-
-At the very least, you will need to set `c2l-base-account` and 
`c2l-csv-columns`. `c2l-base-account` is the account that represents your bank 
account in your ledger file.  By default, `c2l-base-account` is set to 
`Assets:Checking`. `c2l-csv-columns` is a list of column names representing the 
columns in your CSV file. The default value for this variable is the following:
-
-```
-(date posted description sender payee amount)
-```
-
-Note that the column names are symbols. In the default setup, all these fields 
appear in the Ledger entry, except for the fact that `sender` and `payee` never 
appear both. By default, `payee` is used as the title of the CSV file and 
`sender` is ignored. The CSV files that I receive from my bank, however, have 
my name in the payee field when I receive money. In such cases, I want the 
sender to appear as the title of the ledger entry.
-
-`csv2ledger` makes this happen if you set the option `c2l-account-holder` to a 
regular expression matching your name, or whatever your bank puts in the payee 
field in transactions where you receive money. If the payee matches this 
regular expression, the value of the `sender` field is used as the title.
-
-If, on the other hand, you do not have a `sender` field in your CSV files, you 
may simply leave it out. In that case, the `payee` will always be used as the 
title.
-
-The default value of `c2l-csv-columns` assumes that the transaction amount 
always appears in the same column. This is not always the case, however: you 
may have separate columns for amount credit and amount debit. If this is the 
case, you can use the column names `credit` and `debit` instead of `amount`. If 
`csv2ledger` doesn't find and `amount` field in `c2l-csv-columns`, it assumes 
the `credit` and `debit` fields are present and uses those to construct the 
ledger entry. Basically, it c [...]
-
-If you have columns in your CSV files that you wish to ignore, use an 
underscore for them. For example, I'm not interested in the effective (posted) 
date, and my CSV files contain an additional final column with the balance, 
which `csv2ledger` doesn't use. Therefore, I set `c2l-csv-columns` to the 
following value:
-
-```
-(setq c2l-csv-columns '(date _ type description sender payee amount _))
-```
-
-One more thing to note here: I have a `type` field in this list. In my CSV 
files, this field indicates whether the transaction is a bank transfer, an ATM 
withdrawal, a card payment at a store, etc. `csv2ledger` itself does not do 
anything with the `type` field, but it will happily extract the information in 
the column if you provide a name for it. Choose any name you like, just don't 
use a name that is meaningful to `csv2ledger`.
-
-Even though `csv2ledger` does not do anything with the `type` field by 
default, there are ways to make use of such extra information, as discussed 
below.
-
-
-## Running the conversion ##
-
-With these options set up, it is possible to convert a CSV file. To do so, 
open the CSV file in Emacs and run `c2l-convert-buffer`. This command creates a 
new buffer named `*Csv2Ledger Results*` and puts all converted CSV transactions 
in it. If you do not wish to convert the entire buffer, you can also select a 
region and call `M-x c2l-convert-region` instead. Note that if a buffer with 
the name `"Csv2Ledger Results"` already exists, it is reused. That is, its 
contents is erased before t [...]
-
-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.
-
-
-## Automatic account recognition ##
-
-In order to convert an entry, `csv2ledger` needs to know which account to use 
as the balancing account. By default, `csv2ledger` simply asks the user for 
each entry which account to use. To make `csv2ledger` recognise the balancing 
account automatically, you need to set up a file with account matchers. This 
file is a TSV (tab-separated values) file that matches strings to accounts:
-
-```
-aldi          Expenses:Groceries
-lidl          Expenses:Groceries
-restaurant    Expenses:Leisure:Restaurant
-```
-
-Set the option `c2l-account-matchers-file` to point to this file. With this 
setup, if the payee or description (or any other field you configure) of a 
transaction contains the string `"aldi"`, `Expenses:Groceries` is taken as the 
balancing account. There can be more than one matcher for one account: in the 
example, both `"aldi"` and `"lidl"` link to the account `Expenses:Groceries`.
-
-The matchers are simple substrings, not regular expressions. I have not found 
the need to use regular expressions for account matching, and prefer the 
simplicity of not having to worry about the special meaning of certain 
characters in them. But if you prefer, you can use regular expressions for 
account matching. To do this, set the variable `c2l-account-regexps` to an 
alist mapping regular expressions to accounts:
-
-```
-(("\\(?:aldi\\|lidl\\)" . "Expenses:Groceries")
- ("\\(?:restaurant\\)" . "Expenses:Leasure:Restaurant"))
-```
-
-`c2l-account-regexps` is not a customisable option, because normally the 
variable is set based on the contents of the account matchers file. If it is 
already set to a value the first time a conversion function is called though, 
`csv2ledger` will not overwrite it.
-
-When `c2l-account-regexes` is compiled from the account matchers file, each 
account has only one entry in the alist, but this is not a requirement. You can 
have multiple regexes pointing to the same account. Note that if you have 
multiple regexes matching a transaction the first regex that matches wins out.
-
-By default, only the `payee` and `description` fields are compared against the 
account matchers. This can be configured with the option 
`c2l-target-match-fields`. Its default value is `(payee description)`, but you 
can add other fields to it. In fact, I set it to the value `(description payee 
sender type)`.
-
-Two things are of note here: first, the order of this list determines the 
order in which the fields get checked. I prefer for the `description` field to 
be checked first, because it tends to contain more information than the `payee` 
field. Second, I added the `type` field to the list. `csv2ledger` does not do 
anything with this field, but I included it in the list of fields to extract 
from the CSV file and I use it here to match the target account. Specifically, 
I use it to capture ATM w [...]
-
-
-## Modifying field values ##
-
-If you wish or need to modify the values extracted from the CSV file in some 
way, there are several user options that allow you to do so.
-
-### Modifying individual fields ###
-
-First, there is the option `c2l-field-modify-functions`. This is an alist 
mapping field names to functions. Each function should take a string as its 
only argument and return a string. These functions are called with the field's 
value as argument and the return value is used to construct the entry.
-
-As an example, my CSV files provide the date in the format `DD.MM.YYYY`, but 
ledger expects them to be in the format `YYYY-MM-DD`. To remedy this, 
`csv2ledger` comes with the function 
`c2l-convert-little-endian-to-iso8601-date` that takes a date in the format 
`DD.MM.YYYY` and converts it to `YYYY-MM-DD`. For convenience, it also accepts 
dates in the forms `DD-MM-YYYY` and `DD/MM/YYYY`.
-
-To use this function to modify the `date` field, I set 
`c2l-field-parse-functions` like this:
-
-```
-(setq c2l-field-modify-functions
-      '((date . c2l-convert-little-endian-to-iso8601-date)))
-```
-
-I have a similar problem with the amount. In the CSV file, amounts are given 
as follows: `3.150,20 €` or `-240,71 €`. I need to remove the dots and replace 
the decimal comma with a decimal dot. Furthermore, in my ledger file, the 
commodity € comes before the amount, but after the minus sign.
-
-Since this is a very particular conversion, there is no function for it 
included in `csv2ledger`, but if you face the same problem, you can use or 
adapt the following:
-
-```
-(defun c2l-convert-postbank-to-ledger-amount (amount)
-  "Convert AMOUNT from the format found in Postbank CSV files to ledger format.
-Specifically, this converts an amount of the form \"-3.150,20 €\"
-to \"-€3150.20\"."
-  (string-match "\\(-\\)?\\([[:digit:].]+\\),\\([[:digit:]]\\{2\\}\\)" amount)
-  (let ((sign (or (match-string 1 amount) ""))
-        (euros (string-replace "." "" (match-string 2 amount)))
-        (cents (match-string 3 amount)))
-    (concat sign "€" euros "." cents)))
-```
-
-The setting for `c2l-field-parse-functions` then ends up like this:
-
-```
-(setq c2l-field-modify-functions
-      '((date . c2l-convert-little-endian-to-iso8601-date)
-        (amount . c2l-convert-postbank-to-ledger-amount)))
-```
-
-### 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 the other 
fields in the transaction. If you need to make such a change to the 
transaction, you can set the option `c2l-transaction-modify-function` to a 
function that takes the entire transaction as its argument and returns a 
modified transaction.
-
-The transaction will be passed as an alist of field-value pairs. For example, 
for the ledger entry shown above, the transaction would be something like this:
-
-```
-((date . "17.20.2022")
- (description . "Referenz 9999999XXX999 ALDI SAGT DANKE")
- (sender . "account holder")
- (payee . "Aldi Supermarket")
- (amount . "-25,10 €"))
-
-```
-
-Your function can make any change to the transaction you wish. The only 
requirement is that the modified transaction contains at least the fields 
`date`, `payee` and either `amount` or `debit` and `credit`,  because 
`csv2ledger` needs them to construct the ledger entry.
-
-Note that in this transaction alist, the values for date and amount have not 
been modified by the functions if `c2l-field-modify-functions`. This is because 
`c2l-transaction-modify-function` is called first. The result of that function 
is passed to the functions in `c2l-field-modify-functions`. In principle, 
`c2l-transaction-modify-function` can do anything `c2l-field-modify-functions` 
can do, but the latter type  of function is conceptually simpler, which is why 
it's included here.
-
-
-### Setting the title ###
-
-You may also notice that the transaction alist does not contain a value for 
`title`. The `title` field is added to the transaction alist after the 
functions in `c2l-field-modify-functions` have been applied. The function that 
creates the title is configurable through the option `c2l-title-function.` Its 
default value is `c2l-payee-or-sender`, which returns the sender if the payee 
matches the value of `c2l-account-holder` and the payee otherwise. It makes 
sure to check that it does not re [...]
-
-`c2l-title-function` should be set to a function that takes a transaction as 
an alist and returns the title of the transaction as a string. This means that 
if you want to use something other than the payee or the sender as the title, 
e.g., the description field, you can. Just write a short function that extracts 
the relevant value from the transaction and returns it.
-
-
-### Setting the amount ###
-
-As already mentioned above, a CSV file may contain the amount of a transaction 
in a single column, or it may use separate columns for amounts debit and 
amounts credit. The function that creates the actual ledger entry requires the 
`amount` field to be present, however. Therefore, if there is no `amount` field 
in `c2l-csv-columns`, `csv2ledger` assumes that `credit` and `debit` are 
present. It does this by setting the variable `c2l-amount-function`. This 
variable is similar to `c2l-title- [...]
-
-The variable `c2l-amount-function` is actually a user option, which means that 
you can set it to a user-defined function if you like, which may be useful if 
your CSV file is structured in some strange way that I haven't envisaged.
-
-One point to keep in mind: the amount in the debit field must be a negative 
amount, i.e., it must have a minus sign. If this is not the case, the easiest 
way to change this is in `c2l-field-modify-functions`, though in principle 
`c2l-transaction-modify-function` and `c2l-amount-function` could be used as 
well.
-
-
-### Creating the entry ###
-
-After all modification functions have been called, the resulting transaction 
is passed to the function in `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.
-
-
-
-TODO
-
-
-A final variable you may want to set is `c2l-alignment-column`. This should 
most likely have the same value as `ledger-post-amount-alignment-column`, 
although `csv2ledger` currently assumes that `ledger-post-amount-alignment-at` 
is set to `:end` and that the commodity precedes the amount. If either is not 
true, alignment is probably not optimal.
-
-
-
--------------------------------------------------------------------------------
-
-c2l-accounts-file nil
-c2l-base-account "Assets:Unknown"
-c2l-fallback-account nil
-c2l-account-holder nil
-c2l-csv-columns '(date posted description sender payee amount)
-c2l-transaction-modify-function #'identity
-c2l-field-modify-functions nil
-c2l-title-function
-c2l-amount-function
-c2l-account-matchers-file nil
-c2l-target-match-fields '(payee description)
-c2l-auto-cleared nil
-c2l-alignment-column 52
-
-
--------------------------------------------------------------------------------
+Forthcoming.