Add instructions

[berlincount]

I don't really consider myself a novice user, but - instructions would be highly welcome.

Racket is (still?) somewhat obscure, and I found myself completely stumped. The stock Ubuntu 'racket' seems to be too old for this code (version) 5.3.6, and even with the (slightly scary) shell installer from the website (6.1.1) it doesn't get much better:

$ racket letter-frequency.rkt
letter-frequency.rkt:12:9: collection not found
for module path: shelly/random-password
collection: "shelly"
in collection directories:
/home/count/.racket/6.1.1/collects
/usr/local/share/racket/collects
... [152 additional linked and package directories]
context...:
show-collection-err
standard-module-name-resolver
standard-module-name-resolver

... I don't know how to proceed, the documentation is non-obvious, Google doesn't help, and all I really wanted to do is chuck a copy of the Cryptonomicon at it and get a few useful passwords.

Can extended the README to provide concrete steps for the unitiated user to teach how to do that?

I consider the concept awesome, but I don't know how many might have given up before even getting this far.

Cheers!

[jbclements]

Your comment is 100% on the money. In particular, the shelly dependency is really unforgivable; that's a private collection of mine, and there's literally no way to get it from the web. Really, at a minimum, I should make it possible to install this code by running

raco pkg install molis-hai.

I bet I can do this in ... 30 minutes? Let me try.

[jbclements]

Okay, Done! (38 minutes)

I cleared up most of the foreign dependencies, and made it into a package. You should be able to run letter-frequency.rkt without installing shelly, or indeed any non-off-the-shelf packages.

[berlincount]

Hmmm, nah, I'm not agreeing with this being closed, sorry :)

While you may have resolved the dependencies, it still isn't possible to run it without more knowledge:

$ raco pkg install molis-hai
Resolving "molis-hai" via http://download.racket-lang.org/releases/6.1.1/catalog/
Resolving "molis-hai" via http://pkgs.racket-lang.org
Using cached14297804891429780489300 for https://github.com/jbclements/molis-hai/tarball/0da4f68414ef8cb786d85dd613e2f121f56f6ae8
The following uninstalled packages are listed as dependencies of molis-hai:
data-enumerate-lib
Would you like to install these dependencies? [Y/n/a/?] y
Resolving "data-enumerate-lib" via http://download.racket-lang.org/releases/6.1.1/catalog/
Resolving "data-enumerate-lib" via http://pkgs.racket-lang.org
Using cached14297804941429780494395 for https://github.com/racket/data/tarball/1619c11bc74d58a6bc24ba2fce55842fce40a195
The following out-of-date packages are listed as dependencies of data-enumerate-lib:
base (have 6.1.1, need 6.1.1.8)
Would you like to update these dependencies? [Y/n/a/?] y
raco pkg install: package installed in a different scope
package: base
current scope: user
installed in scope: installation

... with only 6.1.1 being available for download.

... plus, you didn't add a single line of additional instructions :)

But I'm getting some results now with "racket letter-frequency.rkt", so there's that .. cheers!

[jbclements]

Ouch! I see that data-enumerate-lib is a bit more bleeding-edge than I was aware of. This will be solved for us when 6.2 is released, in a month or so. In the meantime, what kind of instructions would be most useful? Instructions on installing the package, or instructions on using your own corpus?

(reopened.)

[berlincount]

Well, the git version seems to work with the binary 6.1.1 distribution (at least after the raco call), at least it seems to generate some output:

count@hoschi:~/repos/github-jbclements-molis-hai/molis-hai$ racket letter-frequency.rkt
6^ZC6JVny
YAwyk47J-
PYchm0oh0
7](S+s5jb
[-EMsRJhh
MtOMmzoGW
T)[a-Ed=x
xdWYbYB@o
bits of entropy: 56.40107886625412
77
'("passwords of order 1" (" bery ids wn lso" "0523514551442564") "ven st’sis Thoor" "chi wisadend L" "thitolighisady at" "agnprhero Ic" "lio stoy hextla" "lid wan wearontist" "tcen gheroues tat" "itlant B want t l")
'("passwords of order 2" (" som, say.o.=’$D. Track i" "4032704314212110212533212") "says,’’Sirld sou coile" "for pal He hat jud," "upturvats, theare " "paturead Comanom" "ovied dentry hten" "ne Moh,’’ wrones " "lat, tones lortani" "sor fromen Nippier w")
'("passwords of order 3" (" them, hunnine-timedictuati" "300133045151126111152222121") "in a talks. They withmethink M" "a time subject. You word," "There meathe does thandy as" "doed.) Evidea int Gen. I" "ther justy, action to don?" "box thrashink ligen " "tone entuardwood.* Avi i" "Chinior applyworniv")
cpu time: 7349 real time: 7352 gc time: 30
average length of passwords using 2-grams/noseed: 47537/2500
12498/625
'("passwords of order 4" (" linkie jar our arose for g" "a00023114132132144210242111") "the traffinges. Towards, gar" "Huk contractity, all, ask" "through busy identirelimining " "air animal hold. Within " "doing? In an on Glasgow of. Or " "you, yo-ho point veiller, this" "onto-appeasantly: he arishabby" "| Tabasements, the head in rh")
'("passwords of order 5" (" where. Q: What door, to refe" "a0000021900201012141303315151") "there ends. Against EpiphyteB" "climax. Randy save meal wire. H" "project a documen of you trying ts" "can follow. He’ll gesturizing a blad" "posit into tomb. It is analoging t" "sting if his Walking men" "himself, would belly: a Biblication.) Use thu" "come fishin Detailed. It taken fel")

... well well. :)

In my book, good code documentation teaches the reader:

• Build requirements (seems to be a scripted, none needed)
• Runtime requirements and ideally where to get them (racket 6.1.1.8?!?)
• Expected inputs / API conventions (edited a filename in two places, seems to work?)
• Provided output (and how to interprete it. no idea. didn't expect the JS at all!)

Extra points whatever creates outputs from inputs has some kind of architecture/code layout description, so someone can follow along - I don't know scheme, let alone racket, so I didn't even really start looking into it ;) Might just be a "some assembly required" situation in your view, but hey ;)

I'd love to be able to tweak the code to stop having special characters at the start/end of the password, configure password length limits (mostly upper) and character policy (we've got up to 32 characters with a requirement of upper, lower, number, and special characters, grr), and generally a way to get the password to be as natural-language as possible. But this is a very good start!!! :)