[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: fun with last-minute, major changes.
Nits:
----
You should use '"' whenever you want a '"'
to show up in plain text.
I'm not sure "prepend" is really a word.
M-x query-replace "prepend" "prefix"
e.g., "MCP messages in a package should be created
by prefixing the package name to the message name."
In your diagram:
---------------
Change "in-band messages" to "in-band lines". In fact, just *don't*
use "message" to refer to in-band stuff; as far as MCP knows/cares,
there is *NO* structure to the in-band data beyond it being a
sequence of lines. Lots of things simplify if you reserve the term
"message" strictly for MCP messages.
There's at most one other place where you use "in-band message" and
that's easily changed.
Then, change "out-of-band messages" to "messages",
MCP/out-of-band messages now being the only kind of messages
we ever talk about (except for that one paragraph in the
definitions section that talks about "network messages"
but keep reading...).
That "messages" are derived from "out-of-band lines" is
still clear from the diagram, so removing the "out-of-band"
qualifier on messages doesn't lose you anything.
Change "MCP parser" to either "MCP parser/formatter" or
"MCP parser/unparser". These are bi-directional streams, after all.
Terminology:
-----------
I've entirely rewritten the definitions section.
The changes are almost entirely cosmetic, but
here's what I was trying to address:
(*) Mention the higher-level notion of "session",
(i.e., stream of *messages* as opposed to stream of network lines)
the one that's used most often...
(*) Replace uses of "agent" (which I originally used to mean "client
or server") with "connection endpoint" (as used elsewhere) to make
usage consistent across the entire document.
Actually, I find "connection endpoint" to be a little too
low-level. When I hear it, I tend to think "ethernet card", but
maybe that's just me. I think "agent" is better...
... in other words, feel free to change "connection endpoint"
back to "agent", but if you do, you should change all of the
other occurrences as well.
In any case, whatever term you use deserves its own <DT>.
(*) The important characteristic of "in-band"-ness is that in-band
is the *default* channel. That sentence should go first.
That the translation layer looks for #$# to make the in-band/OOB
distinction is secondary (and feel free to remove the two
sentences that start with "All network lines..." if you think
things are now clear enough without them).
(*) Removed duplicate descriptions (e.g., how quoting is done or
how OOB lines get parsed into messages; this is too much to put
in a definitions section) and put in forward references
(whee... HTML is c0ol!).
(*) Got rid of "Network Messages" since this term appears
nowhere else. To fix what I believe its introduction was
trying to address, I changed the definition of "MCP messages"
(now just "Messages") to the effect that
a message is just something consisting of a name, authkey, and
a bunch of arguments; end of story. The question of how
exactly we parse it out of a sequence of out-of-band lines
can wait...
(*) Some people may find it confusing that we use "message" to
refer to both message instances and message classes.
I'm guessing you don't want to substitute "message classes"
throughout the rest of the document, so I'm hoping a simple
"messages (i.e., message classes)" in the definition of
"package" will give people the right idea...
Here goes (pray that MSExchange doesn't garble this too badly).
BTW, the blank lines are not intended to be significant
(i.e., don't feel obliged to put in <P> tags):
- - - - - - - - - - - - - -
<DL>
<DT> Server
<DD> The MUD "world".
A network service which implements the MUD's shared space.
<DT> Client
<DD> A program used to connect to a MUD server.
<DT> Connection Endpoint
<DD> Since, for most part, MCP is peer-to-peer and has no built-in
concept of "client" or "server",
we use <EM>connection endpoint</EM> to refer to either a
client or a server.
Likewise "implementations" should be taken to mean
either client or server implementations of MCP.
Where clients and servers need to behave distinctly, the specification
will refer to "clients" or "servers" specifically.
<DT> Session
<DD> A <EM>session</EM> is a bidirectional stream of
<EM>network lines</EM>.
MCP requires that each direction of this stream guarantee ordered,
reliable message delivery, but there need not be synchronization
between the two directions.
The standard implementation of a session is a TCP connection;
however, any protocol which meets the session requirements may be used.
The term "session" is also used to refer to the
bidirectional stream of MCP <EM>messages</EM>
derivable from a given stream of network lines.
<DT> Network Lines
<DD> A <EM>network line</EM> consists of a sequence of (ASCII) bytes
terminated by a network newline. MCP does not impose a line-length
restriction, and the definition of "network newline" depends on
the
network over which MCP is carried (and consequently is not specified
here). An connection endpoint receiving a network line must
interpret the line as an <EM>in-band</EM> or <EM>out-of-band</EM>
line.
<DT> In-band lines
<DD>
<EM>In-band</EM> lines are those that are to be processed by a
connection endpoint in the default manner, e.g., being interpreted as
ordinary (MUD) command input by a server or being immediately
displayed to a user by a client in its default window.
MCP places no restriction on the form/contents of in-band data apart
from their division into lines and the quoting requirements
described <a href="#netlintran">below</a>.
All network lines not beginning with the literal string <SAMP>#$#</SAMP>
are interpreted as in-band lines.
<DT> Out-of-band lines, message lines
<DD>
<EM>Out-of-band</EM> lines are those that are to be processed in some
non-default manner, e.g., lines sent to a client that are directed at
some specific client facility, or lines sent to a server that are not
part of the main command stream.
MCP is a standard for the format/transmission of these out-of-band
lines.
Out-of-band lines are also referred to as MCP <EM>message lines</EM>.
All network lines beginning with the literal string
<SAMP>#$#</SAMP> are interpreted as out-of-band lines.
<DT> Messages
<DD> An MCP <EM>message</EM> is a structured entity consisting of a
<EM>message name</EM> identifying the class (kind) of the message
(usually indicating an action to be taken),
an <EM>authentication key</EM>, and
a keyword-to-value mapping that comprises the <EM>arguments</EM>
of the message.
How a given MCP message is formatted as a sequence of out-of-band
lines is described <a href="#msgfmt">below</a>.
The term "message" can refer to the entire class of
messages having a given message name as well as to particular
instances of that class.
<DT> Packages
<DD> MCP <EM>packages</EM> (or <EM>protocols</EM>) are suites of
MCP messages (i.e., message classes) used to implement an application.
Typical packages include the MCP version negotiation and cords
packages, which are described later in this document.
</DL>