Author: dylan
Date: 2004-08-01 23:19:17 -0400 (Sun, 01 Aug 2004)
New Revision: 332
Added:
branches/protocol-v4/docs/manual/config.tex
branches/protocol-v4/docs/manual/style.tex
Modified:
branches/protocol-v4/docs/manual/Makefile
branches/protocol-v4/docs/manual/chap/commands.tex
branches/protocol-v4/docs/manual/haver.tex
branches/protocol-v4/docs/manual/macros.tex
Log:
Oh, many changes. I don't think I can give a coherent
description though... But this is a report, not a program... :)
style.tex -- contains things that affect the general style of the document
config.tex -- configuration options, for disabling color, urls, etc.
macros.tex -- useful macros
haver.tex -- the main document.
chap/*.tex -- each chapter is in a separate file.
Modified: branches/protocol-v4/docs/manual/Makefile
===================================================================
--- branches/protocol-v4/docs/manual/Makefile 2004-07-31 22:15:07 UTC (rev
331)
+++ branches/protocol-v4/docs/manual/Makefile 2004-08-02 03:19:17 UTC (rev
332)
@@ -9,9 +9,11 @@
base=haver
+tex=$(wildcard chap/*.tex) $(wildcard *.tex)
+all:
+ @echo "Probably you want to run make pdf or make dvi or make html"
-all: dvi
dvi: $(base).dvi
@@ -27,7 +29,7 @@
-rm $(base).dvi
-$(base).dvi: $(base).tex $(wildcard chap/*.tex) $(base).bbl
+$(base).dvi: $(base).tex $(tex) $(base).bbl
latex $< | tee dvi.log
-grep -q "$$RERUN" dvi.log && latex $<
rm dvi.log
@@ -41,13 +43,13 @@
bibtex $(base)
-$(base).pdf: $(base).tex $(wildcard chap/*.tex) $(base).bbl
+$(base).pdf: $(base).tex $(tex) $(base).bbl
pdflatex $< | tee pdf.log
-grep -q "$$RERUN" pdf.log && pdflatex $<
rm pdf.log
-$(base)/$(base).html: $(base).tex $(wildcard chap/*.tex) $(base).bbl
+$(base)/$(base).html: $(base).tex $(tex) $(base).bbl
latex2html -local_icons -split 3 $<
.PHONY: all clean dvi
Modified: branches/protocol-v4/docs/manual/chap/commands.tex
===================================================================
--- branches/protocol-v4/docs/manual/chap/commands.tex 2004-07-31 22:15:07 UTC
(rev 331)
+++ branches/protocol-v4/docs/manual/chap/commands.tex 2004-08-02 03:19:17 UTC
(rev 332)
@@ -1,43 +1,229 @@
\newenvironment{commands}{\begin{description}}{\end{description}}
\newenvironment{errors}{\begin{description}}{\end{description}}
-\newcommand{\cmd}[2]{\item[#1] #2}
-\newcommand{\err}[2]{\item[#1] #2}
-\newcommand{\param}[1]{\emph{#1}}
+
+\newcommand{\param}[1]{\emph{\$#1}}
\newcommand{\opt}[1]{[\param{#1}]}
+\newcommand{\params}[1]{\param{#1\ldots}}
+\newcommand{\opts}[1]{[\param{#1\ldots}]}
+\newcommand{\cmd}[1]{{\bfseries #1}}
+\ifhas{COLOR}{
+ \renewcommand{\param}[1]{\textcolor{param}{\emph{#1}}}
+}
+
+\newcommand{\eitem}[3]{\item[#1] \param{#2} \par }
+\newcommand{\citem}[1]{\item[#1] ~ \par}
+
+\newcommand{\Res}{Results}
+\newcommand{\Desc}{Description}
+\newcommand{\Err}{Errors}
+
+\newenvironment{cmddef}[2]{%
+ \item[\cmd{#1}] #2
+
+ \begin{description}%
+}{%
+ \end{description}%
+}
+
+
+
\chapter{Commands}
+This chapter describes the building blocks that clients and servers
+use to talk to each other. The low-level details of the protocol
+are described in Chapter~\ref{protocol}, herein we discuess the meanings
+of the core haver commands.
+A command consists of a line from the server, broken into a list of tokens
separated by
+tabs. The first item in this list is the name of the command, and the
remaining items
+are the arguments, or parameters.
+
+The following is a summary of the typographical conventions used in this
chapter:
+
+\begin{description}
+ \item[\cmd{COMMAND}]
+ This is used for commands, and their literal arguments.
+ \item[\param{param}]
+ Used to refer to an item in the list of arguments for a command.
+ \item[\params{params}]
+ Used to refer to the remaining items in the argument list.
+ \item[\opt{opt}]
+ Used for optional arguments.
+ \item[\opts{opts}]
+ Used when the remaining arguments are optional.
+\end{description}
+
+
\section{Client Commands}
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 \cmd{FAIL} command. An ``\Err'' listing
+shows the possible (not exhaustive) error types that may result.
+See Chapter~\ref{commands.server} for details on \cmd{FAIL}.
+
\begin{commands}
+ \begin{cmddef}{HAVER}{\param{client}}
+ \citem{\Desc}
+ 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.
-\cmd{HAVER}{\param{client}}
+ \citem{\Res}
+ The server will send \cmd{HAVER} and \cmd{WANT IDENT}.
-A client will send this command when it first connects
-to the server. The argument \param{client} should be the name and version
number
-of the user-agent. For example, haver-gtk sends ``Haver::GTK/0.3''.
+ \citem{\Err} None.
+ \end{cmddef}
-The server will reply with two commands, HAVER, and WANT, in that order.
+ \begin{cmddef}{IDENT}{\param{id} \opt{mode}}
+ \citem{\Desc}
+ This should only be sent as the reply a \cmd{WANT
IDENT}.
+ Login as \param{id} in mode \param{mode},
+ where \param{mode} is optional and defaults to ``user''.
-\cmd{IDENT}{\param{id} \opt{mode}}
+ \citem{\Res}
+ \cmd{ACCEPT} will be sent if \param{id} requires
+ no authorization. If authorization is required,
+ \cmd{WANT AUTH} will be sent.
+
-Login as \param{id} in mode \param{mode}, where \param{mode}
-is optional and defaults to ``user''.
+ \citem{\Err}
+ \begin{errors}
+ \eitem{mode}{mode}
+ Unknown client mode ``\param{mode}''.
+
+ \eitem{syntax}{id}
+ Identifier ``\param{id}'' contains illegal characters.
+
+ \eitem{reserved}{id}
+ Identifier ``\param{id}'' is reserved, you may not use
it.
+
+ \eitem{used}{id}
+ Identifier ``\param{id}'' is being used by another
client.
+ \end{errors}
+ \end{cmddef}
-This is the reply to WANT IDENT.
+ \begin{cmddef}{AUTH}{\param{method}}
+ \citem{\Desc}
+ A client will only send this when it the server
+ requests it with \cmd{WANT AUTH}.
+ Ask the server to use the ``\param{method}''
+ method of authorization.
-\begin{errors}
-\err{}{}
+ \citem{\Res}
+ The server will send \cmd{AUTH:\param{method}}
+ where \param{method} is replaced by the actual method
requested.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{method}{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}.
+ 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}.
+
+ \citem{\Err}
+ \begin{errors}
+ \eitem{nomatch}{} the password did not match.
+ \end{errors}
+ \end{cmddef}
+
-
+
\end{commands}
-\section{Client 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)
+%> Errors:
+%> * notfound -- 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:
+%> * notfound.cid -- the cid %1 was not found.
+%> * notfound.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...
+
+
Added: branches/protocol-v4/docs/manual/config.tex
===================================================================
--- branches/protocol-v4/docs/manual/config.tex 2004-07-31 22:15:07 UTC (rev
331)
+++ branches/protocol-v4/docs/manual/config.tex 2004-08-02 03:19:17 UTC (rev
332)
@@ -0,0 +1,7 @@
+\newboolean{COLOR}
+\newboolean{DRAFT}
+\newboolean{URL}
+
+\setboolean{COLOR}{false}
+\setboolean{DRAFT}{true}
+\setboolean{URL}{true}
Modified: branches/protocol-v4/docs/manual/haver.tex
===================================================================
--- branches/protocol-v4/docs/manual/haver.tex 2004-07-31 22:15:07 UTC (rev
331)
+++ branches/protocol-v4/docs/manual/haver.tex 2004-08-02 03:19:17 UTC (rev
332)
@@ -1,10 +1,17 @@
% Date: Wednesday, May 26 at 7:45PM
-\documentclass[12pt]{report}
-\usepackage{url}
+\documentclass[12pt,draft]{report}
+\usepackage{ifthen}
+
+\input{config}
\input{macros}
+\input{style}
+
+\ifhas{COLOR}{\usepackage{color}}
+\ifhas{URL}{\usepackage{url}}
+
+
\title{The Divine Secrets of Haver}
\author{Dylan William Hardison}
-
\date{\today}
\begin{document}
Modified: branches/protocol-v4/docs/manual/macros.tex
===================================================================
--- branches/protocol-v4/docs/manual/macros.tex 2004-07-31 22:15:07 UTC (rev
331)
+++ branches/protocol-v4/docs/manual/macros.tex 2004-08-02 03:19:17 UTC (rev
332)
@@ -1,4 +1,7 @@
-\newcommand{\function}[1]{#1()}
-\newcommand{\comment}[1]{(\emph{#1})}
-
+\newcommand{\ifhas}[2]{%
+\ifthenelse{\boolean{#1}}{#2}{ }%
+}
+\newcommand{\ifhaselse}[3]{%
+\ifthenelse{\boolean{#1}}{#2}{#3}%
+}
Added: branches/protocol-v4/docs/manual/style.tex
===================================================================
--- branches/protocol-v4/docs/manual/style.tex 2004-07-31 22:15:07 UTC (rev
331)
+++ branches/protocol-v4/docs/manual/style.tex 2004-08-02 03:19:17 UTC (rev
332)
@@ -0,0 +1,16 @@
+
+
+\ifhas{COLOR}{
+\definecolor{scmd}{rgb}{0,0,0.5}
+\definecolor{ccmd}{rgb}{0.5,0,0}
+\definecolor{param}{rgb}{0.1,0.5,0}
+}
+
+\ifhaselse{DRAFT}{
+\newcommand{\comment}[1]{(\emph{#1})}
+}{\newcommand{\comment}[1]{}}
+
+\newcommand{\function}[1]{#1()}
+\newcommand{\variable}[1]{\emph{#1}}
+
+\renewcommand{\bibname}{References}
