[Guile-commits] 04/04: Fix documentation of R6RS 'binary-port?' to reflect reality.

[Mark H. Weaver]

mhw pushed a commit to branch stable-2.2
in repository guile.

commit 2095033b42edc91d24dad7a6e9b716b94992342e
Author: Mark H Weaver <address@hidden>
Date:   Sun Apr 28 03:55:40 2019 -0400

    Fix documentation of R6RS 'binary-port?' to reflect reality.
    
    * doc/ref/r6rs.texi (rnrs io ports): Improve the descriptions of
    'binary-port?' and 'textual-port?'.
    * module/rnrs/io/ports.scm (binary-port?, textual-port?): Update the
    docstrings.
---
 doc/ref/r6rs.texi        | 21 +++++++++++++++++----
 module/rnrs/io/ports.scm | 18 +++++++++++++-----
 2 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi
index fa8d7d2..218dca3 100644
--- a/doc/ref/r6rs.texi
+++ b/doc/ref/r6rs.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @c Copyright (C)  2010, 2011, 2012, 2013,
-@c   2014 Free Software Foundation, Inc.
+@c   2014, 2019 Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @node R6RS Support
@@ -1680,9 +1680,22 @@ Return a transcoder associated with the encoding of 
@var{port}.
 @end deffn
 
 @deffn {Scheme Procedure} binary-port? port
-@deffnx {Scheme Procedure} textual-port? port
-Return @code{#t}, as all ports in Guile are suitable for binary and
-textual I/O.  @xref{Encoding}, for more details.
+Return @code{#t} if @var{port} appears to be a binary port, else return
+@code{#f}.  Note that Guile does not currently distinguish between
+binary and textual ports, so this predicate is not a reliable indicator
+of whether the port was created as a binary port.  Currently, it returns
+@code{#t} if and only if the port encoding is ``ISO-8859-1'', because
+Guile uses this encoding when creating a binary port.  @xref{Encoding},
+for more details.
+@end deffn
+
+@deffn {Scheme Procedure} textual-port? port
+Return @code{#t} if @var{port} appears to be a textual port, else return
+@code{#f}.  Note that Guile does not currently distinguish between
+binary and textual ports, so this predicate is not a reliable indicator
+of whether the port was created as a textual port.  Currently, it always
+returns @code{#t}, because all ports can be used for textual I/O in
+Guile.  @xref{Encoding}, for more details.
 @end deffn
 
 @deffn {Scheme Procedure} transcoded-port binary-port transcoder
diff --git a/module/rnrs/io/ports.scm b/module/rnrs/io/ports.scm
index 5946067..c19aee9 100644
--- a/module/rnrs/io/ports.scm
+++ b/module/rnrs/io/ports.scm
@@ -1,6 +1,6 @@
 ;;;; ports.scm --- R6RS port API                    -*- coding: utf-8 -*-
 
-;;;;   Copyright (C) 2009, 2010, 2011, 2013 Free Software Foundation, Inc.
+;;;; Copyright (C) 2009-2011, 2013, 2019 Free Software Foundation, Inc.
 ;;;;
 ;;;; This library is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU Lesser General Public
@@ -269,13 +269,21 @@ if the port has no transcoder."
                                 "unsupported error handling mode"))))))
 
 (define (binary-port? port)
-  "Always returns @code{#t}, as all ports can be used for binary I/O in
-Guile."
+  "Return @code{#t} if @var{port} appears to be a binary port, else
+return @code{#f}.  Note that Guile does not currently distinguish
+between binary and textual ports, so this predicate is not a reliable
+indicator of whether the port was created as a binary port.  Currently,
+it returns @code{#t} if and only if the port encoding is ``ISO-8859-1'',
+because Guile uses this encoding when creating a binary port."
   (equal? (port-encoding port) "ISO-8859-1"))
 
 (define (textual-port? port)
-  "Always returns @code{#t}, as all ports can be used for textual I/O in
-Guile."
+  "Return @code{#t} if @var{port} appears to be a textual port, else
+return @code{#f}.  Note that Guile does not currently distinguish
+between binary and textual ports, so this predicate is not a reliable
+indicator of whether the port was created as a textual port.  Currently,
+it always returns @code{#t}, because all ports can be used for textual
+I/O in Guile."
   #t)
 
 (define (port-eof? port)