Update port documentation

* doc/ref/api-io.texi: Update for refactorings.

doc/ref/api-io.texi

@@ -230,9 +230,9 @@ Return the next character available from @var{port}, updating
 @var{port} to point to the following character.  If no more
 characters are available, the end-of-file object is returned.
 
-When @var{port}'s data cannot be decoded according to its
+When @var{port}'s data cannot be decoded according to its character
-character encoding, a @code{decoding-error} is raised and
+encoding, a @code{decoding-error} is raised and @var{port} is not
-@var{port} points past the erroneous byte sequence.
+advanced past the erroneous byte sequence.
 @end deffn
 
 @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
@@ -263,9 +263,7 @@ an interactive port will hang waiting for input whenever a call
 to @code{read-char} would have hung.
 
 As for @code{read-char}, a @code{decoding-error} may be raised
-if such a situation occurs.  However, unlike with @code{read-char},
+if such a situation occurs.
-@var{port} still points at the beginning of the erroneous byte
-sequence when the error is raised.
 @end deffn
 
 @deffn {Scheme Procedure} unread-char cobj [port]
@@ -355,17 +353,13 @@ a print state, the old print state is reused.
 
 @deffn {Scheme Procedure} simple-format destination message . args
 @deffnx {C Function} scm_simple_format (destination, message, args)
