updated README

diff --git a/README.rst b/README.rst
index ee0ee07a7890002af90e6b38b80a1693efe2e8af..970f99df7e347033aa02b10707ac883b4578a97b 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -1,46 +1,106 @@
-| A simple command line script that generates XKCD-style multiword passwords/passphrases. Inspired by http://xkcd.com/936/
+xkcdpass
+========
 
-|XKCD password strength|
+A flexible and scriptable password generator which generates strong passphrases, inspired by `XKCD 936 <http://xkcd.com/936/>`_::
 
-For more memorable words, we provide a word list (``static/default.txt``), reproduced with permission from http://wordlist.sourceforge.net/
+    $ xkcdpass
+    > correct horse battery staple
 
-A simple example of how the script may be used via ``import`` is also provided.
+.. image:: http://imgs.xkcd.com/comics/password_strength.png
 
-| **Installation**
 
-Install via pip:
 
-``pip install xkcdpass``
+Install
+=======
 
+``xkcdpass`` can be easily installed using pip::
 
-**Requirements:** Python 2.4+ (Python 3 compatible)
+    pip install xkcdpass
 
-| **Usage:**
-| xkcdpass [options]
+or manually::
 
--  ``-w WORDFILE, --wordfile=WORDFILE`` List of valid words for password
+    python setup.py install
 
--  ``--min=MIN_LENGTH`` Minimum length of words to make password
 
--  ``--max=MAX_LENGTH`` Maximum length of words to make password
 
--  ``-n NUMWORDS, --numwords=NUMWORDS`` Number of words to make password
+Source
+~~~~~~
+The latest development version can be found on github: https://github.com/redacted/XKCD-password-generator
 
--  ``-i, --interactive`` Interactively select a password
+Contributions welcome and gratefully appreciated!
 
--  ``-v VALID_CHARS, --valid_chars=VALID_CHARS`` Valid chars, using
-   regexp style (e.g. '[a-z]')
 
--  ``-V, --verbose`` Report various metrics for given options
 
--  ``-a ACROSTIC, --acrostic=ACROSTIC`` Constrain word choices to those
-   starting with the letters in a given word
+Requirements
+============
 
--  ``-c COUNT, --count=COUNT`` Number of passwords to generate
+Python 2.4+ (Python 3.x compatible)
 
--  ``-d DELIMITER, --delimiter=DELIMITER`` separator character between
-   words
 
-Licensed under the BSD license.
 
-.. |XKCD password strength| image:: http://imgs.xkcd.com/comics/password_strength.png
+Running ``xkcdpass``
+====================
+
+``xkcdpass`` can be called with no arguments::
+
+    $ xkcdpass
+    > pinball previous deprive militancy bereaved numeric
+
+which returns a single password, using the default dictionary and default settings. Or you can mix whatever arguments you want::
+
+    $ xkcdpass --count=5 --acrostic='chaos' --delimiter='|' --min=5 --max=6 --valid_chars='[a-z]'
+    > collar|highly|asset|ovoid|sultan
+    > caper|hangup|addle|oboist|scroll
+    > couple|honcho|abbot|obtain|simple
+    > cutler|hotly|aortae|outset|stool
+    > cradle|helot|axial|ordure|shale
+
+which returns
+
+* ``--count=5``   5 passwords to choose from
+* ``--acrostic='chaos'``   the first letters of which spell 'chaos'
+* ``--delimiter='|'``   joined using '|'
+* ``--min=5 --max=6``  with words between 5 and 6 characters long
+* ``--valid_chars='[a-z]'``   using only lower-case letters (via regex).
+
+
+A concise overview of the available ``xkcdpass`` options can be accessed via::
+
+    xkcdpass --help
+
+    Usage: xkcdpass [options]
+
+    Options:
+        -h, --help
+                                    show this help message and exit
+        -w WORDFILE, --wordfile=WORDFILE
+                                    List of valid words for password
+        --min=MIN_LENGTH
+                                    Minimum length of words to make password
+        --max=MAX_LENGTH
+                                    Maximum length of words to make password
+        -n NUMWORDS, --numwords=NUMWORDS
+                                    Number of words to make password
+        -i, --interactive
+                                    Interactively select a password
+        -v VALID_CHARS, --valid_chars=VALID_CHARS
+                                    Valid chars, using regexp style (e.g. '[a-z]')
+        -V, --verbose
+                                    Report various metrics for given options
+        -a ACROSTIC, --acrostic=ACROSTIC
+                                    Acrostic to constrain word choices
+        -c COUNT, --count=COUNT
+                                    number of passwords to generate
+        -d DELIM, --delimiter=DELIM
+                                    separator character between words
+
+
+A large wordlist is provided (courtesy of `12Dicts <http://wordlist.aspell.net/12dicts/>`_) for convenience, but the generator can be used with any word file of the correct format: a file containing one 'word' per line. The default word file can be found in ``xkcdpass/static/default.txt``.
+
+The main script can also be imported into other python code, and an example of this usage is provided in the package (``xkcdpass/example_import.py``).
+
+
+
+License
+=======
+The BSD License (BSD)
\ No newline at end of file