AGM(6)

."Revision 1.6 1996/10/23 15:43:08 fraser ."minor toggle tidy ." ."Revision 1.5 1996/10/07 21:31:50 fraser ."-t now generates CPU time statistics, not elapsed time ." ."Revision 1.4 1996/09/27 14:01:13 fraser ."updated manual to reflect changes to command-line switch processing ." ."Revision 1.3 1996/09/16 14:50:04 fraser ."changed date to use RCS keyword ." ."Revision 1.2 1996/09/13 20:56:10 fraser ."added stuff about reading wordfile from standard input ." ."Revision 1.1 1996/09/12 14:27:13 fraser ."Initial revision ."

NAME
agm - search for single- or multi-word anagrams
xagm - Tcl/Tk front-end to agm

SYNOPSIS
agm [ global-options ] [ [ word-options ] word [ word ] ] ...
xagm

DESCRIPTION

If both agm and its Tcl/Tk front-end xagm are correctly installed, you probably won't need to read most of this manual page. Go play with xagm and come back here if there is stuff you still can't do (create extra word lists, for example). If you're back already, then...

If you have never used agm before, go right now to the section "EXAMPLES" to get the feel of it.

agm reads a central word file and any additional word files given with the + prefix (word files are any text file with distinct words separated by whitespace), converts them to lower-case, and (if required) sorts them. Using this, it outputs anagrams of all search words given on the command line.

Before the search begins, word is converted to lower-case, and may be any sequence of characters not including the "-" (minus) character, although it is not normally useful to use non-alphabetic characters. Optionally word may be of the form

verylargeword-dowry

in which case, the letters in dowry are removed from verylargeword before processing begins. Naturally, verylargeword must completely contain dowry (as in fact it does). Note that in agm word cannot have any spaces, unlike xagm where it can.

By default, agm searches for anagrams with an average word length of one-third of the length of the search word, but always at least 2. This gives the richest set of anagrams, but it's usually pretty slow. For faster performance, use the -c (number of words) switch.

If agm is writing to your terminal, it displays two digits at the current cursor position to indicate the percentage of the search completed so far.

"global-options" can be one or more of:

    -q  quiet; display just the anagrams, no status messages or statistics; to be sure this switch will work, give it first

    -o<width>
        set the maximum length of a line to width (however the display may be messy if this is set below 80, which is the default); use -o0 to display every anagram on a new line

    -t  after the search completes, output CPU time statistics

    -s<secs>
        limit the CPU time used by agm to <secs> seconds.

    -w  instead of searching for anagrams, write out the dictionary, then exit; this is used to compile word lists for future use, see the section WORD LISTS

    +wordfile
        read the file wordfile into the dictionary

    ++  do not read the central word file

    +-  read a wordfile from the standard input

"word-options" may be one or more of:

    -l<len>
        for all following target words, search for anagrams where the average word length is at least <len> characters; -l overrides any previous -c

    -h  (only affects the setting of the -l switch) toggle hard minimum mode; search for anagrams where all words are at least of length <len>, rather than at least averaging length <len> (fastest switch, poorest set of anagrams)

    -c<words>
        for all following target words, search for anagrams of at most <words> words (faster than searching by average word length); -c overrides any previous -l

    -p  (only affects the setting of the -c switch) toggle partial mode; will display both full anagrams of X or less words (where X is the number given to the -c switch) and partial anagrams of exactly X words (i.e. anagrams which use some but not all of the letters of the target word)

EXAMPLES

The following examples work well with the supplied word file<:

agm -c2 williamshatner leonardnimoy

agm -l4 -h davidletterman

This one is amusing:

agm -c2 billgates

However, this one is extremely dull (unlike a perl, of course):

agm -c2 larrywall

All candidate words for the above:

agm -c1 -p larrywall

All words that have no duplicate letters (i.e. "letters" doesn't qualify):

agm -c1 -p abcdefghijklmnopqrstuvwxyz

A two double examples; these show the difference in speed between using -c and -l, the first is fairly trivial, the second is pathological; both generate pretty much the same results twice:

agm -c2 billgates -l4 billgates

agm -c2 williamshatner -l7 williamshatner

WORD LISTS

If you wish to extend the (supplied) default word list, or you wish to compile your own list separate from the default one, you can use agm to compile one from any set of good, large text files, possibly in conjunction with the default list. While this is not necessary, and you can use other text files directly, it will make future startups of the program much faster.

For example, to add all words in the file newwords (where newwords may be any plain text), and create a new word list newlist use the command:

agm -w -q +newwords > newlist

agm will read newwords then the default list, sort the words removing any duplicates, then write out the remainder in order. The -q switch is needed to suppress the messages generated when initially reading the files.

Similarly, to compile a completely new list from several files, use a command of the form:

agm -q -w ++ +file1 +file2 +file3 > newlist

You could achieve the same effect with:

cat file1 file2 file3 | agm -q -w ++ +- > newlist

but that is slightly slower.

Note that because of the way the shell works, newlist should never be in the list of input files, since the shell will clobber it before agm gets to read it.

agm is very dumb at deciding on word boundaries; it splits words at any non-alphabetic or non-numerical character, thus "don't" will be read as two words, "don" and "t". The best source files are probably plain non-technical pieces, perhaps on-line literature. Failing that, you can use anything with text in, mail messages, news articles, manual pages, but be aware you will end up with a lot of garbage words especially from mail messages, since agm will read all the headers as text.

NOTES

The switches to restrict searches by number of words or by length of words are necessary because of the nature of most word files on Unix systems, which contain many "dross" words (very short words, such as "an", abbreviations such as "ie", and acronyms, such as "DC" and "AAA").

Additionally, agm silently filters out any single-letter words because although some valid anagrams could come from them, the price to be paid in garbage output is too great.

If you don't believe this is necessary, force agm to generate absolutely every anagram possible with a command like:

agm -l1 -h anythingatall

Now imagine this with single letter words, too.

agm tries to provide enough switches to allow you to be fairly discriminating and avoid too much "mince" (lots of anagrams comprising very short words, tedious to wade through), but in the process often misses some "obvious" anagrams.

There are several other anagram-generating programs available on the Internet; agm is no better or worse than any of them, merely different. With the same word list and target word, all the programs to some degree or other generate different output. For links to these programs, as well as to some freely-available word lists, check out the Anagrams FAQ at

http://www.wordsmith.org/awad-cgibin/anagram

My thanks to Anu Garg <anu@wordsmith.org> (the maintainer of the page) for pointing this out to me.

On the trailing info line, "rejections"+"ok" does not always equal "permutations"; "permutations" is the number of paths explored, "rejections" is the number of correct anagrams rejected because the average word length was too low, or the number of words is too high. With -h "rejections" is always zero, since agm eliminates all words which are too short before beginning the search, so no anagrams can get rejected for this reason.

As a special case, when the output width is set to 0, agm does not display a ; character after each word.

BUGS

A bit of a memory dog; initially allocates memory roughly double the total size of all word files read, and sometimes a lot more while processing.

-q does not suppress output from -t

Switches cannot be combined; thus you cannot use -pq instead of -p -q

Occasionally agm will, from perfectly innocent words, generate double-meanings of extreme suggestiveness. Actually, this isn't a bug, it's a feature, unless you have to explain to a small child why you are laughing.

AUTHOR

Fraser McCrossan <fraserm@gtn.net>