Author: dylan
Date: 2004-08-09 00:48:32 -0400 (Mon, 09 Aug 2004)
New Revision: 344
Added:
trunk/docs/manual/chap/commands/
trunk/docs/manual/chap/commands/client.tex
Modified:
trunk/docs/manual/Makefile
trunk/docs/manual/chap/commands.tex
trunk/docs/manual/config.m4
trunk/docs/manual/haver.tex
Log:
Split the commands chapter, the client
section is over 200 lines.
Modified: trunk/docs/manual/Makefile
===================================================================
--- trunk/docs/manual/Makefile 2004-08-08 22:49:49 UTC (rev 343)
+++ trunk/docs/manual/Makefile 2004-08-09 04:48:32 UTC (rev 344)
@@ -1,17 +1,21 @@
+# Comment to produce non-DRAFT.
DRAFT=1
+VERSION=0.5
-
clean=-name '*.aux' \
-or -name '*.log' \
-or -name '*.bbl' \
-or -name '*.blg' \
-or -name '*.toc' \
+ -or -name '*.out' \
-or -name 'config.tex'
base=haver
tex=$(wildcard chap/*.tex) $(filter-out haver.tex,$(wildcard *.tex)) haver.bib
config.m4
+ARGS += -D VERSION=$(VERSION)
+
ifdef DRAFT
ARGS += -f DRAFT
endif
@@ -24,10 +28,8 @@
@echo "Probably you want to run make pdf or make dvi or make html"
-dvi: $(base).dvi
-
-pdf: $(base).pdf
-
+dvi: $(base).dvi
+pdf: $(base).pdf
html: $(base)/$(base).html
Added: trunk/docs/manual/chap/commands/client.tex
===================================================================
--- trunk/docs/manual/chap/commands/client.tex 2004-08-08 22:49:49 UTC (rev
343)
+++ trunk/docs/manual/chap/commands/client.tex 2004-08-09 04:48:32 UTC (rev
344)
@@ -0,0 +1,248 @@
+\section{Client Commands}
+\label{commands.client}
+
+This section describes the commands that clients may send to the server.
+
+Each command may result in the server sending one or more commands to the
client,
+though the protocol is asynchronous and this may not be relied on.
+In the listings below the possible results of each command is explained under
+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 \scmd{FAIL} command. An ``\Err'' listing
+shows the possible (not exhaustive) error types that may result.
+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 \scmd{HAVER} and \scmd{WANT}.
+
+ \citem{\Err} None.
+ \end{cmddef}
+
+ \begin{cmddef}{IDENT}{\param{id} \opt{ns}}
+ \citem{\Desc}
+ A client may only send this when it the server
+ requests it with \scmd{WANT}.
+
+ Login as \param{id} in namespace \param{ns},
+ where \param{ns} is optional and defaults to ``user''.
+
+ \citem{\Res}
+ \scmd{ACCEPT} will be sent if \param{id} requires
+ no authorization. If authorization is required,
+ the server will request (\scmd{WANT}) \cmd{AUTH}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{unsupported.ns}{ns}
+ \eitem{reserved}{id}
+ \eitem{used}{id}
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{AUTH}{\param{method}}
+ \citem{\Desc}
+ 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 \scmd{WANT} \cmd{AUTH:\param{method}}
+ where \param{method} is replaced by the actual method
requested.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{badmethod}{method}
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{AUTH:PASS}{\param{password}}
+ \citem{\Desc}
+ 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}
+ \scmd{ACCEPT}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{nomatch}{~}
+ \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}
+ The server will send \scmd{MSG} to every user in
\param{where}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where}
+ \eitem{unknown.cid}{where}
+ \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}
+ \eitem{unknown.uid}{to}
+ \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}
+ \eitem{unknown.cid}{where}
+ \eitem{joined}{where}
+ \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}
+ \eitem{unknown.cid}{where}
+ \eitem{timetravel}{where}
+ \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}
+
+ \begin{cmddef}{INFO}{\param{ns} \param{id}}
+ \citem{\Desc}
+ Get information about the in the namespace \param{ns}
with the id \param{id}.
+ This will only return the most ``relevant'' fields of
the object,
+ not all of them.
+
+ \citem{\Res}
+ The server will send \scmd{INFO}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.id}{ns id}
+ \eitem{syntax.ns}{ns}
+ \eitem{unknown.id}{ns id}
+ \eitem{unknown.ns}{ns}
+
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{LINFO}{\param{where} \param{ns} \param{id}}
+ \citem{\Desc}
+ This is like INFO, except local to a channel
\param{where},
+ the ``L'' standing for local. The only other
+ difference is \param{id} may be ``*'' (the asterisk),
+ in which case it is as if the client sent \cmd{LINFO}
+ requests to every \param{ns} in \param{where}.
+
+ \comment{Perhaps \param{ns} should be allowed to be
``*''
+ as well?}
+ \citem{\Res}
+ The server will send \scmd{LINFO}.
+
+ If \param{id} is ``*'', the server will
+ send \scmd{END} \cmd{LINFO} after all other
\scmd{LINFO}'s
+ have been sent.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where}
+ \eitem{unknown.cid}{where}
+ \eitem{syntax.ns}{ns}
+ \eitem{unknown.ns}{ns}
+ \eitem{syntax.id}{ns id}
+ \eitem{unknown.id}{ns id}
+ \end{errors}
+ \end{cmddef}
+
+ \begin{cmddef}{LIST}{\param{where} \param{ns}}
+ \citem{\Desc}
+ Request a list of all things in \param{where}
+ with the namespace \param{ns}.
+
+ \citem{\Res}
+ The server will send \scmd{LIST}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{syntax.cid}{where}
+ \eitem{syntax.ns}{ns}
+ \eitem{unknown.cid}{where}
+ \eitem{unknown.ns}{ns}
+ \end{errors}
+ \end{cmddef}
+
+
+\end{commands}
+
Modified: trunk/docs/manual/chap/commands.tex
===================================================================
--- trunk/docs/manual/chap/commands.tex 2004-08-08 22:49:49 UTC (rev 343)
+++ trunk/docs/manual/chap/commands.tex 2004-08-09 04:48:32 UTC (rev 344)
@@ -65,255 +65,8 @@
\end{description}
-\section{Client Commands}
-\label{commands.client}
+\input{chap/commands/client}
-This section describes the commands that clients may send to the server.
-
-Each command may result in the server sending one or more commands to the
client,
-though the protocol is asynchronous and this may not be relied on.
-In the listings below the possible results of each command is explained under
-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 \scmd{FAIL} command. An ``\Err'' listing
-shows the possible (not exhaustive) error types that may result.
-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 \scmd{HAVER} and \scmd{WANT}.
-
- \citem{\Err} None.
- \end{cmddef}
-
- \begin{cmddef}{IDENT}{\param{id} \opt{ns}}
- \citem{\Desc}
- A client may only send this when it the server
- requests it with \scmd{WANT}.
-
- Login as \param{id} in namespace \param{ns},
- where \param{ns} is optional and defaults to ``user''.
-
- \citem{\Res}
- \scmd{ACCEPT} will be sent if \param{id} requires
- no authorization. If authorization is required,
- the server will request (\scmd{WANT}) \cmd{AUTH}.
-
- \citem{\Err}
- \begin{errors}
- \eitem{unsupported.ns}{ns}
- \eitem{reserved}{id}
- \eitem{used}{id}
- \end{errors}
- \end{cmddef}
-
- \begin{cmddef}{AUTH}{\param{method}}
- \citem{\Desc}
- 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 \scmd{WANT} \cmd{AUTH:\param{method}}
- where \param{method} is replaced by the actual method
requested.
-
- \citem{\Err}
- \begin{errors}
- \eitem{badmethod}{method}
- \end{errors}
- \end{cmddef}
-
- \begin{cmddef}{AUTH:PASS}{\param{password}}
- \citem{\Desc}
- 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}
- \scmd{ACCEPT}.
-
- \citem{\Err}
- \begin{errors}
- \eitem{nomatch}{~}
- \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}
- The server will send \scmd{MSG} to every user in
\param{where}.
-
- \citem{\Err}
- \begin{errors}
- \eitem{syntax.cid}{where}
- \eitem{unknown.cid}{where}
- \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}
- \eitem{unknown.uid}{to}
- \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}
- \eitem{unknown.cid}{where}
- \eitem{joined}{where}
- \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}
- \eitem{unknown.cid}{where}
- \eitem{timetravel}{where}
- \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}
-
- \begin{cmddef}{INFO}{\param{ns} \param{id}}
- \citem{\Desc}
- Get information about the in the namespace \param{ns}
with the id \param{id}.
- This will only return the most ``relevant'' fields of
the object,
- not all of them.
-
- \citem{\Res}
- The server will send \scmd{INFO}.
-
- \citem{\Err}
- \begin{errors}
- \eitem{syntax.id}{ns id}
- \eitem{syntax.ns}{ns}
- \eitem{unknown.id}{ns id}
- \eitem{unknown.ns}{ns}
-
- \end{errors}
- \end{cmddef}
-
- \begin{cmddef}{LINFO}{\param{where} \param{ns} \param{id}}
- \citem{\Desc}
- This is like INFO, except local to a channel
\param{where},
- the ``L'' standing for local. The only other
- difference is \param{id} may be ``*'' (the asterisk),
- in which case it is as if the client sent \cmd{LINFO}
- requests to every \param{ns} in \param{where}.
-
- \comment{Perhaps \param{ns} should be allowed to be
``*''
- as well?}
- \citem{\Res}
- The server will send \scmd{LINFO}.
-
- \citem{\Err}
- \begin{errors}
- \eitem{syntax.cid}{where}
- \eitem{unknown.cid}{where}
- \eitem{syntax.ns}{ns}
- \eitem{unknown.ns}{ns}
- \eitem{syntax.id}{ns id}
- \eitem{unknown.id}{ns id}
- \end{errors}
- \end{cmddef}
-
-
-
-
-
-
-
-\end{commands}
-
-%> [INFO]
-%> C: INFO $id
-%> S: INFO $type $id (list of key value pairs)
-%> Errors:
-%> * unknown -- the id %1 of type %2 was not found.
-%> * syntax -- the id %1 of type %2 is invalid.
-%> [LINFO]
-%> C: LINFO $cid $uid
-%> S: LINFO $cid $uid (key-value pairs)
-%> Errors:
-%> * unknown.cid -- the cid %1 was not found.
-%> * unknown.uid -- the uid %1 was not found.
-%> * syntax.cid -- the cid %1 is invalid.
-%> * syntax.uid -- the uid %1 is invalid.
-
-
-
\section{Server Commands}
\label{commands.server}
To be written...
Modified: trunk/docs/manual/config.m4
===================================================================
--- trunk/docs/manual/config.m4 2004-08-08 22:49:49 UTC (rev 343)
+++ trunk/docs/manual/config.m4 2004-08-09 04:48:32 UTC (rev 344)
@@ -1,7 +1,13 @@
-define(`have', `dnl
-\newboolean{have$1}
-\setboolean{have$1}{ifdef(`$1', `true', `false')}')dnl
+dnl Edit the makefile if you want to configure this. :)
+ifdef(`have', , dnl
+`define(`have', `\newboolean{have$1}dnl
+\setboolean{have$1}{ifdef(`$1', `true', `false')}')')dnl
+ifdef(`version', , dnl
+`define(`version', ``\newcommand{\version}{$1}'')')
+
+
+version(VERSION)
have(`COLOR')
have(`DRAFT')
have(`PDF')
Modified: trunk/docs/manual/haver.tex
===================================================================
--- trunk/docs/manual/haver.tex 2004-08-08 22:49:49 UTC (rev 343)
+++ trunk/docs/manual/haver.tex 2004-08-09 04:48:32 UTC (rev 344)
@@ -12,7 +12,7 @@
\input{style}
-\title{The Divine Secrets of Haver}
+\title{The Divine Secrets of Haver (v\version)}
\author{Dylan William Hardison}
\date{\today}
