update README.me

1 files changed, 51 insertions, 7 deletions

diff --git a/README.md b/README.md
index 1509a93..b5c413f 100644
--- a/README.md
+++ b/README.md
@@ -3,15 +3,59 @@ marigold-cgi
 
 A Lua CGI scripting toolkit.
 
-usage
------
 
-### retrieving meta-variables
+functions
+---------
 
-`marigold.get_metavars()` - returns a table. The keys are the (lowercase) names of the meta-variables described in section 4.1 of RFC 3875 and are associated with their (string) values.
+#### `marigold.get_metavars()` ####
 
-### generating html
+Returns a table containing all of the meta-variables described in section 4.1 
+of [RFC 3875]. The keys are the lowercase metavariable names (e.g. `
+request_method`) and the values are strings containing their values.
 
-`marigold.h(tag, attributes_and_children)` - returns a `marigold.html` table. `tag` is a string; `attributes_and_children` is a table containing, uh, tag attributes and children. Attributes are string keys with string values and represent the tag's attributes (e.g. `{id='tag1', class='large blinking'}` converts to `<[tag] id="tag1" class="large blinking"></[tag]>`). Children are the array elements of the table and should contain `marigold.html` tables as values.
 
-The only thing that is special about `marigold.html` tables is that they can be passed to `marigold.render_html(tbl, indent_level=0)` in order to produce actual string output.
+#### `marigold.h(tag_type [string], content [string, opt], tbl [table, opt])` ####
+
+Builds a table to be used with `marigold.html`.
+
+  * `tag_type`: the type of the tag, e.g. `<p>`, `<div>`, etc
+  * `content`: any text content within the tag. may be omitted and *still include tbl*
+  * `tbl`: table containing both tag attributes and children. Values with 
+     string keys are considered attributes, while values with numeric keys are 
+     added as children in the same order as the keys.
+
+Returns a table with stringly-typed `tag` and `content` keys, and table-typed `
+attributes` and `children` keys. There is no reason you can't generate a table 
+like this by hand and pass it to `marigold.html`; this function is provided for convenience.
+
+
+#### `marigold.html(tbl [table], indent_level [number, opt])` ####
+
+Reads a `marigold.h`-formatted table and returns a pretty-printed HTML fragment representing it.
+
+  * `tbl`: a table as described above
+  * `indent_level`: 0 by default, but if you're rendering a document piecemeal you might set this
+
+Returns a string with nicely formatted HTML. To render a whole document, pass 
+it a `marigold.h('html', ...)` result.
+
+
+#### `marigold.decode_percent(str [string])` ####
+
+Decodes percent-encoded strings.
+
+  * `str`: a string with percent-encoded values embedded
+
+Returns the clean string, with the percent-encoded values decoded. Note that it will NOT do things like replace '+' with ' ' for `application/x-www-form-urlencoded` data.
+
+
+#### `marigold.decode_query(str [string])` ####
+
+Decodes `application/x-www-form-urlencoded` data into a table.
+
+   * `str`: the string containing the data to decode
+
+Returns a table containing all the key-value pairs that could be extracted from the string, with all percent-encoding removed and appropriate '+' replaced with ' '.
+
+
+[RFC 3875]: https://www.rfc-editor.org/rfc/rfc3875.html