Update port documentation, rename sports to suspendable ports

* module/ice-9/suspendable-ports.scm: Rename from ice-9/sports.scm, and
  adapt module names.  Remove exports that are not related to the
  suspendable ports facility; we want people to continue using the port
  operations from their original locations.  Add put-string to the
  replacement list.
* module/Makefile.am: Adapt to rename.
* test-suite/tests/suspendable-ports.test: Rename from sports.test.
* test-suite/Makefile.am: Adapt to rename.
* module/ice-9/textual-ports.scm (unget-char, unget-string): New
  functions.
* doc/ref/api-io.texi (Textual I/O, Simple Output): Flesh out
  documentation.
  (Line/Delimited): Undocument write-line, read-string, and
  read-string!.  This is handled by (ice-9 textual-ports).
  (Bytevector Ports): Fix duplicated section.
  (String Ports): Move the note about encodings down to the end.
  (Custom Ports): Add explanatory text.  Remove mention of C functions;
  they should use the C port interface.
  (Venerable Port Interfaces): Add text, and make documentation refer to
  recommended interfaces.
  (Using Ports from C): Add documentation.
  (Non-Blocking I/O): Document more fully and adapt to suspendable-ports
  name change.

module/Makefile.am

@@ -106,10 +106,10 @@ SOURCES =					\
   ice-9/serialize.scm				\
   ice-9/session.scm				\
   ice-9/slib.scm				\
-  ice-9/sports.scm				\
   ice-9/stack-catch.scm				\
   ice-9/streams.scm				\
   ice-9/string-fun.scm				\
+  ice-9/suspendable-ports.scm			\
   ice-9/syncase.scm				\
   ice-9/textual-ports.scm			\
   ice-9/threads.scm				\

module/ice-9/suspendable-ports.scm

@@ -48,30 +48,15 @@
 ;;; Code:
 
 
-(define-module (ice-9 sports)
+(define-module (ice-9 suspendable-ports)
   #:use-module (rnrs bytevectors)
   #:use-module (ice-9 ports internal)
   #:use-module (ice-9 match)
-  #:replace (peek-char
-             read-char
-             force-output
-             close-port)
   #:export (current-read-waiter
             current-write-waiter
 
-            lookahead-u8
-            get-u8
-            get-bytevector-n
-            put-u8
-            put-bytevector
-            put-string
-
-            %read-line
-            read-line
-            read-delimited
-
-            install-sports!
-            uninstall-sports!))
+            install-suspendable-ports!
+            uninstall-suspendable-ports!))
 
 (define (default-read-waiter port) (port-poll port "r"))
 (define (default-write-waiter port) (port-poll port "w"))
@@ -681,11 +666,14 @@
     ((ice-9 binary-ports)
      get-u8 lookahead-u8 get-bytevector-n
      put-u8 put-bytevector)
+    ((ice-9 textual-ports)
+     ;; FIXME: put-char
+     put-string)
     ((ice-9 rdelim) %read-line read-line read-delimited)))
-(define (install-sports!)
+(define (install-suspendable-ports!)
   (unless saved-port-bindings
     (set! saved-port-bindings (make-hash-table))
-    (let ((sports (resolve-module '(ice-9 sports))))
+    (let ((suspendable-ports (resolve-module '(ice-9 suspendable-ports))))
       (for-each
        (match-lambda
          ((mod . syms)
@@ -694,11 +682,11 @@
                         (hashq-set! saved-port-bindings sym
                                     (module-ref mod sym))
                         (module-set! mod sym
-                                     (module-ref sports sym)))
+                                     (module-ref suspendable-ports sym)))
                       syms))))
        port-bindings))))
 
-(define (uninstall-sports!)
+(define (uninstall-suspendable-ports!)
   (when saved-port-bindings
     (for-each
      (match-lambda

module/ice-9/textual-ports.scm

@@ -28,6 +28,8 @@
                put-char
                put-string)
   #:export (get-char
+            unget-char
+            unget-string
             lookahead-char
             get-string-n
             get-string-all
@@ -39,6 +41,17 @@
 (define (lookahead-char port)
   (peek-char port))
 
+(define (unget-char port char)
+  (unread-char char port))
+
+(define* (unget-string port string #:optional (start 0)
+                       (count (- (string-length string) start)))
+  (unread-string (if (and (zero? start)
+                          (= count (string-length string)))
+                     string
+                     (substring/shared string start (+ start count)))
+                 port))
+
 (define (get-line port)
   (read-line port 'trim))