Author: dylan
Date: 2004-08-08 02:10:05 -0400 (Sun, 08 Aug 2004)
New Revision: 339
Modified:
branches/protocol-v4/docs/manual/Makefile
branches/protocol-v4/docs/manual/chap/commands.tex
branches/protocol-v4/docs/manual/style.tex
Log:
All currently implemented client commands,
except INFO and LINFO, are implemented.
The syntax of LINFO is changing slightly,
and I'm re-working the error names somehow.
"notfound.cid" seems stupid on JOIN, for example.
Just "notfound" will do.
Modified: branches/protocol-v4/docs/manual/Makefile
===================================================================
--- branches/protocol-v4/docs/manual/Makefile 2004-08-07 23:28:16 UTC (rev
338)
+++ branches/protocol-v4/docs/manual/Makefile 2004-08-08 06:10:05 UTC (rev
339)
@@ -15,6 +15,10 @@
ARGS += -f DRAFT
endif
+ifdef COLOR
+ARGS += -f COLOR
+endif
+
all:
@echo "Probably you want to run make pdf or make dvi or make html"
@@ -35,11 +39,11 @@
$(base).dvi: $(base).tex $(tex)
- ./buildlatex -f PDF $(ARGS) $<
+ ./buildlatex -f DVI $(ARGS) $<
$(base).pdf: $(base).tex $(tex)
- ./buildlatex -f DVI $(ARGS) -l pdflatex $<
+ ./buildlatex -f PDF $(ARGS) -l pdflatex $<
#$(base)/$(base).html: $(base).tex $(tex)
# latex2html -local_icons -split 3 $<
Modified: branches/protocol-v4/docs/manual/chap/commands.tex
===================================================================
--- branches/protocol-v4/docs/manual/chap/commands.tex 2004-08-07 23:28:16 UTC
(rev 338)
+++ branches/protocol-v4/docs/manual/chap/commands.tex 2004-08-08 06:10:05 UTC
(rev 339)
@@ -6,16 +6,21 @@
\newcommand{\params}[1]{\param{#1\ldots}}
\newcommand{\opts}[1]{[\param{#1\ldots}]}
\newcommand{\cmd}[1]{{\bfseries #1}}
+\newcommand{\scmd}[1]{\cmd{#1}}
+\newcommand{\eitem}[3]{\item[#1] \param{#2} \par }
+\newcommand{\citem}[1]{\item[#1] ~ \par}
+
+
\ifhas{COLOR}{
\renewcommand{\param}[1]{\textcolor{param}{\emph{#1}}}
- \renewcommand{\cmd}[1]{\textcolor{cmd}{\emph{#1}}}
+ \renewcommand{\cmd}[1]{\textcolor{cmd}{{\bfseries #1}}}
+ \renewcommand{\scmd}[1]{\textcolor{scmd}{{\bfseries #1}}}
+ \renewcommand{\eitem}[3]{\item[\textcolor{err}{#1}] \param{#2} \par }
}
-\newcommand{\eitem}[3]{\item[#1] \param{#2} \par }
-\newcommand{\citem}[1]{\item[#1] ~ \par}
\newcommand{\Res}{Results}
\newcommand{\Desc}{Description}
@@ -25,6 +30,7 @@
\item[\cmd{#1}] #2
\begin{description}%
+ \nopagebreak[1]
}{%
\end{description}%
}
@@ -70,36 +76,40 @@
the ``\Res'' entry. Keep in mind this may not exhaustive.
In addition to the listed results, nearly every client command may result in
-the server sending the \cmd{FAIL} command. An ``\Err'' listing
+the server sending the \scmd{FAIL} command. An ``\Err'' listing
shows the possible (not exhaustive) error types that may result.
-See Section~\ref{commands.server} for details on \cmd{FAIL}.
+See Section~\ref{commands.server} for details on \scmd{FAIL}.
Section~\ref{commands.errors} describes errors in more detail.
\begin{commands}
\begin{cmddef}{HAVER}{\param{client}}
\citem{\Desc}
+ This command may only be sent once during
+ the liftetime the connection.
+
A client will send this command when it
first connects to the server. The argument
\param{client}
should be the name and version num\-ber of the user
agent.
\citem{\Res}
- The server will send \cmd{HAVER} and \cmd{WANT IDENT}.
+ The server will send \scmd{HAVER} and \scmd{WANT}.
\citem{\Err} None.
\end{cmddef}
\begin{cmddef}{IDENT}{\param{id} \opt{mode}}
\citem{\Desc}
- This should only be sent as the reply a \cmd{WANT
IDENT}.
+ A client may only send this when it the server
+ requests it with \scmd{WANT}.
+
Login as \param{id} in mode \param{mode},
where \param{mode} is optional and defaults to ``user''.
\citem{\Res}
- \cmd{ACCEPT} will be sent if \param{id} requires
+ \scmd{ACCEPT} will be sent if \param{id} requires
no authorization. If authorization is required,
- \cmd{WANT AUTH} will be sent.
+ the server will request (\scmd{WANT}) \cmd{AUTH}.
-
\citem{\Err}
\begin{errors}
\eitem{mode}{mode}
@@ -118,97 +128,144 @@
\begin{cmddef}{AUTH}{\param{method}}
\citem{\Desc}
- A client will only send this when it the server
- requests it with \cmd{WANT AUTH}.
+ A client may only send this when it the server
+ requests it with \scmd{WANT}.
+
Ask the server to use the ``\param{method}''
method of authorization.
\citem{\Res}
- The server will send \cmd{AUTH:\param{method}}
+ The server will \scmd{WANT} \cmd{AUTH:\param{method}}
where \param{method} is replaced by the actual method
requested.
\citem{\Err}
\begin{errors}
- \eitem{method}{method}
+ \eitem{badmethod}{method}
The method \param{method} is unknown.
\end{errors}
\end{cmddef}
\begin{cmddef}{AUTH:PASS}{\param{password}}
\citem{\Desc}
- A client will only send this when it the server
- requests it with \cmd{WANT AUTH:PASS}.
+ A client may only send this when it the server
+ requests it with \scmd{WANT}.
+
This is the authorization command for password-based
authentication.
The password, \param{password} will be the SHA-1 sum of
the user's password, their id, and the hostname of the
server.
\citem{\Res}
- The server will send \cmd{ACCEPT}.
+ \scmd{ACCEPT}.
\citem{\Err}
\begin{errors}
\eitem{nomatch}{} the password did not match.
\end{errors}
\end{cmddef}
+
+ \newpage
+ \begin{cmddef}{MSG}{\param{where} \param{type} \params{msg}}
+ \citem{\Desc}
+ This command may only be used by user clients.
+
+ Send a public message \params{msg}\ of type \param{type}
+ to the channel \param{where}.
+
+ \citem{\Res}
+ \scmd{MSG} will be sent to every user in \param{cid}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where} The channel id \param{where}
contains illegal
+ characters or is the wrong length.
+ \eitem{notfound.cid}{where} The channel \param{where}
does not exist.
+ \end{errors}
+ \end{cmddef}
+ \begin{cmddef}{PMSG}{\param{to} \param{type} \params{msg}}
+ \citem{\Desc}
+ This command may only be used by user clients.
+ Send a private message \params{msg}\ of type
\param{type}
+ to the user \param{to}.
+
+ \citem{\Res}
+ The user \param{to} will recieve \scmd{PMSG},
+ the sender recieves nothing (Unless there is an error).
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.uid}{to} The user id \param{to} contains
illegal
+ characters or is the wrong length.
+ \eitem{notfound.uid}{to} The user \param{to} does not
exist.
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{JOIN}{\param{where}}
+ \citem{\Desc}
+ This command may only be used by user clients.
+
+ Attempt to join \param{where}.
+
+ \citem{\Res}
+ Upon successful entry, the server will send
+ \scmd{JOIN} to each user in the channel, including the
joiner.
+
+ \comment{There should be some support for passworded
channels,
+ and channels that maintain a wait-list.}
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where} The channel id \param{where}
contains illegal
+ characters or is the wrong length.
+ \eitem{notfound.cid}{where} The channel \param{where}
does not exist.
+ \eitem{joined}{where} already joined to the channel.
Can't join twice!
+ \end{errors}
+ \comment{Further errors will be added for when people
are banned, etc.}
+ \end{cmddef}
+
+ \begin{cmddef}{PART}{\param{where}}
+ \citem{\Desc}
+ This command may only be used by user clients.
+
+ Attempt to leave \param{where}.
+
+ \citem{\Res}
+ The server will send \scmd{PART}
+ to every user in the channel \emph{before} the user
+ actually leaves the channel. Thus the parter will get
his
+ own part message.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where} The channel id \param{where}
contains illegal
+ characters or is the wrong length.
+ \eitem{notfound.cid}{where} The channel \param{where}
does not exist.
+ \eitem{timetravel}{where} Many things are possible, but
leaving a place you've
+ never been is not.
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{BYE}{\opt{reason}}
+ \citem{\Desc}
+ Part every channel and disconnect from the server.
+
+ \citem{\Res}
+ The server will send \scmd{BYE}
+ and disconnect shortly after that.
+
+ The server will send \scmd{QUIT} to any other clients
+ that need to be notified of this client's departure.
+
+ \citem{\Err} None.
+ \end{cmddef}
+
+
+
+
\end{commands}
-%> [HAVER]
-%> C: HAVER $client
-%> S: HAVER $server
-%> [IDENT]
-%> C: IDENT $id [$type]
-%> S: ACCEPT $id
-%> | WANT AUTH ...
-%> Errors:
-%> * unknown-type -- %1 is an unknown type of client.
-%> * syntax -- %1 this is an illegal id.
-%> * reserved -- %1 is reserved for something else.
-%> * used -- %1 is already being used.
-%> [CANT]
-%> C: CANT $want
-%> S: ...
-%> [AUTH]
-%> C: AUTH $method ...
-%> S: WANT AUTH:uc($method) ...
-%> Errors:
-%> * unknown -- auth method %1 is unknown
-%> [AUTH:PASS]
-%> C: AUTH:PASS $password
-%> S: ACCEPT $uid
-%> Errors:
-%> * nomatch -- password did not match,
-%> [MSG]
-%> C: MSG $cid $type @args
-%> S: MSG $cid $uid $type @args
-%> Errors:
-%> * syntax.cid -- the cid %1 is invalid.
-%> * notfound.cid -- the cid %1 was not found.
-%> [PMSG]
-%> C: PMSG $uid $type @args
-%> S: PMSG $uid $type @args
-%> Errors:
-%> * syntax.uid -- the uid %1 is invalid.
-%> * notfound.uid -- the uid %1 was not found.
-%> [JOIN]
-%> C: JOIN $cid
-%> S: JOIN $cid $uid
-%> Errors:
-%> * notfound.cid -- the cid %1 was not found.
-%> * syntax.cid -- the cid %1 is invalid.
-%> * joined -- tried to join %1 while already in it.
-%> [PART]
-%> C: PART $cid
-%> S: PART $cid $uid
-%> Errors:
-%> * notfound.cid -- the cid %1 was not found.
-%> * syntax.cid -- the cid %1 is invalid.
-%> * timetravel -- you tried to part %1 before you joined it...
-%> [BYE]
-%> C: BYE [$reason]
-%> S: BYE ACTIVE [$reason]
%> [INFO]
%> C: INFO $id
%> S: INFO $type $id (list of key value pairs)
Modified: branches/protocol-v4/docs/manual/style.tex
===================================================================
--- branches/protocol-v4/docs/manual/style.tex 2004-08-07 23:28:16 UTC (rev
338)
+++ branches/protocol-v4/docs/manual/style.tex 2004-08-08 06:10:05 UTC (rev
339)
@@ -2,7 +2,9 @@
\ifhas{COLOR}{
\definecolor{cmd}{rgb}{0,0,0.5}
+\definecolor{scmd}{rgb}{0.2,0,0.9}
\definecolor{param}{rgb}{0.5,0,0}
+\definecolor{err}{rgb}{1,0,0}
}
\ifhaselse{DRAFT}{
