1 files changed, 107 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..93bd739
--- /dev/null
+++ b/README.md
@@ -0,0 +1,107 @@
+# makepass
+
+*This is a work in progress!*
+
+I wrote `makepass` long ago 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
+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.
+
+Around then I found some joy in tinkering with the script, and I did some
+optimalization of the zsh-script to minimilize forks and runtime. It is now pure
+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
+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.
+
+### Character sets
+
+Normal character set: `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_`
+
+Special character set: `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!#$%&/()=?+-_,.;:<>[]{}|\@*`
+
+### Example output
+
+```
+Normal passwords:
+7B39aQZSm9P9BYZ8gBu0rLNIjNP                 SLztHlkZ5IsG5VaMfeF_JgttZOfZZa5
+RxnvFtdztaX                                 jZ6lAAA2a38ip5gwr_LuIDOys2Co
+kn3hGdRMyIyz1sJic5iNL6N5                    3Z9wWyScY4qqQYh
+wigDZcuGDlWDyW4UKNtC_NHg9ITVfLOUq4Iq4R      dJJSK10_SDk7q6Jk
+41uPXf5d-jYCh7wgc0ZOy                       hTTcPdqGg5NWCyf7vcFp3su4kGQ0aIyP7xK7WVcp
+
+Passwords with special characters:
+p0M4b1%XP.BsIDH1ub[q9b+3nSR84!W$<e          ZLz80iY]ZT%RcA*H
+txX4e-vYf0ZO2hG20h[d                        Y!H0d1K4Vz*2z6U=?Yotk
+hw!b;bK||[Bx                                gmrqB$nz[k!/fwV4>W%W
+
+Passphrases:
+brisk-gong-gag-open-life-boil
+womb-nanny-stove-word-ajar-ocean
+sage-barge-barge-five-poise-coach
+lunar-juror-savor-unit-boil-sleep
+cloth-nap-word-shun-gulp-sedan
+guide-fray-dial-grid-candy-wick
+```
+
+## 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
+nice job.
+
+Here are the results so far:
+
+```
+% hyperfine --time-unit=millisecond --warmup=1 --shell=none ./*(.)
+Benchmark 1: ./makepass.bash
+  Time (mean ± σ):     469.3 ms ±   3.6 ms    [User: 92.0 ms, System: 734.0 ms]
+  Range (min … max):   463.6 ms … 474.3 ms    10 runs
+
+Benchmark 2: ./makepass.pl
+  Time (mean ± σ):      38.8 ms ±   0.4 ms    [User: 18.2 ms, System: 19.0 ms]
+  Range (min … max):    38.1 ms …  40.1 ms    77 runs
+
+Benchmark 3: ./makepass.sh
+  Time (mean ± σ):     1261.6 ms ±  18.5 ms    [User: 298.0 ms, System: 2030.0 ms]
+  Range (min … max):   1237.4 ms … 1291.8 ms    10 runs
+
+Benchmark 4: ./makepass.zsh
+  Time (mean ± σ):      27.2 ms ±   0.7 ms    [User: 12.0 ms, System: 13.0 ms]
+  Range (min … max):    25.5 ms …  29.1 ms    111 runs
+
+Summary
+  './makepass.zsh' ran
+    1.43 ± 0.04 times faster than './makepass.pl'
+   17.27 ± 0.49 times faster than './makepass.bash'
+   46.43 ± 1.43 times faster than './makepass.sh'
+```