diff --git a/libguile/ChangeLog b/libguile/ChangeLog
index 9ad69a2f7..dae4f34ec 100644
--- a/libguile/ChangeLog
+++ b/libguile/ChangeLog
@@ -1,5 +1,7 @@
 2000-01-29  Gary Houston  <ghouston@arglist.com>
 
+	* posix.c (scm_pipe): rewrote the docstring.
+
 	* filesys.c (scm_select, retrieve_select_type, get_element,
 	fill_select_type, set_element): modified so that Scheme
 	"select" tests port buffers for the ability to provide input
diff --git a/libguile/filesys.c b/libguile/filesys.c
index ad2c6a968..e8ee16c65 100644
--- a/libguile/filesys.c
+++ b/libguile/filesys.c
@@ -1050,18 +1050,19 @@ SCM_DEFINE (scm_select, "select", 3, 2, 0,
       max_fd = except_max;
   }
 
-  if (SCM_UNBNDP (secs) || SCM_FALSEP (secs))
+  /* if there's a port with a ready buffer, don't block, just
+     check for ready file descriptors.  */
+  if (read_ports_ready != SCM_EOL || write_ports_ready != SCM_EOL)
+    {
+      timeout.tv_sec = 0;
+      timeout.tv_usec = 0;
+      time_ptr = &timeout;
+    }
+  else if (SCM_UNBNDP (secs) || SCM_FALSEP (secs))
     time_ptr = 0;
   else
     {
-      /* if there's a port with a ready buffer, don't block, just
-	 check for ready file descriptors.  */
-      if (read_ports_ready != SCM_EOL || write_ports_ready != SCM_EOL)
-	{
-	  timeout.tv_sec = 0;
-	  timeout.tv_usec = 0;
-	}
-      else if (SCM_INUMP (secs))
+      if (SCM_INUMP (secs))
 	{
 	  timeout.tv_sec = SCM_INUM (secs);
 	  if (SCM_UNBNDP (usecs))
diff --git a/libguile/posix.c b/libguile/posix.c
index e75d1168b..5ceeef637 100644
--- a/libguile/posix.c
+++ b/libguile/posix.c
@@ -168,13 +168,18 @@ SCM_SYMBOL (sym_write_pipe, "write pipe");
 
 SCM_DEFINE (scm_pipe, "pipe", 0, 0, 0,
             (),
-	    "Creates a pipe which can be used for communication.  The return value\n"
-	    "is a pair in which the CAR contains an input port and the CDR an\n"
-	    "output port.  Data written to the output port can be read from the\n"
-	    "input port.  Note that both ports are buffered so it may be necessary\n"
-	    "to flush the output port before data will actually be sent across the pipe.\n"
-	    "Alternatively a buffer can be added to the port using @code{setvbuf}\n"
-	    "(see below).")
+	    "Returns a newly created pipe: a pair of ports which are linked\n"
+	    "together on the local machine.  The CAR is the input port and\n"
+	    "the CDR is the output port.  Data written (and flushed) to the\n"
+	    "output port can be read from the input port.\n"
+	    "Pipes are commonly used for communication with a newly\n"
+	    "forked child process. @code{setvbuf} can be used to remove the\n"
+	    "buffer from the output port: then data written will be\n"
+	    "available at the input port even if the output port is not\n"
+	    "flushed.  Note that the output port is likely\n"
+	    "to block if too much data is written without reading from\n"
+	    "the input port."
+	    )
 #define FUNC_NAME s_scm_pipe
 {
   int fd[2], rv;