From 6abcf20f5cee0409e0b705edbfe1ebb3a38d63bd Mon Sep 17 00:00:00 2001
From: mdw <mdw>
Date: Thu, 9 Jun 2005 17:52:38 +0000
Subject: [PATCH] Fix documentation for mkphrase.  Oops.

---
 Makefile.m4 |   2 +-
 mkphrase.1  | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 mkphrase.c  |   4 +-
 3 files changed, 135 insertions(+), 3 deletions(-)
 create mode 100644 mkphrase.1

diff --git a/Makefile.m4 b/Makefile.m4
index c462e0b..b8d9316 100644
--- a/Makefile.m4
+++ b/Makefile.m4
@@ -329,7 +329,7 @@ changequote(`, ')
 ## --- Documentation ---
 
 man_MANS = \
-	key.1 dsig.1 cookie.1 catcrypt.1 catsign.1 hashsum.1 \
+	key.1 dsig.1 cookie.1 catcrypt.1 catsign.1 hashsum.1 mkphrase.1 \
 	keyring.5 pixie.1
 
 ## --- Other handy definitions ---
diff --git a/mkphrase.1 b/mkphrase.1
new file mode 100644
index 0000000..56141f3
--- /dev/null
+++ b/mkphrase.1
@@ -0,0 +1,132 @@
+.\" -*-nroff-*-
+.ie t \{\
+.  if \n(.g \{\
+.    fam P
+.  \}
+.  ds ss \s8\u
+.  ds se \d\s0
+.  ds us \s8\d
+.  ds ue \u\s0
+.  ds *b \(*b
+.\}
+.el \{\
+.  ds ss ^
+.  ds se
+.  ds us _
+.  ds ue
+.  ds *b \fIbeta\fP
+.\}
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.TH mkphrase 1 "9 June 2005" "Straylight/Edgeware" "Catacomb cryptographic library"
+.SH NAME
+mkphrase \- generate passphrases with guaranteed minimum entropy
+.SH SYNOPSIS
+.B mkphrase
+.RB [ \-p ]
+.RB [ \-b
+.IR bits ]
+.RB [ \-g
+.IR generator ]
+.br
+	
+.RB [ \-n
+.IR count ]
+.RB [ \-r
+.RI [ min\fB\- ] max ]
+.IR wordlist ...
+.SH DESCRIPTION
+The
+.B mkphrase
+program generates pronounceable but random passphrases in such a way
+that they're guaranteed to have at least a given level of entropy.
+.PP
+The program generates phrases using a wordlist.  Usually this will be
+something like
+.BR /usr/share/dict/words ,
+though you can use anything you want.  Wordlist files are expected to
+contain whitespace-separated words.  Letters are smashed to lowercase;
+apostrophes are retained; other funny characters are ignored.
+.PP
+Options provided are:
+.TP
+.B "\-h, \-\-help"
+Write a help summary for
+.B mkphrase
+to standard output and exit.
+.TP
+.B "\-v, \-\-version"
+Write 
+.BR mkphrase 's
+version information to standard output and exit.
+.TP
+.B "\-u, \-\-usage"
+Write a really brief usage summary for
+.B mkphrase
+to standard output and exit.
+.TP
+.BI "\-b, \-\-bits=" bits
+Set the minimum entropy for acceptable phrases.  The default is 128
+bits.  This might increase in future.
+.TP
+.BI "\-g, \-\-generator=" generator
+Use the given
+.I generator
+to construct passphrases.  See below.  The default generator is
+.BR markov .
+.TP
+.BI "\-n, \-\-count=" count
+Produce 
+.I count
+phrases.  The default is to produce only one.
+.TP
+.B "\-p, \-\-probability"
+After each phrase, write the entropy of the passphrase, in bits.
+.TP
+.BR "\-r, \-\-range=" [\fImin - ]\fImax
+Set a range for acceptable word lengths.  The default is to allow
+(almost) arbitrary length words, though these can be hard to remember.
+.PP
+The following phrase generators are implemented.
+.TP
+.B markov
+Builds a Markov model of the words in the wordlist(s).  It then uses
+this to produce new `words' with similar statistical properties.
+They're usually pronounceable and often absurdly memorable.
+.IP
+Here's how it actually works.  The program builds a big table which
+remembers how often each given letter occurs given the three preceding
+letters.  There is a special placeholder letter for `before-the-start',
+and another for `end-of-word'.  On output, we remember the last three
+letters emitted as our `state': then we choose a letter to emit at
+random, with the probability for each choice determined by how often it
+turned up following the letters in the state in the wordlists.  The new
+letter is then shifted into the state and we try again, until we choose
+the end-of-word letter.  The initial state is three before-the-start
+placeholder `letters'.
+.IP
+The word length limits are imposed by filtering the output of the Markov
+word generator.  Strict limits make the program run slowly.  The
+generator tracks the probability it had of making each choice of letter
+as it goes, and we just produce words until the phrase is sufficiently
+entropic.
+.TP
+.B wordlist
+Very simple: just choose random words from the wordlist until the phrase
+has enough entropy.  Phrases are usually longer than Markov-generated
+ones.
+.SH BUGS
+Three letters work fairly well for English.  However, they may not work
+so well for other languages.
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>.
diff --git a/mkphrase.c b/mkphrase.c
index 3954418..3a26ed9 100644
--- a/mkphrase.c
+++ b/mkphrase.c
@@ -1,6 +1,6 @@
 /* -*-c-*-
  *
- * $Id: mkphrase.c,v 1.4 2004/04/08 01:36:15 mdw Exp $
+ * $Id$
  *
  * Generate passphrases from word lists
  *
@@ -274,7 +274,7 @@ static void version(FILE *fp)
 static void usage(FILE *fp)
 {
   pquis(fp, "\
-Usage: $ [-p] [-b bits] [-g gen] [-n count] [-r [min-]max] wordlist...\n\
+Usage: $ [-p] [-b BITS] [-g GEN] [-n COUNT] [-r [MIN-]MAX] WORDLIST...\n\
 ");
 }
 
-- 
2.11.0