-Write @var{message} to @var{destination}, defaulting to
+Write @var{message} to @var{destination}, defaulting to the current
-the current output port.
+output port.  @var{message} can contain @code{~A} and @code{~S} escapes.
-@var{message} can contain @code{~A} (was @code{%s}) and
+When printed, the escapes are replaced with corresponding members of
-@code{~S} (was @code{%S}) escapes.  When printed,
+@var{args}: @code{~A} formats using @code{display} and @code{~S} formats
-the escapes are replaced with corresponding members of
+using @code{write}.  If @var{destination} is @code{#t}, then use the
-@var{args}:
+current output port, if @var{destination} is @code{#f}, then return a
-@code{~A} formats using @code{display} and @code{~S} formats
+string containing the formatted text.  Does not add a trailing newline.
-using @code{write}.
-If @var{destination} is @code{#t}, then use the current output
-port, if @var{destination} is @code{#f}, then return a string
-containing the formatted text. Does not add a trailing newline.
 @end deffn
 
 @rnindex write-char
@@ -415,10 +409,10 @@ all open output ports.  The return value is unspecified.
 
 @deffn {Scheme Procedure} close-port port
 @deffnx {C Function} scm_close_port (port)
-Close the specified port object.  Return @code{#t} if it
+Close the specified port object.  Return @code{#t} if it successfully
-successfully closes a port or @code{#f} if it was already
+closes a port or @code{#f} if it was already closed.  An exception may
-closed.  An exception may be raised if an error occurs, for
+be raised if an error occurs, for example when flushing buffered output.
-example when flushing buffered output.  See also @ref{Ports and
+@xref{Buffering}, for more on buffered output.  See also @ref{Ports and
 File Descriptors, close}, for a procedure which can close file
 descriptors.
 @end deffn
@@ -499,7 +493,7 @@ as a block, without regard to what is in the block.  Likewise reads are
 read in at the block size, though if there are fewer bytes available to
 read, the buffer may not be entirely filled.
 
-Note that reads or writes that are larger than the buffer size go
+Note that binary reads or writes that are larger than the buffer size go
 directly to the mutable store without passing through the buffers.  If
 your access pattern involves many big reads or writes, buffering might
 not matter so much to you.
@@ -923,8 +917,6 @@ initialized with the @var{port} argument.
 @cindex Types of ports
 @cindex Port, types
 
-[Types of port; how to make them.]
-
 @menu
 * File Ports:: Ports on an operating system file.
 * String Ports:: Ports on a Scheme string.
@@ -1017,25 +1009,6 @@ is requested.
 
 If a file cannot be opened with the access requested, @code{open-file}
 throws an exception.
-
-When the file is opened, its encoding is set to the current
-@code{%default-port-encoding}, unless the @code{b} flag was supplied.
-Sometimes it is desirable to honor Emacs-style coding declarations in
-files@footnote{Guile 2.0.0 to 2.0.7 would do this by default.  This
-behavior was deemed inappropriate and disabled starting from Guile
-2.0.8.}.  When that is the case, the @code{file-encoding} procedure can
-be used as follows (@pxref{Character Encoding of Source Files,
-@code{file-encoding}}):
-
-@example
-(let* ((port     (open-input-file file))
-       (encoding (file-encoding port)))
-  (set-port-encoding! port (or encoding (port-encoding port))))
-@end example
-
-In theory we could create read/write ports which were buffered
-in one direction only.  However this isn't included in the
-current interfaces.
 @end deffn
 
 @rnindex open-input-file
@@ -2256,47 +2229,36 @@ the representation, will return an object equal (in the sense of
 @node I/O Extensions
 @subsection Implementing New Port Types in C
 
-This section describes how to implement a new port type in C.  Before
+This section describes how to implement a new port type in C.  Although
-getting to the details, here is a summary of how the generic port
+ports support many operations, as a data structure they present an
-interface works internally.
+opaque interface to the user.  To the port implementor, you have two
+additional pieces of information: the port type code, which you allocate
+when defining your port type; and a port's ``stream'', which you
+allocate when you create a port.
 
-@cindex ptob
+The type code helps you identify which ports are actually yours.  The
-@tindex scm_t_ptob_descriptor
+``stream'' is the private data associated with that port which you and
-@tindex scm_t_port
+only you control.  Get a stream from a port using the @code{SCM_STREAM}
-@findex SCM_PTAB_ENTRY
+macro.
-@findex SCM_PTOBNUM
-@vindex scm_ptobs
-Guile's port facility consists of two main data types: port type objects
-and port instances.  A port type object (or @dfn{ptob}) is of type
-@code{scm_t_ptob_descriptor}, and holds pointers to the methods that
-implement the port type.  A port instance is of type @code{scm_t_port},
-and holds all state for the port.
 
-Given an @code{SCM} variable which points to a port, the corresponding C
+A port type is created by calling @code{scm_make_port_type}.
-port object can be obtained using the @code{SCM_PTAB_ENTRY} macro.  The
-ptob can be obtained by using @code{SCM_PTOBNUM} to give an index into
-the @code{scm_ptobs} global array.
-
-@subsubheading C interface
-
-A port type object is created by calling @code{scm_make_port_type}.
 
 @deftypefun scm_t_bits scm_make_port_type (char *name, size_t (*read) (SCM port, SCM dst, size_t start, size_t count), size_t (*write) (SCM port, SCM src, size_t start, size_t count))
-Return a new port type object.  The @var{name}, @var{read} and
+Define a new port type.  The @var{name}, @var{read} and @var{write}
-@var{write} parameters are initial values for those port type fields, as
+parameters are initial values for those port type fields, as described
-described below.  The other fields are initialized with default values
+below.  The other fields are initialized with default values and can be
-and can be changed later.
+changed later.
 @end deftypefun
 
-All of the elements of the port type object, apart from @code{name}, are
+The port type has a number of associate procedures and properties which
-procedures which collectively implement the port behaviour.  Creating a
+collectively implement the port's behavior.  Creating a new port type
-new port type mostly involves writing these procedures.
+mostly involves writing these procedures.
 
 @table @code
 @item name
 A pointer to a NUL terminated string: the name of the port type.  This
-is the only element of @code{scm_t_ptob_descriptor} which is not
+property is initialized via the first argument to
-a procedure.  Set via the first argument to @code{scm_make_port_type}.
+@code{scm_make_port_type}.
 
 @item read
 A port's @code{read} implementation fills read buffers.  It should copy
@@ -2312,12 +2274,12 @@ starting at offset @code{start} and continuing for @code{count} bytes,
 and return the number of bytes that were written.
 
 @item print
-Called when @code{write} is called on the port object, to print a
+Called when @code{write} is called on the port, to print a port
-port description.  E.g., for an fport it may produce something like:
+description.  For example, for a file port it may produce something
-@code{#<input: /etc/passwd 3>}.   Set using
+like: @code{#<input: /etc/passwd 3>}.  Set using
 
 @deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate))
-The first argument @var{port} is the object being printed, the second
+The first argument @var{port} is the port being printed, the second
 argument @var{dest_port} is where its description should go.
 @end deftypefun
 
@@ -2455,7 +2417,7 @@ BOM.  Similarly, if the user writes first, then later reads will
 @emph{not} consume a BOM.
 
 @item
-For ports that do not support seeking (e.g. pipes, sockets, and
+For ports that are not random access (e.g. pipes, sockets, and
 terminals), the input and output streams are considered
 @emph{independent} for purposes of BOM handling: the first read will
 consume a BOM (if appropriate), and the first write will @emph{also}