Author: dylan
Date: 2004-07-11 04:16:34 -0400 (Sun, 11 Jul 2004)
New Revision: 310
Added:
trunk/docs/manual/
trunk/docs/manual/Makefile
trunk/docs/manual/chap/
trunk/docs/manual/chap/introduction.tex
trunk/docs/manual/chap/protocol.tex
trunk/docs/manual/haver.tex
trunk/docs/manual/macros.tex
Log:
commiting the haver manual... the first
two chapters are mostly complete.
Added: trunk/docs/manual/Makefile
===================================================================
--- trunk/docs/manual/Makefile 2004-07-08 02:11:46 UTC (rev 309)
+++ trunk/docs/manual/Makefile 2004-07-11 08:16:34 UTC (rev 310)
@@ -0,0 +1,34 @@
+
+
+
+export RERUN=Rerun to get cross-references right
+
+base=haver
+
+
+all: dvi
+
+dvi: $(base).dvi
+pdf: $(base).pdf
+
+
+clean:
+ find . \( -name '*.aux' -or -name '*.log' \) -exec rm -v {} \;
+
+realclean:
+ -rm $(base).dvi $(base).pdf
+
+
+$(base).dvi: $(base).tex $(wildcard chap/*.tex)
+ latex $< | tee dvi.log
+ -grep -q "$$RERUN" dvi.log && latex $<
+ rm dvi.log
+
+$(base).pdf: $(base).tex $(wildcard chap/*.tex)
+ pdflatex $< | tee pdf.log
+ -grep -q "$$RERUN" pdf.log && pdflatex $<
+ rm pdf.log
+
+
+
+.PHONY: all clean dvi pdf
Added: trunk/docs/manual/chap/introduction.tex
===================================================================
--- trunk/docs/manual/chap/introduction.tex 2004-07-08 02:11:46 UTC (rev
309)
+++ trunk/docs/manual/chap/introduction.tex 2004-07-11 08:16:34 UTC (rev
310)
@@ -0,0 +1,58 @@
+
+\chapter{Introduction}
+
+Haver\footnote{verb: To maunder; to talk foolishly; to chatter.}
+is a simple line based, tab delimited protocol. It is
+not meant as a replacement to IRC\footnote{add citation},
Jabber/XMPP\footnote{cite},
+or SILC\footnote{cite}.
+
+Nevertheless, it should be rather less difficult to write clients for
+than the above mentioned protocols. SILC is likely to be far more secure,
+however.
+
+\section{Servers}
+
+Each server must have a name.
+
+\section{Clients}
+
+Clients are any programs that connect to the server.
+There are several different types of clients, and each may have access to
special features
+of the server.
+
+Each client of a given type (which is its namespace) must have a unique id.
That is to say,
+each type and id combination must be unique.
+
+The form of namespaces is defined in \ref{sec:format.ns},
+and the form of identifiers in \ref{sec:format.id}.
+
+\subsection{Users}
+
+The vast majority of clients will be representations of users.
+Users are the chatters of the network.
+They may be real people, bots, or GreenReaper.
+
+Users may or may not require authorization, depending
+on if the user is registered or not.
+
+% cross-ref: Authoriztion.
+
+\subsection{Services}
+
+Services add new protocol commands to the server,
+and will typically require some form of authorization.
+
+\subsubsection{Agents}
+
+Services may produce virtual user-like entities to interact with
+users. These are called agents, and are rather like privledged bots.
+
+% cross-ref: Authoriztion.
+
+
+\section{Channels}
+
+Channels are collections of users, much like in IRC,
+except they must be created by a server admin or by
+Channel ids (cids) follow the same rules as identifiers for client objects
+as defined in section~\ref{sec:format.id}.
Added: trunk/docs/manual/chap/protocol.tex
===================================================================
--- trunk/docs/manual/chap/protocol.tex 2004-07-08 02:11:46 UTC (rev 309)
+++ trunk/docs/manual/chap/protocol.tex 2004-07-11 08:16:34 UTC (rev 310)
@@ -0,0 +1,154 @@
+
+\chapter{Protocol}
+
+
+Write something....
+
+\section{Parsing}
+
+The protocol is in the UTF-8 encoding, but only the first
+127 character codes (ASCII) are used for commands,
+identifiers, and delimiters.
+
+The characters CR, LF, Tab, and Esc (see Table~\ref{tab:chars})
+have special meaning. CR (Carriage Return) followed by LF (Line Feed)
+terminates a line. Each line is sub-devided into tokens separated by Tabs.
+Esc is used for encoding literal CR, LF, Tab, and Esc characters.
+See Section~\ref{tab:esc} for details on escaping.
+
+\begin{table}
+\caption{Special Characters}
+\label{tab:chars}
+\begin{tabular}{|l|l|} \hline
+ Name & ASCII Hex Code \\ \hline
+ CR & 0x0D \\ \hline
+ LF & 0x0A \\ \hline
+ Tab & 0x09 \\ \hline
+ Esc & 0x1b \\ \hline
+\end{tabular}
+\end{table}
+
+\subsection{Lines}
+
+Lines are terminated by the sequence CR LF,
+which is a carriage return followed by a line feed.
+A carriage return not followed by a line feed is illegal,
+as is a line feed not preceded with a carriage return.
+The previous sentence may be ignored for simplicity.
+
+Most programming languages have a fairly easy
+way of reading lines from sockets. In perl,
+the \function{readline} function should do.
+
+ \subsection{Lists}
+
+ Each line is a list of strings separated by a Tab character.
+ The first item in the list is generally called the command,
+ and the remaining items (if any) are called the arguments.
+
+ In perl, you will use {\tt \verb"($cmd, @args) = split(/\t/, $line)"}
+ to parse this. The C library glib (used by gtk) has a
+ \function{g\_strsplit} function, as well.
+
+ \subsection{Escaping and Unescaping}
+
+ Escape sequences are used to encode ``CR'', ``LF'', ``Tab'', and
``Esc'' (as defined
+ in table~\ref{tab:chars}) as ``Esc r'', ``Esc n'', ``Esc t'', and ``Esc
e''
+ respectively.
+ Table~\ref{tab:esc} should provide some enlightenment to this rather
+ confusing definition. Thus, CR escaped is ``Esc r'', ``Esc t''
unescaped is
+ Tab, and so on and so forth.
+
+ \begin{table}
+ \caption{Escape Sequences}
+ \label{tab:esc}
+ \begin{tabular}{|l|l|l|} \hline
+ Character & Escaped as & Byte Sequence \\
+ \hline
+ CR & Esc r & 1B 72 \\
+ \hline
+ LF & Esc n & 1B 6E \\
+ \hline
+ Tab & Esc t & 1B 74 \\
+ \hline
+ Esc & Esc e & 1B 65 \\
+ \hline
+ \end{tabular}
+ \end{table}
+
+ \subsection{Psuedo-code Examples}
+
+ TODO. WRITE ME.
+
+\section{Formats}
+
+This section describes formats used in the haver protocol,
+such as how dates, times, and time zones are formatted.
+It also describes the format for identifiers (the ids of channels, users, etc).
+
+\subsection{Timestamps}
+
+Timestamps are in the form of ``DATE TIME TIMEZONE'',
+and the format for each of those is given below.
+
+An example timestamp would be 1944-06-06 12:30:41 +0100,
+which is June 6th, 1944 at half past noon (and 41 seconds...) in the UTC + 1
+time zone.
+
+\subsubsection{Dates}
+Dates are expressed as YYYY-MM-DD, which MM and DD are zero-padded if
necessary.
+For example would be 1985-09-14.
+
+\paragraph{Perl Regex} \verb!/\d{4}-\d{2}-\d{2}/!
+
+\subsubsection{Times}
+Time is expressed as HH:MM:SS, where the hour ranges from 00 to 23,
+the minute and second range from 00 to 59.
+A period (``.'') me be appended to SS to express any fractional part of a
second.
+
+\paragraph{Perl Regex} \verb!/\d{2}:\d{2}:\d{2}(\.\d+)?/!
+
+\subsubsection{Time Zones}
+
+All times are assumed to be in UTC unless a different time zone is specified.
+The format for time zones is ZHHMM, where Z is either a plus or a minus sign,
+HH the hour offset and MM is the minute offset. For example, Eastern Daylight
Time is
+-0400.
+
+\paragraph{Perl Regex} \verb!/[-+]\d{2}\d{2}/!
+
+\subsection{Identifiers and Namespaces}
+
+This section describes the various naming convention for
+objects such as channels, users, and services within a haver server.
+
+\subsubsection{Identifiers}
+\label{sec:format.id}
+
+Identifiers may begin with an optional ampersand or dollar sign,
+and must then be followed (or start with in the first place) a lower-case
letter,
+and then must be followed by at least one lower case letter, number,
+underscore, single quote, hyphen or at symbol.
+
+All identifiers that begin with either an ampersand or dollar sign,
+or that contain the at symbol, are reserved for the server and for services
+with appropriate authority.
+
+
+\paragraph{Perl Regex} \verb!/[&$]?[a-z][a-z0-9_'@-]+/!.
+
+A user client will not be allowed to login with user ids that fail to match
\verb!/[a-z][a-z0-9_'-]+/!,
+nor create channel ids fail to match the same.
+
+\subsubsection{Namespaces}
+\label{sec:format.ns}
+
+Namespaces are used to separate the identifiers for different types of things,
+so that, for example, there may be a channel named joe and a user named joe.
+Namespaces are composed of only lower case letters.
+
+
+\paragraph{Perl Regex} \verb!/[a-z]+/!
+
+It can't be very much simpler, no?
+
Added: trunk/docs/manual/haver.tex
===================================================================
--- trunk/docs/manual/haver.tex 2004-07-08 02:11:46 UTC (rev 309)
+++ trunk/docs/manual/haver.tex 2004-07-11 08:16:34 UTC (rev 310)
@@ -0,0 +1,31 @@
+% Date: Wednesday, May 26 at 7:45PM
+\documentclass[12pt]{report}
+\input{macros}
+\title{The Divine Secrets of Haver}
+\author{Dylan William Hardison}
+
+\date{\today}
+
+\begin{document}
+\maketitle
+
+\begin{abstract}
+The haver protocol is being developed by an international coalition
+of four people bent on world domination.
+It does not feature advanced technology such as XML, XSL, SOAP, or any number
+of other acronyms.
+
+However, it does feature both socket-level
+encryption with SSL and user-to-user encryption with OpenPGP, and thus
+the American developers will likely be investigated
+by the Department of Homeland Security sometime in the near future.
+
+The Haver protocol is text-based, with the simplest client being any program
capable
+of using SSL sockets.
+\end{abstract}
+
+\include{chap/introduction}
+\include{chap/protocol}
+
+
+\end{document}
Added: trunk/docs/manual/macros.tex
===================================================================
--- trunk/docs/manual/macros.tex 2004-07-08 02:11:46 UTC (rev 309)
+++ trunk/docs/manual/macros.tex 2004-07-11 08:16:34 UTC (rev 310)
@@ -0,0 +1,4 @@
+
+\newcommand{\function}[1]{#1()}
+\newcommand{\comment}[1]{(\emph{#1})}
+
