Reasonably complete and up-to-date docs.

doc/latex/nettime.tex

@@ -1,57 +1,55 @@
-\chapter{Using Time and Daytime Protocol}\label{cha:ntp}
-%
-\begin{description}
-\item[Used files:] nettime.scm nettime-obsolete.scm
-\item[Name of the package:] nettime nettime-obsolete
-\end{description}
-%
+\chapter{Time and Daytime}\label{cha:ntp}
 
-\subsection{Overview}
-Most Unix hosts provide a Daytime service which sends the current date
-and time as a human-readable character string. The daytime service is
-typically served on port 13 as both TCP and UDP.
+Many Unix hosts provide a RFC~867 Daytime service which sends the
+current date and time as a human-readable character string. The
+daytime service is typically served on port 13 as both TCP and UDP.
 
-The Time protocol provides a site-independent, machine readable date
-and time. A ``time'' consists of the number of seconds since midnight on
-1st January 1900. The Time service is typically served on port 37 as
-TCP and UDP. The idea is that you can confirm your system's idea of
-the time by polling several independent sites on the network.
+The RFC~868 Time protocol provides a site-independent, machine
+readable date and time.  The Time service is typically served
+on port 37 as TCP and UDP. The idea is that you can confirm your
+system's idea of the time by polling several independent sites on the
+network.
 
-\subsection{Procedures}
+\section{Daytime}
 
-\begin{defundesc}{net-time}{host tcp/udp}{integer}
-  Asks \semvar{host} about the current time. \semvar{tcp/udp} is
-  either \ex{socket\=type/\ob{}stream} or
-  \ex{socket\=type/\ob{}datagram}, that indicate TCP or UDP
-  connection, respectively (depends on the server).  The number of
-  second since 1970 is returned, since the time protocol returns the
-  number of seconds since 1900, whereas Unix time is since 1970. The
-  difference between both answers is 2208988800.
-\end{defundesc}
+The \ex{rfc867} structure contains an interface to Daytime protocol.
 
-\begin{defundesc}{net-daytime}{host tcp/udp}{string}
-  Asks \semvar{host} about the current daytime. \semvar{tcp/udp} is
-  the same as in \ex{net:time}, indicating to use TCP or UDP. The
-  host's answer is returned (e.g., ``Thursday, April 4, 2'').
-\end{defundesc}
+\defun{rfc867-daytime/tcp}{host}{string}
+\defunx{rfc867-daytime/udp}{host [timeout-or-\sharpf]}{string-or-\sharpf}
+\begin{desc}
+  These procedures asks \var{host} about the current daytime and
+  return the host's answer (e.g., ``Thursday, April 4,
+  2'').
+  
+  \ex{Rfc867-daytime/tcp} uses the TCP variant of the protocol.
+  \ex{Rfc867-daytime/udp} uses UDP and sends a single request to the
+  server.  It allows the specification of an optional timeout; if not
+  specified or \sharpf{}, \ex{Rfc867-daytime/udp} will wait
+  indefinitely for an answer.  If the answer from the server doesn't
+  arrive within the specified time, \ex{rfc867-daytime/udp} returns
+  \sharpf.
+\end{desc}
 
-\subsubsection*{Obsolete procedures}
+\section{Time}
 
-Names in further versions of \ex{nettime} contained a colon (`\ex{:}')
-after the prefix `\ex{net-}'. This is now changed to a hyphen
-('\ex{-}'), accordingly to SUnet's philosophy. If you need the old
-names, use the \ex{nettime\=obsolete}-package that maps the old names
-to the new ones.
+The \ex{rfc868} structure contains an interface to the Time protocol.
+
+\defun{rfc868-time/tcp}{host}{string}
+\defunx{rfc868-time/udp}{host [timeout-or-\sharpf]}{string-or-\sharpf}
+\begin{desc}
+  These procedures asks \var{host} about the current time and return
+  the host's answer.  This is the number of second since 1970, just as
+  with scsh's \texttt{time} procedure.
+
+  \ex{rfc868-time/tcp} uses the TCP variant of the protocol.
+  \ex{rfc868-time/udp} uses UDP and sends a single request to the
+  server.  It allows the specification of an optional timeout; if not
+  specified or \sharpf{}, \ex{rfc868-time/udp} will wait
+  indefinitely for an answer.  If the answer from the server doesn't
+  arrive within the specified time, \ex{rfc868-time/udp} returns
+  \sharpf.
+\end{desc}
 
-\subsection{Related work}
-\begin{itemize}
-\item \ex{Time.pm} is a Perl module by Graham Barr
-\item RFC~868 describes the Time protocol
-\item RFC~867 describes the Daytime protocol in all its glory
-\item For a genuinely useful protocol look at the Network Time
-  Protocol defined in RFC~1305, which allows for the synchronization
-  of clocks on networked computers.
-\end{itemize}
 
 %%% Local Variables: 
 %%% mode: latex