updated the README.md so that it can be used on github and to make a man page

README.md

@@ -1,10 +1,15 @@
-# pwgen
+% pwgen(1) 1.3 | Misc
+% Pat Beirne <patb@pbeirne.com>
+  
+# Name
+
+pwgen - a phrase-based password generator
 
 Generate word-based passwords. Based on [XKCD/936](https://xkcd.com/936/), word-based passwords are easier to remember than a string of random letters/numbers/punctuation.
 
 [TOC]
 
-### Overview
+# Description
 
 Password generators can be found all over the internet, but most generate random combinations of letters + numbers + punctuation. If a combination of those is long enough to be secure, it is also long enough to be difficult to remember, and possible difficult to type.
 
@@ -12,49 +17,61 @@ The XKCD comic #936 introduced the idea that a phrase of 3, 4 or 5 common words
 
 This program runs locally on a UNIX/Linux based computer, and the passphrase never crosses the network, so you can be sure that you're the only one who has ever seen it.
 
-### Usage
-
 Simply invoke the program, and the defaults will give you a usable password phrase:
 
-    pwgen
+    pwgen -S
 
 returns
 
     boards.coziest.allure
 
-as a potential pass phrase. The following options exist:
+as a potential pass phrase.
+
+
+# Synopsis
+
+    pwgen [-sSpPkKnNcCXMa] [-L <length>] [nummber of passwords]
 
-    -p    pad the words with spaces
-    -P    pad the words with spaces, periods or commas
-    -n    pad with numbers
-    -N    pad with numbers and punctuation (other than space)
-    -L <n>  minimum phrase length (default=20) (or --length <n>)
-    -c    make 2 word phrases with conjunction between them
-    <n>   make multiple phrases (default=1)
+# Options
+
+       -s           pad with only spaces (default; for smartphone)
+       -S           pad with period and comma (for smartphone)
+       -p           pad with special characters
+       -P           pad with numbers
+       -k           connect the words as CamelCase
+       -K           connect the words as snake_case
+       -n           add a number at the beginning
+       -N           add a number at the end
+       -c           add a special character at the begnning
+       -C           add a special character at the end
+       -M           capitalize the words
+       -a           connect the words with a conjuction filler
+       -X           same as -MNCS (capital, periods & commas, extra number & char)
+       -L <n>       make pass phrases at least this long; default=20
+       num_phrases  make multiple pass phrases, one per line; default=1
 
 By default, **`pwgen`** will build a pass phrase using words from the dictionary at **`/usr/share/dict/words`** and add punctuation to separate the words. 
 
     $ pwgen
-    consequently?restraining
+    consequentlyi restraining
 
-Adding the **`-p`** option will insist that the passphrase be padded with only spaces, making it easier to type on a smartphone. Similarly, the **`-P`** option uses only spaces, periods and commas, which are often easily accessed on a smartphone.
+The **`-s`** and **`-S`** options add padding using spaces or periods/commas, making thease passphrases easy to type on a smartphone. Adding the **`-p`** option will padd the phrase using a "special characters"; the character will be one of ` !@#$%^&*()-_=+[{]}\\|;:/?.>,<~`. Similarly, the **`-P`** option uses a number.
 
-    $ pwgen -p
+    $ pwgen -s
     garments mazes queasy
+    $ pwgen -S
+    crufted.teeth.buy
+    $ pwgen -p
+    eating!rocks!outside
     $ pwgen -P
-    crufted..teeth...buy
-
-Some servers require numbers to be embedded in the password, so the **`-n`** and **`-N`** options are available.
-
-    $ pwgen -N
-    bleeding5clusters5berries#
+    bleeding5clusters5berries
 
 The **`-L`** option allows you to specify a minimum length for the pass phrase, although the result may be a few characters longer than you requested, so that the words aren't chopped up.
 
     $ pwgen -L 30
-    dittoed___nonabrasive___atomic
+    dittoed nonabrasive atomic exhaust
 
-The **`-c`** option uses common English conjunctions to separate a pair of words. If the 2nd word starts with a vowel, the conjuntion "a" is changed to "an". I find these phrases much easier to remember than just a sequence of words.
+The **`-a`** option uses common English conjunctions to separate a pair of words. If the 2nd word starts with a vowel, the conjuntion "a" is changed to "an". I find these phrases much easier to remember than just a sequence of words.
 
     $ pwgen -c
     quick in a crowd
@@ -69,11 +86,52 @@ Part of the reason for using pass phrases is to make them easier to remember for
     firesides!!!spaceman
     wannest=tabloids=weighty
 
-Coming soon: Instead of spaces & punctuation, you will be able to use CamelCase to indicate word boundaries. Snake_case is also a commonly requested format. L3tt3rSubst!tut!0n will also be implemented.
+The **`-k`** and **`-K`** options will create CamelCase and snake_case respetively. You can use the **`-M`** option to capitalize all the dictionary words.
+
+Some servers require numbers and "special characters" in the passwords, so the **`-n, -N, -c`** and **`-C`** allow you to add these characters at the beginning or the end of your passphrase. See the examples below.
+
+The **`-X`** option is included to abbreviate a commonly used combination of **`-MNCS`**. 
+
+# Examples
+
+    -s    dog cat mouse        # default
+    -S    dog.cat.mouse   
+    -p    dog#cat#mouse  
+    -P    dog4cat4mouse  
+    -c    !dog cat mouse  
+    -C    dog cat mouse#  
+    -n    4dog cat mouse
+    -N    dog cat mouse4
+    -cnCN $4dog cat mouse4$
+    -M    Dog Cat Mouse
+    -k    DogCatMouse
+    -kN   DogCatMouse2
+    -K    dog_cat_mouse
+    -KMN  Dog_Cat_Mouse3
+    -a    dog and a cat with mouse
+    -Sa   dog.and.a.cat.with.mouse
+    -aMS  Dog.and.a.Cat.with.Mouse
+    -pa   dog#and#a#cat#with#mouse
+    -paCN dog^and^a^cat^with^mouse5%
+    -X    Dog.Cat.Mouse6&
+
+Just select a format that you find memorable.
+ 
+# Files
+
+**`/usr/share/dict/words`**:  a line separated list of words for the pass phrases
+
+Words ending in `'s` are dropped by the import algorithm; this may need to be changed for other languages. 
+ 
+# Notes
+
+Don't bother trying the **`-ka`** combination....the results can be illegible.
 
+This project is written in Python3 and duplicated in Rust. I wanted to learn Rust and compare the complexity of both.
 
+# See Also
 
-#### Other implementations
+### Other implementations
 
 <http://www.egansoft.com/password/index.php>