Subject: updated protocol for webster

From: George M Cathey <gmcathey>
Date: Mon, 06 Apr 87 00:29:35 EDT

This is the most up-to-date version of the dictionary protocol
as of April 5, 1987.  Please send any recommendations or comments
to info-dictionary.

DICTIONARY server protocol:

Contact name is "DICTIONARY".  A full connectional is established
(additional data in the RFC is ignored, there's no simple mode)

Command lines to the server are of the form

	COMMAND[<space>ARGUMENT]<NL>

where the part in brackets, [], is optional.  <space> is ASCII space,
octal 40, and <NL> is the LispMachine NewLine character, octal 215.

The server responds with a single line of the same format, and then if
there's additional data it comes next, followed by an EOF packet.

The actual response will be either

	ERROR<space>RECOVERABLE<error message><NL>
or	ERROR<space>FATAL<error message><NL>

or a command-depenedent response.  FATAL-type errors are just that,
fatal, and the server will go away after sending the ERROR message.

Command:	HELP<NL>

This command will send back the text of this document, the dictionary
protocol, followed by <EOF>.

Command:	DEFINE<space>WORD<NL>

This is the command that asks for the defintion of a word from the
dictionary.  The possible response are:

	WILD<space>0<NL>

or
	WILD<NL>
	<word#><space><word1><NL>
	<word#><space><word2><NL>
		. . .
	<word#><space><wordN><NL>
	<EOF>

A WILD response is given when the word to be defined contained
wildcard characters ('%' which matches exactly one character, or '*'
which matches 0 or more characters).  If the wild string had no
matches, a WILD response with argument 0 is returned.  If there are
one or more matches, a WILD with no arg is returned, and then the
matching words are sent, one per line, followed by an EOF packet.  For
each returned word there is a word#, a string of ASCII digits
representing a decimal number.  For user convenience, that word#
may be specified in place of the word itself, in a DEFINE request.

	SPELL<space>0<NL>

or
	SPELL<NL>
	{ same response as WILD }

When a word is specified that couldn't be found verbatim, Webster
attempts to Do What You Mean, and try to fix common typos (transposed
letter, one missing or one additional letter, or one letter wrong).
If any such matches are found, a SPELL response is returned, listing
all the "possible" words.  If no such words were found, (e.g. it
couldn't make ANY sense out of the input word), a SPELL with argument
0 is returned.

	DEFINITION<space>n<NL>
then n	{ WILD-response-like lines }
then	<any amount of ASCII text>
	<EOF>

A DEFINITION response means the word matched an entry, and the definition
follows.  The argument (always present), n,  is the # of cross-references
in the definition that might prove interesting.  If n > 0, then follows
one line per cross-reference, in the same fork as the WILD responses.  Then
comes the body of the definition, followed by and <EOF>

Command:	COMPLETE<space>word<NL>

Is used to simulate is action of the TENEX/TWENEX <escape> completion
feature.  "word" is usually the beginning portion of a word that is
expected to be unique.  The response is either

	AMBIGUOUS<space>n<NL>

or
	COMPLETION<space>full-word<NL>

If the partial word you specified matches zero or more than one
dictionary entry, an AMBIGUOUS response is given, the argument
being the number of matches.

If the partial word matches one and only one entry, a COMPLETION
reply is sent back, containing the full text of the word that was
completed.  Note that COMPLETION and wildcard characters CAN be
mixed, so the user program should check the word being completed,
and if any wildcard characters exist (in the supplied part),
the entire word should be retyped, not just what was competed.

Command:	ENDINGS<space>word<NL>

This command is used to simulate the "?" TENEX/TWENEX feature.
The response is either

	ENDINGS<space>0<NL>

or
	ENDINGS<NL>
	{ WILD-like word-list }

What ENDINGS actually does is append a "*" to the word you gave and
check for WILD matches.  If there were none, you get the ENDINGS with
argument 0 response, else a WILD-like list of words.  NOTE that even
tho the word-line returned have a word#, that number does not work
the same as for WILD or SPELLING.  A number is present on the line so
that the response is in the same format as that of WILD or SPELLING,
to make it a little easier on the user program.  Those number shouldn't
be passed back as they don't mean anything.

Command:	SPELL<space>word<NL>

The SPELL command is for people who want to (ab)use the dictionary
server as a SPELL server.  The word is looked up, and if it matches
zero or one entries you get a

	SPELL<space>matches<NL>

response where matches is 0 or 1.

If the word isn't found, but has possible alternate spellings, those
are returned exactly like a SPELLING response to DEFINE.


Command: PART-OF-SPEECH<space>word<NL>

The PART-OF-SPEECH command asks only for the parts
of speech of a word from the dictionary.  The possible
responses are:

	PART_OF_SPEECH<NL>
	<part of speech><NL>
	<part of speech><NL>
	      . . .
	<part of speech><NL>
	<EOF>

Following the PART-OF-SPEECH response are the different
parts of speech of the word.

            Frequency   Code   Part of Speech          Example
            ____________________________________________________________
                42590   n      noun
                13250   aj     adjective
                 4972   vt     verb, transtitive
                 2423   vb     verb
                 1432   av     adverb
                 1363   vi     verb, intransitive
                  516   cf     combining form
                  164   pp     preposition
                  150   nc     noun combining form
                  121   tm     trademark
                  108   pn     pronoun
                  107   ns     noun suffix
                   96   cj     conjunction
                   94   ij     interjection
                   74   pf     prefix
                   51   js     adjective suffix
                   12   vs     verb suffix
                   10   vp     verb imperative
                    6   as     adjective suffix
                    4   va     verbal auxiliary
                    3   ia     indefinite article
                    2   vm     verb impersonal, past   meseems, methinks
                    2   vc     verb combining form     -lyze, -sect
                    2   sf     suffix                  -est, -fold
                    2   da     definite article        the, ye
                    1   np     noun plural suffix      -s
                    1   is     interjection suffix     -o

If the word contains wildcard characters, then a
WILD response will be returned, just like for the
DEFINE command.

If the word is not found in the dictionary, then a 
SPELL response will be returned, just like for the 
DEFINE command.

Command: PRONUNCIATION<space>word[<space>part-of-speech]<NL>

The PRONUNCIATION command asks only for the pronunciation of 
a word from the dictionary.  The possible responses are:

	PRONUNCIATION<NL>
	<pronunciation>
	<EOF>

Following the PRONUNCIATION response is the pronunciation
of the word. If a part-of-speech is specified, then the
corresponding pronunciation is returned.  If no part-of-speech
is specified, then the first pronunciation found is returned.

A list of possible parts-of-speech is found on the 
PART-OF-SPEECH command page.

If the word contains wildcard characters, then a
WILD response will be returned, just like for the
DEFINE command.

If the word is not found in the dictionary, then a 
SPELL response will be returned, just like for the 
DEFINE command.

If the word is not the specified part-of-speech, then 
the response will be:

	NO-SUCH-PART-OF-SPEECH<NL>

Command: RAW-MODE<NL>

The RAW-MODE command requires the server to send the 
data in its "raw" form; that is, just as it exists in the
database file.

The response is:

	RAW-MODE-OK<NL>

Command: FORMAT-MODE<space>format-option<NL>

The FORMAT-MODE command requires the server to parse
(make it human readable) the data before sending the 
information.

The format-options are:
** none decided yet, but options may include: **
-variable width screen
-tty types
-others

The response is:

	FORMAT-MODE-OK<NL>

Command: MODE<NL>

The MODE command requests the server to tell the client
which mode the server is in.

The possible responses are:

	FORMAT-MODE-OK<NL>
	<format-option><NL>
	<format-option><NL>
	  .   .   .   .
	<format-option><NL>
	<EOF>

This response indicates the server in the format mode.

	RAW-MODE-OK<NL>

This response indicate the server in the raw mode.

yours,

george cathey