Adding description to README

1 files changed, 39 insertions, 29 deletions

diff --git a/README.md b/README.md
index b1f8981..21bb9ce 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,25 @@
 
 *This is a work in progress!*
 
-I wrote `makepass` long ago to just spit out some random strings I could use as
-passwords.
+makepass is a program that outputs a series of random passwords with both
+"normal" and "special" characters, and a series of passphrases from a given
+dictionary. See below for an example of what the output looks like.
 
-The first versions has been lost to time, and `makepass` was first commited to a
+makepass is implemented in several languages for both fun and learning. The
+current main version is `makepass.zsh`. The symlink `./makepass` will always
+point to the main version.
+
+## History
+
+I wrote makepass long ago (somewhere between 2010 and 2013 I believe) to just
+spit out some random strings I could use as passwords.
+
+The first versions has been lost to time, and makepass was first commited to a
 git-repo in 2018, as part of my dotfile-repo
 [idgatt](https://git.dnns.no/idgatt/) ("It's Dangerous to Go Alone, Take
 This!").
 
-`makepass` was first written as a bash-script, but it was a zsh-script when I
+makepass was first written as a bash-script, but it was a zsh-script when I
 commited it to my dotfile-repo. It was later changed back to a bash-script, and
 in 2022 I rewrote it as both a POSIX shell-script and as a zsh-script.
 
@@ -21,7 +31,31 @@ zsh, and does not fork out to any other programs.
 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
+## Example output
+
+```
+Normal passwords:
+ZmvQB4r23KnctqjoV8fAlObMNu9Yt               f-FS1k7yXwxeTIZk
+IpCL6RiHgh0DsJGzE_mvQB4r23KnctqjoV8fAlY     ANu9Yda5-FS1k7yXwxeTIZWPUpCL6RiHgh0Dsr
+vE_mvQB4r23KnctqjoV8fAlObMNu9YdaD           dS1k7yXwxeTIZu
+wpCL6RiHgh0DsJGzE_mvQB4r23KnctqjoV8fAN      XMNu9Yda5-FS1k7yXwxeTIZWPUpCL6
+uHgh0DsJGzE_mV                              N4r23KnctqjoV8fAlObMNu9Yda5-FS1k7yXwxy
+
+Passwords with special characters:
+L&ROH=NKTcti-U#Sv_/Ojgx}1kd+jEFe)cX         fwVCfYRWXghK9AR$-Ex.vktyrE5
+HAZG-EhuL&t4H:x}vc74HwFe|&Raj@Fy            w7>j!hev_JabEV(vIBqHMx.TcZGjwV0|c,i-!<W
+QJa%g3ufIJaPw3C;Yla[=peTQ,>5E?}vAR4zMpCD6v  PENeD&lyr@xKF
+ZazwVCLAJWzM?8fs{W%g#KvYZq[Mp(P
+
+Passphrases:
+tweak-boots-shun-pond-cone-wimp-happy-polar
+shut-acre-decay-thank-pagan-crown-snack-cadet
+slug-putt-twist-fresh-park-flock-deed-error
+music-rerun-mocha-acid-taps-boast-rule-clad
+churn-curvy-wreck-list-stove-bonus-ozone-atom
+```
+
+## Specifications
 Here's the synopsis from `makepass.zsh`, which explains how makepass should work:
 
 ```
@@ -119,30 +153,6 @@ Normal character set: `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234
 
 Special character set: `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&/()=?+-_,.;:<>[]{}|@*`
 
-### Example output
-
-```
-Normal passwords:
-ZmvQB4r23KnctqjoV8fAlObMNu9Yt               f-FS1k7yXwxeTIZk
-IpCL6RiHgh0DsJGzE_mvQB4r23KnctqjoV8fAlY     ANu9Yda5-FS1k7yXwxeTIZWPUpCL6RiHgh0Dsr
-vE_mvQB4r23KnctqjoV8fAlObMNu9YdaD           dS1k7yXwxeTIZu
-wpCL6RiHgh0DsJGzE_mvQB4r23KnctqjoV8fAN      XMNu9Yda5-FS1k7yXwxeTIZWPUpCL6
-uHgh0DsJGzE_mV                              N4r23KnctqjoV8fAlObMNu9Yda5-FS1k7yXwxy
-
-Passwords with special characters:
-L&ROH=NKTcti-U#Sv_/Ojgx}1kd+jEFe)cX         fwVCfYRWXghK9AR$-Ex.vktyrE5
-HAZG-EhuL&t4H:x}vc74HwFe|&Raj@Fy            w7>j!hev_JabEV(vIBqHMx.TcZGjwV0|c,i-!<W
-QJa%g3ufIJaPw3C;Yla[=peTQ,>5E?}vAR4zMpCD6v  PENeD&lyr@xKF
-ZazwVCLAJWzM?8fs{W%g#KvYZq[Mp(P
-
-Passphrases:
-tweak-boots-shun-pond-cone-wimp-happy-polar
-shut-acre-decay-thank-pagan-crown-snack-cadet
-slug-putt-twist-fresh-park-flock-deed-error
-music-rerun-mocha-acid-taps-boast-rule-clad
-churn-curvy-wreck-list-stove-bonus-ozone-atom
-```
-
 ## Benchmarks
 I started out using just zshs `time` to time the runtime, but recently I started
 checking out [hyperfine](https://github.com/sharkdp/hyperfine) which does a