Author: dylan
Date: 2004-08-02 01:13:12 -0400 (Mon, 02 Aug 2004)
New Revision: 333
Added:
branches/protocol-v4/docs/manual/chap/formats.tex
Modified:
branches/protocol-v4/docs/manual/
branches/protocol-v4/docs/manual/chap/
branches/protocol-v4/docs/manual/chap/commands.tex
branches/protocol-v4/docs/manual/chap/introduction.tex
branches/protocol-v4/docs/manual/chap/protocol.tex
branches/protocol-v4/docs/manual/haver.tex
Log:
split protocol and formats into separate chapters,
ignored latex-generated files.
Property changes on: branches/protocol-v4/docs/manual
___________________________________________________________________
Name: svn:ignore
+ *.aux
*.pdf
*.ps
*.dvi
*.log
*.toc
*.bbl
*.blg
Property changes on: branches/protocol-v4/docs/manual/chap
___________________________________________________________________
Name: svn:ignore
+ *.aux
Modified: branches/protocol-v4/docs/manual/chap/commands.tex
===================================================================
--- branches/protocol-v4/docs/manual/chap/commands.tex 2004-08-02 03:19:17 UTC
(rev 332)
+++ branches/protocol-v4/docs/manual/chap/commands.tex 2004-08-02 05:13:12 UTC
(rev 333)
@@ -58,6 +58,7 @@
\section{Client Commands}
+\label{commands.client}
This section describes the commands that clients may send to the server.
@@ -69,7 +70,8 @@
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}.
+See Section~\ref{commands.server} for details on \cmd{FAIL}.
+Section~\ref{commands.errors} describes errors in more detail.
\begin{commands}
\begin{cmddef}{HAVER}{\param{client}}
@@ -226,4 +228,8 @@
\label{commands.server}
To be written...
+\section{Errors}
+\label{commands.errors}
+To be written...
+
Added: branches/protocol-v4/docs/manual/chap/formats.tex
===================================================================
--- branches/protocol-v4/docs/manual/chap/formats.tex 2004-08-02 03:19:17 UTC
(rev 332)
+++ branches/protocol-v4/docs/manual/chap/formats.tex 2004-08-02 05:13:12 UTC
(rev 333)
@@ -0,0 +1,98 @@
+\chapter{Formats}
+\label{format}
+
+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).
+
+\section{Dates and Times}
+
+Time stamps are written as either ``Date Time'' or ``Date Time Timezone'',
+where the format of Date, Time, and Timezone is as defined in
Table~\ref{tab:format.time}.
+
+Further explaination is given in the following subsections.
+
+\begin{table}
+\caption{Timestamp formats}
+\label{tab:format.time}
+\begin{tabular}{|l|l|l|} \hline
+Name & Perl Regex & Example \\
+\hline
+Date & \verb!/\d{4}-\d{2}-\d{2}/! & 1985-09-14 \\
+\hline
+Time & \verb!/\d{2}:\d{2}:\d{2}(\.\d+)?/! & 01:18:14 \\
+\hline
+Timezone & \verb!/[+-]\d{2}\d{2}/! & -0400 \\
+\hline
+\end{tabular}
+\end{table}
+
+An example time stamp 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.
+
+\subsection{Dates}
+Dates are expressed as YYYY-MM-DD, which MM and DD are zero-padded if
necessary.
+For example would be 1985-09-14.
+
+
+\subsection{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 (``.'') followed by up to six digits may be appended to SS to
+express any fractional part of a second.
+
+\subsection{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.
+
+\section{Identifiers, Namespaces and Commands}
+\label{format.id}
+
+This section describes the various naming convention for
+objects such as channels, users, and services within a haver server.
+
+The form of identifiers, namespaces and commands is defined
+in Table~\ref{tab:id}, and explained in greater detail in the following
subsections.
+
+\begin{table}
+\caption{IDs, Namespaces and Commands}
+\label{tab:id}
+\begin{tabular}{|l|l|} \hline
+Name & Perl Regex \\
+\hline
+IDs & \verb!/&?[A-Za-z][A-Za-z0-9_.'@-]+/! \\
+\hline
+Namespace & \verb!/[a-z]+/! \\
+\hline
+Command & \verb!/[A-Z][A-Z:_-]+/! \\
+\hline
+\end{tabular}
+\end{table}
+
+
+
+\subsection{Identifiers}
+
+Each channel, user, and service is identified with a unique string
+characters, and this is called the identifier, or ID.
+Identifiers (henceforth refered to as IDs) may be prefixed with an ampersand,
+must begin with a letter, and must be followed by one or more of: letters;
+numbers; periods; hyphens; underscores; single quotes; or the ``at'' symbol.
+All other characters constitute an illegal ID.
+
+
+\subsection{Namespaces}
+
+Name spaces must contain one or more lower-case letters,
+and may contain no other character.
+
+\subsection{Commands}
+
+The commands to and from the server must begin with an upper case
+letter and may be followed by one or more of upper case letters, the
underscore, hyphens, or the colon.
+Commands containing any other characters will be considered illegal.
+
Modified: branches/protocol-v4/docs/manual/chap/introduction.tex
===================================================================
--- branches/protocol-v4/docs/manual/chap/introduction.tex 2004-08-02
03:19:17 UTC (rev 332)
+++ branches/protocol-v4/docs/manual/chap/introduction.tex 2004-08-02
05:13:12 UTC (rev 333)
@@ -1,35 +1,40 @@
\chapter{Introduction}
Haver is a simple line based, tab delimited protocol. It is
-not meant as a replacement to IRC\cite{rfc:1459}, \cite{jabber},
-or SILC\cite{silc}.
+not meant as a replacement to IRC\cite{rfc:1459}, Jabber\cite{jabber},
+or SILC\cite{silc}. Nevertheless, it should be rather
+less difficult to write clients for haver than the above mentioned protocols.
-Nevertheless, it should be rather less difficult to write clients for
-than the above mentioned protocols.
+This protocol is being designed because current protocols are either
+too limited (e.g. IRC) or too complicated (e.g. jabber, SILC) to extend
+in playful and useless ways. Something simple and powerful needs to exist,
+and this could very well be haver.
\section{Servers}
-The server routes messages to and from clients,
-keeps track of permisions for each client,
-and a associates various key-value pairs with each client
-and channel.
+A Haver server is almost, but not quite, entirely unlike chocolate.
+While chocolate's main purpose is to delight with its delicious
+taste, haver servers do not have any taste.
+Instead, haver servers route messages (commands) to their clients,
+and maintain data about their clients and channels.
+Monolithic servers will do more than just this, and will handle many commands
+internally. Micro-servers will offload this burden unto special service
clients.
+
\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.
+A Haver client sends and relieves commands from the server, basically.
-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.
+Each client has an identifier (id) and a type (namespace).
+Details on ids and namespaces can be found in Section~\ref{format.id}.
-The format of identifiers and namespaces is defined in
Section~\ref{protocol.format.id}.
+The functionality available to a client, what it is allowed to do,
+is strongly influenced by the type of client it is.
\subsection{Users}
-The vast majority of clients will be representations of users.
-Users are the chatters of the network.
-They may be real people or bots.
+The vast majority of clients will be users, which are representations
+of either real people, bots, or even Helephants.
Users may or may not require authorization, depending
on if the user is registered or not.
@@ -38,19 +43,22 @@
\subsection{Services}
-Services add new protocol commands to the server,
+Services may add new protocol commands to the server,
and will typically require some form of authorization.
Services may produce virtual user-like entities to interact with
the real users. These are called agents, and are rather like privileged bots.
+In addition, services may be allowed to extend ``virtual'' channels into
+the server to allow different forms of server linking.
+
% 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 some other controlled
means.
-Channel IDs (cids) follow the same rules as identifiers for client objects
-as defined in section~\ref{protocol.format.id}.
+Channels are pretty much like they are on IRC, except their identifiers
(channel ids, cids)
+follow the same rules as identifiers for the other types of objects (users,
services, etc).
+They may either automagically created upon use, or channel creation can be
restricted to privileged users.
+
Modified: branches/protocol-v4/docs/manual/chap/protocol.tex
===================================================================
--- branches/protocol-v4/docs/manual/chap/protocol.tex 2004-08-02 03:19:17 UTC
(rev 332)
+++ branches/protocol-v4/docs/manual/chap/protocol.tex 2004-08-02 05:13:12 UTC
(rev 333)
@@ -1,11 +1,6 @@
\chapter{Protocol}
+\label{protocol}
-The haver protocol is line based, plain text protocol
-for real time Internet conferencing.
-Parsing it is not unlike parsing tab separated field files.
-
-\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.
@@ -14,7 +9,7 @@
have special meaning. CR (Carriage Return) followed by LF (Line Feed)
terminates a line. Each line is subdivided into tokens separated by Tabs.
Esc is used for encoding literal CR, LF, Tab, and Esc characters.
-See Section~\ref{protocol.parse.esc} for details on escaping.
+See Section~\ref{protocol.esc} for details on escaping.
\begin{table}
\caption{Special Characters}
@@ -28,7 +23,7 @@
\end{tabular}
\end{table}
- \subsection{Lines}
+ \section{Parsing Lines}
Lines are terminated by the sequence CR LF,
which is a carriage return followed by a line feed.
@@ -40,7 +35,7 @@
way of reading lines from sockets. In perl,
the \function{readline} function should do.
- \subsection{Lists}
+ \section{Parsing Lists}
Each line is a list of strings separated by a Tab character.
The first item in the list is generally called the command,
@@ -50,8 +45,8 @@
to parse this. The C library glib (used by gtk) has a
\function{g\_strsplit} function, as well.
- \subsection{Escaping and Unescaping}
- \label{protocol.parse.esc}
+ \section{Escaping and Unescaping}
+ \label{protocol.esc}
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''
@@ -77,105 +72,8 @@
\end{tabular}
\end{table}
- \subsection{Psuedo-code Examples}
+ \section{Psuedo-code Examples}
TODO. WRITE ME.
-\section{Formats}
-\label{protocol.format}
-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{Dates and Times}
-
-Time stamps are written as either ``Date Time'' or ``Date Time Timezone'',
-where the format of Date, Time, and Timezone is as defined in
Table~\ref{tab:format.time}.
-
-Further explaination is given in the following subsections.
-
-\begin{table}
-\caption{Timestamp formats}
-\label{tab:format.time}
-\begin{tabular}{|l|l|l|} \hline
-Name & Perl Regex & Example \\
-\hline
-Date & \verb!/\d{4}-\d{2}-\d{2}/! & 1985-09-14 \\
-\hline
-Time & \verb!/\d{2}:\d{2}:\d{2}(\.\d+)?/! & 01:18:14 \\
-\hline
-Timezone & \verb!/[+-]\d{2}\d{2}/! & -0400 \\
-\hline
-\end{tabular}
-\end{table}
-
-An example time stamp 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.
-
-
-\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 (``.'') followed by up to six digits may be appended to SS to
-express any fractional part of a second.
-
-\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.
-
-\subsection{Identifiers, Namespaces and Commands}
-\label{protocol.format.id}
-
-This section describes the various naming convention for
-objects such as channels, users, and services within a haver server.
-
-The form of identifiers, namespaces and commands is defined
-in Table~\ref{tab:id}, and explained in greater detail in the following
subsections.
-
-\begin{table}
-\caption{IDs, Namespaces and Commands}
-\label{tab:id}
-\begin{tabular}{|l|l|} \hline
-Name & Perl Regex \\
-\hline
-IDs & \verb!/&?[A-Za-z][A-Za-z0-9_.'@-]+/! \\
-\hline
-Namespace & \verb!/[a-z]+/! \\
-\hline
-Command & \verb!/[A-Z][A-Z:_-]+/! \\
-\hline
-\end{tabular}
-\end{table}
-
-
-
-\subsubsection{Identifiers}
-
-Each channel, user, and service is identified with a unique string
-characters, and this is called the identifier, or ID.
-Identifiers (henceforth refered to as IDs) may be prefixed with an ampersand,
-must begin with a letter, and must be followed by one or more of: letters;
-numbers; periods; hyphens; underscores; single quotes; or the ``at'' symbol.
-All other characters constitute an illegal ID.
-
-
-\subsubsection{Namespaces}
-
-Name spaces must contain one or more lower-case letters,
-and may contain no other character.
-
-\subsubsection{Commands}
-
-The commands to and from the server must begin with an upper case
-letter and may be followed by one or more of upper case letters, the
underscore, hyphens, or the colon.
-Commands containing any other characters will be considered illegal.
-
Modified: branches/protocol-v4/docs/manual/haver.tex
===================================================================
--- branches/protocol-v4/docs/manual/haver.tex 2004-08-02 03:19:17 UTC (rev
332)
+++ branches/protocol-v4/docs/manual/haver.tex 2004-08-02 05:13:12 UTC (rev
333)
@@ -36,6 +36,7 @@
\include{chap/introduction}
\include{chap/protocol}
+\include{chap/formats}
\include{chap/commands}
\bibliographystyle{plain}
