Update docs

Author: stilvoid

README.md

@@ -14,6 +14,10 @@ It is comprised of three sub-commands:
 
     acts as a one-shot web server - useful in testing you applications
 
+* `please identify`
+
+    given structured data on standard input, this will output the format used (e.g. "json", "yaml")
+
 * `please parse`
 
     understands the data exchange formats of the web and can translate between them

docs/index.md

@@ -14,6 +14,10 @@ It is comprised of three sub-commands:
 
     acts as a one-shot web server - useful in testing you applications
 
+* `please identify`
+
+    given structured data on standard input, this will output the format used (e.g. "json", "yaml")
+
 * `please parse`
 
     understands the data exchange formats of the web and can translate between them

docs/parse.md

@@ -25,47 +25,80 @@ If you're not familiar with associative arrays in bash or how `declare` works, i
 
 ## Usage
 
-    please parse [-i type] [-o type] [path...]
+    please parse [-i <INPUT FORMAT>] [-o <OUTPUT FORMAT>] [PATH]
 
-    -i type  Parse the input as 'type' (default: auto)
-    -o type  Use 'type' as the output format (default: bash)
+    If INPUT TYPE is omitted, it defaults to "auto".
 
-    If path is given, only output data from the path downwards.
+    If OUTPUT TYPE is omitted, it will default to the same as the input type - effectively acting as a pretty-printer.
+
+    If PATH is provided, it should be given in dot-notation, e.g. orders.*.id
+
+    Available input types:
+        auto
+        csv
+        html
+        json
+        mime
+        xml
+        yaml
+
+    Available output types:
+        bash
+        dot
+        json
+        xml
+        yaml
 
 ## Examples
 
 Parsing a whole tree:
 
     $ echo '{"this":{"is":["some","json"],"that":"we"},"will":"parse"}' | please parse
-    ([this]="([is]=\"([0]=some [1]=json)\" [that]=we)" [will]=parse)
+    {
+      "this": {
+        "is": [
+          "some",
+          "json"
+        ],
+        "that": "we"
+      },
+      "will": "parse"
+    }
 
 Getting a single value:
 
     $ echo '{"this":{"is":["some","json"],"that":"we"},"will":"parse"}' | please parse this.that
-    we
+    "we"
 
 Specifying the input format:
 
 Note the `-i` flag
 
     $ echo '<xml example="true"><child>one</child><child>two</child></xml>' | please parse -i xml
-    ([xml]="([-example]=\"true\" [child]=\"([0]=\\\"one\\\" [1]=\\\"two\\\")\")")
+    <xml example="true">
+      <child>one</child>
+      <child>two</child>
+    </xml>
 
 Specifying the output format:
 
 Note the `-o` flag
 
     $ echo '{"json": ["input", "here"], "yaml": "output"}' | please parse -o yaml
-    'json': 
-      - "input"
-      - "here"
-    'yaml': "output"
+    json: 
+    - input
+    - here
+    yaml: output
 
 Making use of the bash-declare output format
 
-    $ echo '{"json": ["array", "values"]}' | please parse json | (declare -A data=$(cat -); echo ${data[1]})
+    $ echo '["array", "values"]' | please parse -o bash | (declare -A data=$(cat -); echo ${data[1]})                                     
     values
 
 Generating a graph from some json (you need graphviz installed)
 
     $ echo '{"vars": ["foo", "bar", "baz"], "cake": {"is_lie": true}}' | please parse -o dot | dot -Tpng > graph.png
+
+Will result in:
+
+![A nice graph](dot-output.png)

docs/request.md

@@ -6,25 +6,22 @@ Probably the most important thing you will need to do with a web service is to c
 
 ## Usage
 
-    please request <method> [options...] <url>
+    please request <METHOD> [option...] <URL>
 
-    -i    Headers included in the input
+    Makes a web request to URL using METHOD
 
-    -s    Output HTTP status line with the response
-    -h    Output headers with the response
+    Shortcut aliases:
+        please get
+        please post
+        please put
+        please delete
 
-    There are aliases for the most common methods:
+    Input options:
+        -i    Include headers from input
 
-        please get <url>
-        please post <url>
-        please put <url>
-        please delete <url>
-
-    For any other methods, you will need to specify the method directly:
-
-        please request head <url>
-        please request info <url>
-        please request patch <url>
+    Output options:
+        -s    Output HTTP status line
+        -h    Output headers
 
 ## Examples
 

docs/respond.md

@@ -4,13 +4,19 @@
 
 ## Usage
 
-    please respond [options...] <status> [<address>[:<port>]]
+    please respond [option...] <STATUS> [<ADDRESS>[:<PORT>]]
 
-    -i    Headers included in the input
+    Listens on the specified address and port and responds with the chosen status code.
+    Any data on stdin will be used as the body of the response.
+    The request body will be printed to stdout.
 
-    -m    Include request method in output
-    -u    Include URL in output
-    -h    Include headers in output
+    Input options:
+        -i    Include headers from input
+
+    Output options:
+        -m    Output the request method
+        -u    Output the requested path
+        -h    Output headers with the request
 
 ## Examples