doco ports verbiage

[Kevin Ryde]

This is in the interests of reducing duplication.  For with- and
call-with- I found it a bit hard to see quite what was going on with
five rather similar chunks of text.

        * scheme-io.texi (File Ports): Describe call-with-input-file and
        call-with-output-file together.  Describe with-input-from-file,
        with-output-to-file and with-error-to-file together.
        (Closing): Describe close-input-port and close-output-port together,
        tweak the wording slightly.

The words are slightly rearranged in support of this, but what's
specified is not changed.



 - Scheme Procedure: call-with-input-file filename proc
 - Scheme Procedure: call-with-output-file filename proc
     Open FILENAME for input or output, and call `(PROC port)' with the
     resulting port.  Return the value returned by PROC.

     For input, FILENAME must exist.  For output, if FILENAME already
     exists the behaviour is unspecified.  In both cases if FILENAME
     cannot be opened an error is signalled.

     When PROC returns, the port is closed.  If PROC does not return
     (eg. if it throws an error), then the port might not be closed
     automatically, though it will be garbage collected in the usual
     way if not otherwise referenced.

 - Scheme Procedure: with-input-from-file filename thunk
 - Scheme Procedure: with-output-to-file filename thunk
 - Scheme Procedure: with-error-to-file filename thunk
     Open FILENAME and call `(THUNK)' with the port setup as
     respectively the `current-input-port', `current-output-port', or
     `current-error-port'.  Return the value returned by THUNK.

     For input, FILENAME must exist.  For output and error output, if
     FILENAME already exists the behaviour is unspecified.  In all
     cases if FILENAME cannot be opened, an error is signalled.

     When THUNK returns, the port is closed and the previous setting of
     the respective current port is restored.  If THUNK does not return
     (eg. if it throws an error), then what happens to the ports is
     unspecified.




 - Scheme Procedure: close-input-port port
 - Scheme Procedure: close-output-port port
 - C Function: scm_close_input_port (port)
 - C Function: scm_close_output_port (port)
     Close the specified input or output PORT.  An exception may be
     raised if an error occurs while closing.  If PORT is already
     closed, nothing is done.  The return value is unspecified.

     See also *Note close: Ports and File Descriptors, for a procedure
     which can close file descriptors.

scheme-io.texi.ports.diff
Description: Text document