.\" -*-Text-*-
.\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
.\"
.\" File:         phonewrd.1
.\" Description:  phonewrd man page
.\" Author:       Eric Haines, erich@eye.com
.\" Modified:     4/21/93
.\" Package:      phonewrd
.\"
.\" (c) Copyright 1993, Eric Haines, all rights reserved.
.\"
.\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
.TH PHONEWRD 1 "" ""
.ad l
.SH NAME
phonewrd \- find words or phrases for phone numbers

.SH SYNOPSIS

.BR phonewrd
[\fB-n \fInumerals allowed\fR]
[\fB-s \fIsingle letter words\fR]
[\fB-q \fIq mapping\fR]
[\fB-z \fIz mapping\fR]
[\fB-d \fIdictionary path\fR]
[\fB-l \fIword length\fR]
[\fB-m \fInumeral map\fR]
[\fB-v\fR]
[\fB-r\fR]
[\fB-c\fR]
[\fB-C\fR]
\fBphone_number1[*...]\fR [\fBphone_number2[*...] ...\fR]

.SH DESCRIPTION

.B phonewrd
finds words or phrases which match the input phone numbers.
It uses the dictionary word list
.I /usr/dict/words
by default, ignoring one letter words (see \fB-s\fR).
There are a wide variety of options available to allow various sorts of
pattern matching.
Words with apostrophes or other punctuation are acceptable.
If more than one phone number is given, each number and its combinations are
output.

If the input phone number ends with one or more \fI*\fR, e.g. \fI555-1212**\fR,
then the output phrases can be up to that many characters longer that the input
number.
This usually yields a few extra phrases, and
dialing those extra digits at the end normally doesn't cause problems.

The input phone number can have letters in it, in which case that digit is
forced to be that letter in any phrase.
This can help pare down a long output list for a number.

If the number is entirely letters, it is converted to numbers and output.

If you don't have a dictionary on your system, a free set of dictionary files
are available via FTP from prep.ai.mit.edu in /pub/gnu/ispell*.tar.z (you'll
also need "gzip" in this same directory to uncompress this archive).
.B phonewrd
understands the "affix" format used for the
dictionaries in ispell and expands words accordingly.

If you can't get your hands on any dictionary files,
look at the \fB-r\fR, \fB-c\fR, and (for the totally insane) \fB-C\fR options.
These options do not need a dictionary (and so will do either very little or
too much).

.SH Options
.ifn .TP 5
.ift .TP 15
.B -n \fInumerals allowed\fP
This option allows phone digits to be replaced by numerals, up to the limit
set.
For example
.B -n 2
means that any two digits of the phone number can be left as digits and not
made a part of any word.
This can help find phrases for phone numbers with poor letter combinations.
Note that numerals that have no corresponding letters
(i.e. 0 and 1 by default) do not count against this total, nor do one letter
words set using \fB-s\fR.
Default setting is 0.

.TP
.B -s \fIsingle letter words\fP
This option gives all allowed single letter words (including numeral "words",
e.g. "I love U 2").
Normally dictionaries have all letters of the alphabet as being legal words,
which gives a ton of useless phrases.
By default the only allowed single letter words are "a", "i", and "o".
As an example of how to change this,
.B -s abcdgimoptuxy248
means that any of these single letters are now considered words.
This can help find phrases for phone numbers with awful
letter combinations and in general open up more possibilities.
To have no single letter words at all, use \fB-s =\fR.

.TP
.B -q \fImapping\fP
This option maps the letter
.I q
to the given numeral.
For example,
.B -q 0
means that phone numbers with 0's in them can have \fIq\fR's
substituted for the 0's.
This usually doesn't help much anyway, and it's up to you to remember that
.I q
== 0, but there you go.
By default
.I q
is not mapped.

.TP
.B -z \fImapping\fP
Amazingly similar to \fB-q\fR.
This option maps the letter
.I z
to the given numeral.
For example,
.B -z 0
means that phone numbers with 0's in them can have \fIz\fR's
substituted for the 0's.
This usually doesn't help much anyway, and it's up to you to remember that
.I z
== 0, but there it is.
By default
.I z
is not mapped.

.TP
.B -d \fIdictionary path\fP
This option allows alternate dictionaries to be used.
For example,
.in +0.5i
.B -d /users/fred/dict/star_trek_words
.in -0.5i
will use (only) Fred's geek-speak dictionary.
Default is \fI/usr/dict/words\fR (or whatever it is on your system),
which is not used if any dictionary path is specified.

Multiple dictionaries can be used by specifying multiple paths.  For example,
to use the geek speak dictionary along with the regular system dictionary, do:
.in +0.5i
.B -d /users/fred/dict/star_trek_words -d /usr/dict/words
.in -0.5i
A path of "." means use the default dictionary, so quicker yet is:
.in +0.5i
.B -d . -d /users/fred/dict/star_trek_words
.in -0.5i
In this way additional
dictionaries can either replace or be added to the default.

