docs: rename readline.md to readline.markdown

doc/api/readline.markdown

@@ -1,61 +1,133 @@
 ## Readline
 
-This module allows reading of a stream (such as STDIN) on a line-by-line basis.
+To use this module, do `require('readline')`. Readline allows reading of a
+stream (such as STDIN) on a line-by-line basis.
 
-Note that once you've invoked this module, your node program will not terminate
-until you've closed the interface, and the STDIN stream. Here's how to allow
-your program to gracefully terminate:
+Note that once you've invoked this module, your node program will not
+terminate until you've closed the interface, and the STDIN stream. Here's how
+to allow your program to gracefully terminate:
 
-<pre>
-var readline = require('readline');
+    var rl = require('readline');
 
-var i = readline.createInterface(process.sdtin, process.stdout, null);
-i.question("What do you think of node.js?", function(answer) {
-  //TODO: Log the answer in a database
-  console.log("Thank you for your valuable feedback.");
-  i.close();                //These two lines together allow the program to
-  process.stdin.destroy();  //terminate. Without them, it would run forever.
-});
-</pre>
+    var i = rl.createInterface(process.sdtin, process.stdout, null);
+    i.question("What do you think of node.js?", function(answer) {
+      // TODO: Log the answer in a database
+      console.log("Thank you for your valuable feedback.");
 
-### createInterface(input, output, completer)
+      // These two lines together allow the program to terminate. Without
+      // them, it would run forever.
+      i.close();
+      process.stdin.destroy();
+    });
 
-Returns an interface object, which reads from input, and writes to output.
-TODO: I think "completer" is used for tab-completion, but not sure.
+### rl.createInterface(input, output, completer)
 
-### interface.setPrompt(prompt, length)
+Takes two streams and creates a readline interface. The `completer` function
+is used for autocompletion. When given a substring, it returns `[[substr1,
+substr2, ...], originalsubstring]`.
 
-TODO
+`createInterface` is commonly used with `process.stdin` and
+`process.stdout` in order to accept user input:
 
-### interface.prompt()
+    var readline = require('readline'),
+      rl = readline.createInterface(process.stdin, process.stdout);
 
-TODO: Appears to trigger showing the prompt.
+### rl.setPrompt(prompt, length)
 
-### interface.question(query, cb)
+Sets the prompt, for example when you run `node` on the command line, you see
+`> `, which is node's prompt.
 
-Displays the query to the user, and then calls the callback after the user
-has typed in their response.
+### rl.prompt()
+
+Readies readline for input from the user, putting the current `setPrompt`
+options on a new line, giving the user a new spot to write.
+
+<!-- ### rl.getColumns() Not available? -->
+
+### rl.question(query, callback)
+
+Prepends the prompt with `query` and invokes `callback` with the user's
+response. Displays the query to the user, and then invokes `callback` with the
+user's response after it has been typed.
 
 Example usage:
 
-<pre>
-interface.question("What is your favorite food?", function(answer) {
-  console.log("Oh, so your favorite food is " + answer);
-});
-</pre>
+    interface.question('What is your favorite food?', function(answer) {
+      console.log('Oh, so your favorite food is ' + answer);
+    });
+
+### rl.close()
+
+  Closes tty.
+
+### rl.pause()
+
+  Pauses tty.
+
+### rl.resume()
+
+  Resumes tty.
+
+### rl.write()
+
+  Writes to tty.
+
+### Event: 'line'
+
+`function (line) {}`
+
+Emitted whenever the `in` stream receives a `\n`, usually received when the
+user hits enter, or return. This is a good hook to listen for user input.
+
+Example of listening for `line`:
+
+    rl.on('line', function (cmd) {
+      console.log('You just typed: '+cmd);
+    });
+
+### Event: 'close'
+
+`function () {}`
 
-### interface.close()
+Emitted whenever the `in` stream receives a `^C` or `^D`, respectively known
+as `SIGINT` and `EOT`. This is a good way to know the user is finished using
+your program.
 
-TODO
+Example of listening for `close`, and exiting the program afterward:
 
-### interface.pause()
+    rl.on('close', function() {
+      console.log('goodbye!');
+      process.exit(0);
+    });
 
-TODO
+Here's an example of how to use all these together to craft a tiny command
+line interface:
 
-### interface.resume()
+    var readline = require('readline'),
+      rl = readline.createInterface(process.stdin, process.stdout),
+      prefix = 'OHAI> ';
 
-TODO
+    rl.on('line', function(line) {
+      switch(line.trim()) {
+        case 'hello':
+          console.log('world!');
+          break;
+        default:
+          console.log('Say what? I might have heard `' + line.trim() + '`');
+          break;
+      }
+      rl.setPrompt(prefix, prefix.length);
+      rl.prompt();
+    }).on('close', function() {
+      console.log('Have a great day!');
+      process.exit(0);
+    });
+    console.log(prefix + 'Good to see you. Try typing stuff.');
+    rl.setPrompt(prefix, prefix.length);
+    rl.prompt();
 
-### interface.write()
 
-TODO
+Take a look at this slightly more complicated
+[example](https://gist.github.com/901104), and
+[http-console](http://github.com/cloudhead/http-console) for a real-life use
+case.