Clarified purpose and initial documentation

AUTHORS

@@ -1,2 +1,3 @@
 This csv reader is originally wrote by Andy Wingo <wingo at pobox dot com>
-And modified/maintaining by Nala Ginrut <nalaginrut@gmail.com>
+Modified and maintained by Nala Ginrut <nalaginrut@gmail.com>
+Further modified for use by Brady McDonough <me at bradymcd dot ca>

README.md

@@ -1,57 +1,75 @@
 guile-csv
 =========
 
-Guile csv reader
+A csv reader for Guile. Forked from [Nala Ginrut's][og-repo] repository of the 
-
+same name. I forked simply because I plan on using this code (or some 
-## USAGE
+derivative) and as my needs change so too will the interface. Pushing breaking 
+changes to a 5 year old repository isn't exactly my idea of a good time.
 
 ### install
 
 `$make`
+
 `$sudo make install`
 
+## General usage
+
+### reading
+
+First get yourself a port out of whatever csv you want to process:
 
-### read csv
 ```scheme
 (use-modules (csv csv))
-(define my-csv-reader (make-csv-reader #:\,))
+(define $port (open-input-string "a,b\n1,2\n3,4"))
-(call-with-input-file "file.csv" my-csv-reader)
 ```
 
-### csv->xml
+Then, you can process it into a form of your choice between xml and sxml.
+
 ```scheme
-(call-with-input-file "file.csv" csv->xml)
+(csv->xml $port)
 ```
 
-and result could be:
+Output:
-```xml
+```
-<record-0>
+"<record-1><a>1</a><b>2</b></record-1><record-2><a>3</a><b>4</b></record-2>"
- <name>aaa</name>
- <age>11</age>
- <email>aaa@aaa.com</email>
-</record-0>
-<record-1>
- <name>bbb</name>
- <age>12</age>
- <email>bbb@bbb.com</email>
-</record-1>
 ```
 
-### sxml->csv or csv-write to output a csv format file
+If you plan on working with the parsed output further in scheme you'll probably
+want to use `(csv->sxml)` with the optional argument `#:record-sym` like 
+so:
 
 ```scheme
-(call-with-output-file "file.csv"
+(csv->sxml $port
- (lambda (port)
+           #:record-sym (lambda n "rec"))
-  (sxml->csv 
-   '((name age email) ("aaa" "11" "aaa@aaa.com") ("bbb" "12" "bbb@bbb.com"))
-   port)))
 ```
 
-and file.csv would be:
+Output:
-```csv
+```sheme
-name,age,email
+(*TOP* (rec ((a "1") (b "2"))) (rec ((a "3") (b "4"))))
-aaa,11,aaa@aaa.com
-bbb,12,bbb@bbb.com
 ```
 
-Enjoy!
+`#:record-sym` expects a procedure and is called with a numeric argument to
+generate a string. Ignoring the argument and using a single symbol for all 
+records as seen in the example above could be useful if you plan on 
+manipulating the resulting tree using something like `(sxml transform)`.
+
+### writing
+
+While there are facilities to write csv strings and files provided user be 
+warned: they don't quite do what they say on the tin. Calling `sxml->csv` 
+with the output from `csv->sxml` for example will result in an error.  
+The "sxml" expected by this function is what I would venture to call "scsv".  
+```scheme
+`((a b c)("1" "2" "3")("4" "5" "6"))
+```  
+Note the double quotes surrounding each data point, the algorithm currently
+does not attempt to make any conversions and `(string-join)` will complain
+accordingly.
+
+I don't have any need for converting back into csv and have no personal plans 
+on improving this situation (just in case you were preparing to hold your 
+breath). If anyone reading this does want such functionality and has a 
+description of how they think the function ought to act please do raise an 
+issue.
+
+[og-repo]:(https://gitlab.com/NalaGinrut/guile-csv)