Note that
.B phonewrd
understands the "affix" format used for the dictionaries of GNU's ispell and
expands words accordingly, so these can be used to add more words to the
search.

.TP
.B -l \fIword length\fP
This option allows a minimum word length to be set.
For example,
.B -l 3
means no words shorter than 3 letters are used for building phrases.
User defined single letter words (see \fB-s\fR) are not affected by this
option.
Single letter words from the dictionary are ignored no matter
what the setting (since most dictionaries include exciting words like "h",
"w" and so on).
Default is 1.

.TP
.B -m \fInumeral map\fP
For those of you from a different planet, this will remap the letters to
different numerals.
For example,
.in +0.5i
.B -m 2223334445556667.77888999.
.in -0.5i
is the default setting, a normal telephone.
The "\fB.\fR" (or any other non-numeric value) means don't map the letter to
any key.
You get a banana for using \fB-v\fR with this command.

.TP
.B -v
Verbose option:  words fitting into the various number slots are output
and other warnings and whatnot are all output to stderr.
This can help you "roll your own" if the program does not find anything to
your liking.

.TP
.B -r
This option is for those without a dictionary.
It simply outputs the letters
possible for each digit in a column so that you can search for combinations
more easily.
No dictionary search is done, so none is needed.

.TP
.B -c
This option is also for those without a dictionary.
It generates all
permutations of letters and numerals valid for the input phone number and
outputs these one per line.
If you do:

	phonewrd -c 234-5678 > junk1
.br
	spell junk1 > junk2
.br
	diff junk1 junk2 | grep "<"

you'll get any 7 letter words formed which pass the spell checker.
It's a long shot, but you never know...

.TP
.B -C
This option is also for those without a dictionary and too much disk space and
CPU time.
It generates all
permutations of letters and numerals valid for the input phone number and
outputs these one per line, plus it makes all permutations of spacing for
each of these permutations.
3^7 * 2^6 = 139968 phrases for a phone number without 0's and 1's.
Then send each one through your spell checker and if any errors are found,
discard it and go to the next.
It will take awhile, but this is the price you pay for not having any
dictionary available.

.SH EXAMPLES
.ne 4
.B phonewrd 542-5968
gives the words:
.br
    kick you
.br
    lick you

.ne 7
.B phonewrd 542-5968 -n 1
.br
allows more slack, letting one character be a numeral:
.br
    kick you
.br
    lick you
.br
    5 gal you
.br
    5 Hal you
.br
which gives a little wider range of possibilities.

.ne 5
.B phonewrd 5683968 -l 3
.br
gives words 3 characters or longer:
.br
    Jove you
.br
    loud you
.br
    love you

.B phonewrd 486-9364 -s aio248
.br
gives many combinations, but the
.B -s aio248
allows the extra combination
.br
    I 8 my dog
.br

.B phonewrd 787-3648*
.br
allows the extra combination
.br
    strength
.br
as one \fI*\fR at the end means up to 1 additional character can be output
at the end of the phrase.

.B phonewrd 861-2076
.br
doesn't yield much of anything, so setting \fI0\fR to \fIo\fR and
\fI1\fR to \fIi\fR:
.br
.B phonewrd 86i-2o76
.br
we get
.br
    unicorn
.br
so \fIun1c0rn\fR fits the original phone number.
Putting a letter in a phone number
forces the use of that letter in that position.

.B phonewrd -r 266-7883
.br
yields
.ne 3
.br
      a  m  m  p  t  t  d
.br
      b  n  n  r  u  u  e
.br
      c  o  o  s  v  v  f
.br
The letters for each numeral are output in columns and so can be more easily
searched by hand for interesting phrases.
Yes, I know you found \fIbon stud\fR
in there, but what seven letter word can be found?
If you find it, pat
yourself on the cranium for having a brain and being able to quickly cull
through the 2187 possibilities.

.B phonewrd -c 2667883
.br
will list all the possible combinations, e.g.
.br
    ammpttd
.br
    ammptte
.br
    ammpttf
.br
    ammptud
.br
    ammptue
.br
    ...
.br
which can then be run through a spell checker and so searched for seven
letter words (see the \fB-c\fR option for how to do this).

.B phonewrd 234-5678 -v
.br
will output all words which fit into the various places in the phone number.
For example, one output entry is:
.ne 2
.br
    Digit 5, length 3:
.br
     opt
.br
which means that for the fifth digit of the number, all words of length three
which fit (i.e. translate into "678" in this case) are displayed.

.SH TO BE DONE
It would be cute to be able to map numerals to strings, e.g. 460-2253 with
"0" mapped to "OPER" gives "inOPERable", or 434-4637 with "4" mapped to "for"
gives "FOReigner".

.SH AUTHOR
Eric Haines, erich@eye.com