WIP: Cleanup and standardization - Done?

I think I'm getting there with this round. `makepass.zsh` might not look
pretty, but it is beginning to look like something that might be
standardized on.

Next step is to rewrite some of the other scripts to match the zsh one.

1 files changed, 90 insertions, 21 deletions

diff --git a/README.md b/README.md
index 6258c88..8f9ee2b 100644
--- a/README.md
+++ b/README.md
@@ -22,27 +22,96 @@ Recently I decided I wanted to try to recreate makepass in other languages, and
 maybe see if I can make it even faster.
 
 ## makepass specifications
-Here's an attempt to specify how `makepass` should work. Might be useful for future versions.
-
-`./makepass` is a symlink that points to whichever of the scripts I think is the best at any given time.
-
-`makepass` should, by default, output:
-- 10 "normal" passwords
-    - random characters from the "normal" character set (see below)
-- 6 passwords with special characters
-    - first and last random character: alphanumerical
-    - the rest are random characters: from the "special" character set
-- 6 passphrases put together from a wordlist the user can define (using
-  `/usr/share/dict/words` by default), separated by hyphens
-
-If an (one) argument is supplied on the command line, it should be a number
-between (including) 0 and 255, else an error should be shown. This argument
-defines the length of the random passwords. If no argument is provided, every
-password (not passphrase) should be of a random length between (including) 8
-and 42 character
-
-The passwords should *preferably* be output in columns. The number of columns
-should be dynamic, and dependant on the width of the screen.
+Here's the synopsis from `makepass.zsh`, which explains how makepass should work:
+
+```
+NAME
+    makepass - create several random passwords
+
+SYNOPSIS
+    makepass [OPTIONS] [NUM]
+
+    If a NUM is provided, passwords will be NUM characters long.
+
+    By default `makepass` will output passwords from the three following classes:
+
+    - Normal passwords - random strings with letters (both lower and upper
+      case), numbers, and dashes and underscores.
+
+    - Passwords with special characters - random strings generated from lower
+      and upper case letters, numbers, and the following characters:
+      !#$%&/()=?+-_,.;:<>[]{}|@*
+
+    - Passphrases - if we find a dictionary, a series of eight random words
+      from the dictionary, separated by dashes. The number of words can not be
+      changed, but you do not have to use all of them. Use as mane as you want.
+
+    The first and last letter will always be a letter.
+
+DESCRIPTION
+    makepass has the following options:
+
+    -h
+        output this help-text
+    -l
+        length of passwords. See MAKEPASS_LENGTH below
+    -n
+        number of passwords. See MAKEPASS_NUMBER below
+    -p
+        print length of number
+
+ENVIRONMENT
+    makepass examines the following environmental variables.
+
+    MAKEPASS_LENGTH
+        Specifies the length of passwords. Valid values are 0-255. If 0, a
+        random value between 8 and 42 will be used for each password. -l
+        overrides this environmental variable, and the argument NUM overrides
+        that again. So `MAKEPASS_LENGTH=10 makepass -l 12 14` will give
+        passwords that are 14 characters long, even though both -l and
+        MAKEPASS_LENGTH also specifies a length.
+
+    MAKEPASS_NUMBER
+        The number of passwords to generate. This formula is used to determine
+        how many passwords from each group should be generated:
+        - (n) normal passwords
+        - (n / 3 * 2 + 1) special passwords
+        - (n / 2) passphrases
+        Where n is 10 by default. Valid values for n are 1-255. Floating-poing
+        math is not used, so results may vary.
+
+    MAKEPASS_PRINTLEN
+        If 1, print length of all passwords. If 0, don\'t.
+
+    MAKEPASS_NORMAL
+        String of characters from which to generate "normal" passwords.
+        Defaults to:
+        abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_
+
+    MAKEPASS_SPECIAL
+        String of characters from which to generate passwords with special
+        characters. Defaults to the same characters as in MAKEPASS_NORMAL, plus
+        these:
+        !#$%&/()=?+-_,.;:<>[]{}|@*
+
+    MAKEPASS_WORDLIST
+        Specifies the dictionary we find words for passphrases in. If this is
+        unset or empty, we try "/usr/share/dict/words". If that file does not
+        exist, no passphrases will be provided.
+
+NOTES
+    This scripts makes use of $RANDOM - a builtin in zsh which produces a
+    pseudo-random integer between 0 and 32767, newly generated each time the
+    parameter is referenced. We initially seed the random number generator with
+    a random 32bit integer generated from /dev/random. This should provide
+    enough randomnes to generate sufficiently secure passwords.
+
+AUTHOR
+    Dennis Eriksen <https://dnns.no>'
+```
+
+Also, the passwords should *preferably* be output in columns. The number of
+columns should be dynamic, and dependant on the width of the screen.
 
 ### Character sets