(Ports): Add notes on garbage collection, and on

explicitly closing file ports.
(File Ports): Cross reference Ports node on explicit closing.

doc/ref/scheme-io.texi

@@ -19,19 +19,44 @@
 @node Ports
 @section Ports
 
-[Concept of the port abstraction.]
-
 Sequential input/output in Scheme is represented by operations on a
-@dfn{port}.  Characters can be read from an input port and
+@dfn{port}.  This chapter explains the operations that Guile provides
-written to an output port.  This chapter explains the operations
+for working with ports.
-that Guile provides for working with ports.
+
+Ports are created by opening, for instance @code{open-file} for a file
+(@pxref{File Ports}).  Characters can be read from an input port and
+written to an output port, or both on an input/output port.  A port
+can be closed (@pxref{Closing}) when no longer required, after which
+any attempt to read or write is an error.
 
 The formal definition of a port is very generic: an input port is
-simply ``an object which can deliver characters on command,'' and
+simply ``an object which can deliver characters on demand,'' and an
-an output port is ``an object which can accept characters.''
+output port is ``an object which can accept characters.''  Because
-Because this definition is so loose, it is easy to write functions
+this definition is so loose, it is easy to write functions that
-that simulate ports in software.  @dfn{Soft ports} and @dfn{string
+simulate ports in software.  @dfn{Soft ports} and @dfn{string ports}
-ports} are two interesting and powerful examples of this technique.
+are two interesting and powerful examples of this technique.
+(@pxref{Soft Ports}, and @ref{String Ports}.)
+
+Ports are garbage collected in the usual way (@pxref{Memory
+Management}), and will be closed at that time if not already closed.
+In this case any errors occuring in the close will not be reported.
+Usually a program will want to explicitly close so as to be sure all
+its operations have been successful.  Of course if a program has
+abandoned something due to an error or other condition then closing
+problems are probably not of interest.
+
+It is strongly recommended that file ports be closed explicitly when
+no longer required.  Most systems have limits on how many files can be
+open, both on a per-process and a system-wide basis.  A program that
+uses many files should take care not to hit those limits.  The same
+applies to similar system resources such as pipes and sockets.
+
+Note that automatic garbage collection is triggered only by memory
+consumption, not by file or other resource usage, so a program cannot
+rely on that to keep it away from system limits.  An explicit call to
+@code{gc} can of course be relied on to pick up unreferenced ports.
+If program flow makes it hard to be certain when to close then this
+may be an acceptable way to control resource usage.
 
 @rnindex input-port?
 @deffn {Scheme Procedure} input-port? x
@@ -623,6 +648,10 @@ The following procedures are used to open file ports.
 See also @ref{Ports and File Descriptors, open}, for an interface
 to the Unix @code{open} system call.
 
+Most systems have limits on how many files can be open, so it's
+strongly recommended that file ports be closed explicitly when no
+longer required (@pxref{Ports}).
+
 @deffn {Scheme Procedure} open-file filename mode
 @deffnx {C Function} scm_open_file (filename, mode)
 Open the file whose name is @var{filename}, and return a port