Use longtable for protocol BNF.

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

diff --git a/doc/protocol/protocol.tex b/doc/protocol/protocol.tex
index 8184cfb..3d3f9be 100644 (file)
--- a/doc/protocol/protocol.tex
+++ b/doc/protocol/protocol.tex
@@ -2,9 +2,11 @@
 
 \usepackage[T1]{fontenc}
 \usepackage[utf8x]{inputenc}
 
 \usepackage[T1]{fontenc}
 \usepackage[utf8x]{inputenc}

+\usepackage[ps2pdf]{hyperref}

 \usepackage{reqlist}
 \usepackage{reqlist}

+\usepackage{longtable}

 
 

-\newcommand{\url}[1]{\texttt{<#1>}}
+\newcommand{\urlink}[1]{\texttt{<#1>}}

 \newcommand{\unix}{\textsc{Unix}}
 
 \title{Dolda Connect protocol}
 \newcommand{\unix}{\textsc{Unix}}
 
 \title{Dolda Connect protocol}


@@ -14,6 +16,8 @@
 
 \maketitle
 
 
 \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
 \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


@@ -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
 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
 
 \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.
 
 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> \\
 <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}''
 & & | ``\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>
 
 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}
 \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
 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.
 
 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
 \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
 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.
 
 has no command name and no syntax, but needs a description
 nonetheless.
 

+\revision{1}
+

 \noperm
 
 \begin{responses}
 \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.
   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}
 
 \end{responses}
 

+\input{commands}
+

 \end{document}
 \end{document}