From b352d0e82522befd4ca9c18ad427dcff28d5b397 Mon Sep 17 00:00:00 2001
From: shivers <shivers>
Date: Fri, 18 Apr 1997 01:59:42 +0000
Subject: [PATCH] - Added warning to DATE doc about mktime() lossage. -
 Documented behavior of delete-{file,directory,filesys-object} when   the
 named thing doesn't exist. - Documented new regexp-substitute procedures.

---
 doc/scsh-manual/strings.tex  | 53 ++++++++++++++++++++++++++++++++++++
 doc/scsh-manual/syscalls.tex | 12 ++++++++
 2 files changed, 65 insertions(+)

diff --git a/doc/scsh-manual/strings.tex b/doc/scsh-manual/strings.tex
index ecac6b6..24ca51a 100644
--- a/doc/scsh-manual/strings.tex
+++ b/doc/scsh-manual/strings.tex
@@ -89,6 +89,59 @@ to all the special regexp characters in \var{str}.
     {\evalto}"\\\\*Hello\\\\* world\\\\."\end{code}
 \end{desc}
 
+\defun{regexp-substitute}{port match . items}{{\str} or \undefined}
+\begin{desc}
+This procedure can be used to perform string substitutions based on
+regular expression matches.
+The results of the substitution can be either output to a port or
+returned as a string.
+
+The \var{match} argument is a regular expression match structure
+that controls the substitution.
+If \var{port} is an output port, the \var{items} are written out to
+the port:
+\begin{itemize}
+    \item If an item is a string, it is copied directly to the port.
+    \item If an item is an integer, the corresponding submatch from \var{match}
+      is written to the port.
+    \item If an item is \ex{'pre}, 
+          the prefix of the matched string (the text preceding the match) 
+	  is written to the port.
+    \item If an item is \ex{'post}, 
+          the suffix of the matched string is written.
+\end{itemize}
+
+If \var{port} is {\sharpf}, nothing is written, and a string is constructed
+and returned instead.
+\end{desc}
+
+\defun{regexp-substitute/global}{port regexp string . items}
+                                {{\str} or \boolean}
+\begin{desc}
+This procedure is similar to \ex{regexp-substitute}, 
+but can be used to perform multiple match/substitute operations over
+a string.
+It has the following differences with \ex{regexp-substitute}:
+\begin{itemize}
+  \item It takes a regular expression and string to be matched as
+        parameters, instead of a completed match structure.
+  \item If an item is \ex{'post}, the procedure recurses on the suffix string
+        (the text from \var{string} following the match).
+  \item If \var{port} is an output port:
+    \begin{itemize}
+      \item There was at least one match: return true.
+      \item No match: return false.
+    \end{itemize}
+
+  \item \var{port} is \sharpf:
+    \begin{itemize}
+      \item There was at least one match: construct and return a string.
+      \item No match: return false.
+    \end{itemize}
+  \end{itemize}
+
+\end{desc}
+
 \subsection{Other string manipulation facilities}
 
 \defun  {index}  {string char [start]} {{\fixnum} or false}
diff --git a/doc/scsh-manual/syscalls.tex b/doc/scsh-manual/syscalls.tex
index 79964a2..274bd8c 100644
--- a/doc/scsh-manual/syscalls.tex
+++ b/doc/scsh-manual/syscalls.tex
@@ -1108,6 +1108,10 @@ These procedures delete objects from the file system.
 The {\ttt delete\=filesys\=object} procedure will delete an object
 of any type from the file system: files, (empty) directories, symlinks, fifos,
 \etc.
+
+If the object being deleted doesn't exist, \ex{delete-directory} and
+\ex{delete-file} raise an error, 
+while \ex{delete-filesys-object} simply returns.
 \end{defundescx}
 
 \begin{defundescx}{read-symlink}{fname} \str
@@ -2758,6 +2762,14 @@ String		&	A {\Posix} time zone string understood by the OS
     field is a {\Posix} time zone of the form
     ``\ex{UTC+\emph{hh}:\emph{mm}:\emph{ss}}''; 
     the trailing \ex{:\emph{mm}:\emph{ss}} portion is deleted if it is zeroes.
+
+    \oops{The Posix facility for converting dates to times, \ex{mktime()},
+          has a broken design: it indicates an error by returning -1, which
+          is also a legal return value (for date 23:59:59 UCT, 12/31/1969).
+          Scsh resolves the ambiguity in a paranoid fashion: it always
+          reports an error if the underlying Unix facility returns -1.
+	  We feel your pain.
+	  }
 \end{desc}
 
 \defun {time} {} \integer