diff --git a/README.markdown b/README.markdown
index f0a4e18..dda523f 100644
--- a/README.markdown
+++ b/README.markdown
@@ -7,7 +7,7 @@ Command-line parsing module that uses a syntax similar to that of GNU Getopt.
 Requirements
 ------------
 
-You should only need a somewhat recent version of Erlang/OTP though the module
+You should only need a somewhat recent version of Erlang/OTP, though the module
 has only been tested with Erlang R13B.
 
 
@@ -19,10 +19,137 @@ To run the unit tests run 'make test'.
 To build the (very) limited documentation run 'make docs'.
 
 
+Usage
+-----
+
+The *getopt* module provides two functions:
+
+    parse([#option{}], Args :: [string()]) -> {ok, {Options, NonOptionArgs}} | {error, {Reason, Data}}
+    usage([#option{}], ProgramName :: string()) -> ok
+
+The ``parse/2`` function receives a list of ``option`` records (defined in
+``getopt.hrl``) with the command line option specifications. The ``option``
+record has the following elements:
+
+    -record(option, {
+              name              :: atom(),
+              short             :: char() | undefined,
+              long              :: string() | undefined,
+              arg               :: getopt_arg_type() | {getopt_arg_type(), getopt_arg()} | undefined.
+              help              :: string() | undefined
+             }).
+
+The fields of the record are:
+
+  - ``name``: name of the option.
+  - ``short``: character for the short option (e.g. $i for -i).
+  - ``long``: string for the long option (e.g. "info" for --info).
+  - ``arg``: data type the argument will be converted to with an optional
+             default value. It can either be an atom() (one of: 'atom',
+             'binary', 'boolean', 'float', 'integer', 'string') or a tuple with
+             an atom() and the default value for that argument.
+  - ``help``: help message that is shown for the option when usage/2 is called.
+
+The second parameter holds the list of arguments as passed to the ``main/1``
+function in escripts.
+
+e.g.
+
+     #option{name     = port,
+             short    = $p,
+             long     = "port",
+             arg      = {integer, 5432},
+             help     = "Database server port"
+            }
+
+If the function is successful parsing the command line arguments it will return
+a tuple containing the parsed options and the non-option arguments. The options
+will be represented by a list of key-value pairs with the ``name`` of the
+option as *key* and the argument from the command line as *value*. If the option
+doesn't have an argument, only the atom corresponding to its ``name`` will be
+added to the list of options. For the example given above we could get something
+like ``{port, 5432}``. The non-option arguments are just a list of strings with
+all the arguments that did not have corresponding options.
+
+e.g. For a program named ex1.escript with the following option specifications:
+
+    OptSpec =
+        [
+         #option{name     = host,
+                 short    = $h,
+                 long     = "host",
+                 arg      = {string, "localhost"},
+                 help     = "Database server host"
+                },
+         #option{name     = port,
+                 short    = $p,
+                 long     = "port",
+                 arg      = integer,
+                 help     = "Database server port"
+                },
+         #option{name     = dbname,
+                 long     = "dbname",
+                 arg      = {string, "users"},
+                 help     = "Database name"
+                },
+         #option{name     = xml,
+                 short    = $x,
+                 help     = "Output data in XML"
+                },
+         #option{name     = file,
+                 arg      = string,
+                 help     = "Output file"
+                }
+        ].
+
+And this command line invocation:
+
+    $ ./ex1.escript -h myhost --port 1000 -x myfile.txt dummy1 dummy2
+
+The arguments would be:
+
+    Args = ["-h", "myhost", "--port", "1000", "-x", "myfile.txt", "dummy1", "dummy2"].
+
+So, the call to ``getopt:parse/2``:
+
+    > getopt:parse(OptSpec, Args).
+
+Would return:
+
+    {ok,{[{host,"myhost"},
+          {port,1000},
+          xml,
+          {file,"myfile.txt"},
+          {dbname,"users"}],
+         ["dummy1","dummy2"]}}
+
+Also, the call to ``getopt:usage/2``:
+
+    > getopt:usage(OptSpec, "ex1.escript").
+
+Would show on *stdout*:
+
+    Usage: ex1.escript [-h <host>] [-p <port>] [--dbname <dbname>] [-x] <file>
+
+      -h, --host                    Database server host
+      -p, --port                    Database server port
+      --dbname                      Database name
+      -x                            Output data in XML
+      <file>                        Output file
+
+
 Known limitations
 -----------------
 
-  - The syntax for multiple short options with no argument (e.g. -abc) is not
-    supported yet.
   - The syntax for non-option arguments that start with '-' (e.g. -a -- -b)
     is not supported yet.
+
+
+Known problems
+--------------
+
+Currently, with Erlang R13B (and older versions), escripts cannot use the
+``-include()`` preprocessor directive so you're forced to install the *getopt*
+package in Erlang's library path for your escripts to be able to include the
+``getopt.hrl`` header file that defines the ``#option{}`` record used by the
+functions in the *getopt* module.
diff --git a/TODO b/TODO
new file mode 100644
index 0000000..fd0e551
--- /dev/null
+++ b/TODO
@@ -0,0 +1,2 @@
+* Add support for non-option arguments where the first character is '-'.
+  e.g. For "test -a -- -b" "-b" should be interpreted as a non option argument.