Fix comma.

[doldaconnect.git] / doc / protocol / protocol.tex

diff --git a/doc/protocol/protocol.tex b/doc/protocol/protocol.tex
index 8184cfb..e7b4866 100644 (file)
--- a/doc/protocol/protocol.tex
+++ b/doc/protocol/protocol.tex
@@ -2,9 +2,11 @@
 
 \usepackage[T1]{fontenc}
 \usepackage[utf8x]{inputenc}
+\usepackage[ps2pdf]{hyperref}
 \usepackage{reqlist}
+\usepackage{longtable}
 
-\newcommand{\url}[1]{\texttt{<#1>}}
+\newcommand{\urlink}[1]{\texttt{<#1>}}
 \newcommand{\unix}{\textsc{Unix}}
 
 \title{Dolda Connect protocol}
@@ -14,6 +16,8 @@
 
 \maketitle
 
+\tableofcontents
+
 \section{Introduction}
 Dolda Connect consists partly of a daemon (a.k.a. server) that runs in
 the background and carries out all the actual work, and a number of
@@ -24,7 +28,7 @@ intends to document that protocol, so that third parties can write
 their own client programs.
 
 It is worthy of note that there exists a library, called
-\texttt{libdcui} that carries out much of the low level work of
+\texttt{libdcui}, that carries out much of the low level work of
 speaking the protocol, facilitating the creation of new client
 programs. In itself, \texttt{libdcui} is written in the C programming
 language and is intended to be used by other programs written in C,
@@ -33,7 +37,7 @@ project's Scheme interpreter) and for Python. The former is
 distributed with the main Dolda Connect source tree, while the latter
 is distributed separately (for technical reasons). To get a copy,
 please refer to Dolda Connect's homepage at
-\url{http://www.dolda2000.com}.
+\urlink{http://www.dolda2000.com}.
 
 \section{Transport format}
 Note: Everything covered in this section is handled by the
@@ -118,7 +122,7 @@ when talking directly to the daemon with a program such as
 Formally, the syntax of the protocol may be defined with the following
 BNF rules. Note that they all operate on Unicode characters, not bytes.
 
-\begin{tabular}{lcl}
+\begin{longtable}{lcl}
 <session> & ::= & <SYN> <response> \\
  & & | <session> <transaction> \\
  & & | <session> <notification> \\
@@ -152,7 +156,7 @@ BNF rules. Note that they all operate on Unicode characters, not bytes.
 & & | ``\texttt{5}'' | ``\texttt{6}'' |
 ``\texttt{7}'' | ``\texttt{8}'' |
 ``\texttt{9}''
-\end{tabular}
+\end{longtable}
 
 As for the terminal symbols, <SPACE> is U+0020, <TAB> is U+0009,
 <CRLF> is the sequence of U+000D and U+000A, <DASH> is U+002D, <CHAR>
@@ -226,7 +230,7 @@ table \ref{tab:perm}.
 \end{table}
 
 \subsection{Protocol revisions}
-
+\label{rev}
 Since Dolda Connect is developing, its command set may change
 occasionally. Sometimes new commands are added, sometimes commands
 change argument syntax, and sometimes commands are removed. In order
@@ -248,11 +252,16 @@ entirely to the new revision. Therefore, a client can check for a
 certain revision and be sure that everything it wants is supported by
 the daemon.
 
+At the time of this writing, the latest protocol revision is 2. Please
+see the file \texttt{doc/protorev} that comes with the Dolda Connect
+source tree for a full list of revisions and what changed between
+them.
+
 \subsection{List of commands}
 
 Follows does a (hopefully) exhaustive listing of all commands valid
 for a request. For each possible request, it includes the name of the
-command for the request, the permissions required, the syntax the
+command for the request, the permissions required, the syntax for the
 entire request line, and the possible responses.
 
 The syntax of the request and response lines is described in a format
@@ -281,6 +290,8 @@ considered a request, soliciting a response. Such a request obviously
 has no command name and no syntax, but needs a description
 nonetheless.
 
+\revision{1}
+
 \noperm
 
 \begin{responses}
@@ -288,6 +299,17 @@ nonetheless.
   The old response given by daemons not yet using the revisioned
   protocol. Clients receiving this response should consider it an
   error.
+  \response{201 LOREV HIREV}
+  Indicates that the connection is accepted. The \param{LOREV} and
+  \param{HIREV} parameters specify the range of supported protocol
+  revisions, as described in section \ref{rev}.
+  \response{502 REASON}
+  The connection is refused by the daemon and will be closed. The
+  \param{REASON} parameter states the reason for the refusal in
+  English\footnote{So it is probably not suitable for localized
+    programs}.
 \end{responses}
 
+\input{commands}
+
 \end{document}