.\" $Id: agm.6,v 1.10 1998/10/17 14:56:31 fraserm Exp $ .\" $Log: agm.6,v $ .\" Revision 1.10 1998/10/17 14:56:31 fraserm .\" added stdin options doco .\" .\" Revision 1.9 1998/03/08 23:02:15 fraserm .\" new email address .\" added xagm stuff .\" .\" Revision 1.8 1998/03/08 22:14:36 fraserm .\" in to get it out .\" .\" Revision 1.7 1996/10/25 19:11:37 fraser .\" updates changing spinny line to 2 digit percentage .\" \."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 \." .TH AGM 6 "$Date: 1998/10/17 14:56:31 $" .SH NAME agm - search for single- or multi-word anagrams .br xagm - Tcl/Tk front-end to agm .SH SYNOPSIS .B agm [ .BI global-options ] [ [ .BI word-options ] .BI word [ .BI word ] ] ... .br .B agm [ .BI global-options ] [ .BI - .br .B xagm .SH DESCRIPTION .IX "agm" "" "\fLagm\fP \(em search for anagrams" .IX "xagm" "" "\fLxagm\fP \(em search for anagrams" .LP If both .B agm and its Tcl/Tk front-end .B xagm are correctly installed, you probably won't need to read most of this manual page. Go play with .B 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... .LP If you have never used .B agm before, go right now to the section "EXAMPLES" to get the feel of it. .LP .B agm reads a central word file and any additional word files given with the .B + 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. .LP Before the search begins, .B 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 .B word may be of the form .LP .B verylargeword-dowry .LP in which case, the letters in .B dowry are removed from .B verylargeword before processing begins. Naturally, .B verylargeword must completely contain .B dowry (as in fact it does). Note that in .B agm .B word cannot have any spaces, unlike .B xagm where it can. .LP By default, .B 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 .B \-c (number of words) switch. .LP If .B 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. .LP "global-options" can be one or more of: .RS .TP .B \-q quiet; display just the anagrams, no status messages or statistics; to be sure this switch will work, give it first .TP .SB \-o set the maximum length of a line to .BI width (however the display may be messy if this is set below 80, which is the default); use .B \-o0 to display every anagram on a new line .TP .B \-t after the search completes, output CPU time statistics .TP .B \-s limit the CPU time used by .B agm to .B seconds. .TP .B \-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 .TP .B +wordfile read the file .B wordfile into the dictionary .TP .B ++ do not read the central word file .TP .B +- read a wordfile from the standard input .RE .LP "word-options" may be one or more of: .RS .TP .SB \-l for all following target words, search for anagrams where the average word length is at least .BI characters; .B \-l overrides any previous .B \-c .TP .B \-h (only affects the setting of the .B \-l switch) toggle hard minimum mode; search for anagrams where all words are at least of length , rather than at least .B averaging length (fastest switch, poorest set of anagrams) .TP .SB \-c for all following target words, search for anagrams of at most .BI words (faster than searching by average word length); .B \-c overrides any previous .B \-l .TP .SB \-p (only affects the setting of the .B -c switch) toggle partial mode; will display both full anagrams of X or less words (where X is the number given to the .B -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) .LP If "word-options" is a single "-" character, further word options and target words are read from standard input. .RE .SH EXAMPLES .LP The following examples work well with the supplied word file: .LP agm -c2 williamshatner leonardnimoy .LP agm -l4 -h davidletterman .LP This one is amusing: .LP agm -c2 billgates .LP However, this one is extremely dull (unlike a perl, of course): .LP agm -c2 larrywall .LP All candidate words for the above: .LP agm -c1 -p larrywall .LP All words that have no duplicate letters (i.e. "letters" doesn't qualify): .LP agm -c1 -p abcdefghijklmnopqrstuvwxyz .LP Two letter anagrams of every word in the file "targets": .LP (echo "-c2"; cat targets) | agm - .LP 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: .LP agm -c2 billgates -l4 billgates .LP agm -c2 williamshatner -l7 williamshatner .SH WORD LISTS .LP 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 .B 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. .LP For example, to add all words in the file .B newwords (where .B newwords may be any plain text), and create a new word list .B newlist use the command: .LP .B agm -w -q +newwords > newlist .LP .B agm will read .B newwords then the default list, sort the words removing any duplicates, then write out the remainder in order. The .B -q switch is needed to suppress the messages generated when initially reading the files. .LP Similarly, to compile a completely new list from several files, use a command of the form: .LP .B agm -q -w ++ +file1 +file2 +file3 > newlist .LP You could achieve the same effect with: .LP .B cat file1 file2 file3 | agm -q -w ++ +- > newlist .LP but that is slightly slower. .LP Note that because of the way the shell works, .B newlist should never be in the list of input files, since the shell will clobber it before .B agm gets to read it. .LP .B 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 .B agm will read all the headers as text. .SH NOTES .LP 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"). .LP Additionally, .B 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. .LP If you don't believe this is necessary, force .B agm to generate absolutely every anagram possible with a command like: .LP .B agm -l1 -h anythingatall .LP Now imagine this with single letter words, too. .LP .B 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. .LP 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 .B \-h "rejections" is always zero, since .B agm eliminates all words which are too short before beginning the search, so no anagrams can get rejected for this reason. .LP As a special case, when the output width is set to 0, .B agm does not display a .B ; character after each word. .SH BUGS .LP 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. .LP .B \-q does not suppress output from .B \-t .LP Switches cannot be combined; thus you cannot use .B -pq instead of .B \-p\ \-q .LP Occasionally .B 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. .SH AUTHOR .LP Fraser McCrossan