From 18832d8a641ff25fefccddd34c0325bc8089a69c Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Thu, 28 Nov 2013 09:11:22 -0800
Subject: * txr.1: Documented open-tail and make-time.

---
 ChangeLog |  4 ++++
 txr.1     | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 736c351d..b4740778 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2013-11-28  Kaz Kylheku  <kaz@kylheku.com>
+
+	* txr.1: Documented open-tail and make-time.
+
 2013-11-28  Kaz Kylheku  <kaz@kylheku.com>
 
 	Extending intrinsic functions to go up to 7 arguments.
diff --git a/txr.1 b/txr.1
index 6d98aab7..5df7c02d 100644
--- a/txr.1
+++ b/txr.1
@@ -10355,6 +10355,38 @@ or output stream. Note that the "b" mode is not supported.
 Whether a stream is text or binary depends on which operations
 are invoked on it.
 
+.SS Function open-tail
+
+.TP
+Syntax:
+
+  (open-tail <path> <mode-string> <seek-to-end-p>)
+
+.TP
+Description:
+
+The open-tail function creates a tail stream connected to the file which is
+located at the given <path>.  The <mode-string> argument is a string which uses
+the same conventions as the mode argument of the C language fopen function.
+The mode string determines whether the stream is an input stream
+or output stream. Note that the "b" mode is not supported.
+Whether a stream is text or binary depends on which operations
+are invoked on it. The <seek-to-end-p> argument is a boolean whcih
+determines whether the initial read/write position is at the
+start of the file, or just past the end.
+
+A tail stream has special semantics with regard to reading at the end
+of file. A tail stream never reports an end-of-file condition; instead
+it polls the file until more data is added. Furthermore, if the file
+is truncated, or replaced with a smaller file, the tail stream follows
+this change: it automatically opens the smaller file and starts reading from
+the beginning (the <seek-to-end-p> flag only applies to the initial open).
+In this manner, a tail stream can dynamically growing rotating log files.
+
+Caveat: since a tail stream can re-open a new file which has the same
+name as the original file, it will do the wrong thing if the program
+changes the current working directory, and the path name is relative.
+
 .SH COPROCESSES
 
 .SS Functions open-command, open-process
@@ -10743,6 +10775,31 @@ the format string of the C library function strftime.
 The <time> argument is an integer representing seconds obtained from the
 time function or from the time-usec function.
 
+.SS Function make-time
+
+.TP
+Syntax:
+
+  (make-time <year> <month> <day> <hour> <minute> <second> <dst-advice>)
+
+.TP
+Description
+
+The make-time function returns a time value, similar to the one returned by the
+time function.  The time value is constructed not from the system clock, but
+from a date and time specified as arguments. The <year> argument is a
+calendar year, like 2013. The <month> argument ranges from 1 through 12.
+These arguments represent a local time, in the current time zone.
+
+The <dst-advice> argument specifies whether the time is expressed in
+daylight savings time (DST). It takes on these values: nil, the keyword :auto,
+or any other value which denotes boolean true.
+
+If <dst-advice> is t, then the time is assumed to be expressed in DST.
+If the argument is nil, then the time is assumed not to be in DST.
+If <dst-advice> is :auto, then the function tries to determine whether
+DST is in effect in the current time zone for the specified date and time.
+
 .SH WEB PROGRAMMING SUPPORT
 
 .SS Functions url-encode and url-decode
-- 
cgit v1.2.3