From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: b3timmons@speedymail.org Newsgroups: gmane.lisp.guile.bugs Subject: Please clarify docs for open-file procedure (in trunk) Date: Wed, 10 Aug 2011 13:27:31 -0400 Message-ID: <87bovxjhx8.fsf@goof.bjgalaxy> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: dough.gmane.org 1313014182 7070 80.91.229.12 (10 Aug 2011 22:09:42 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 10 Aug 2011 22:09:42 +0000 (UTC) To: bug-guile@gnu.org Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Thu Aug 11 00:09:38 2011 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QrGy1-0002Nv-TR for guile-bugs@m.gmane.org; Thu, 11 Aug 2011 00:09:38 +0200 Original-Received: from localhost ([::1]:42771 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QrGy1-0008Sp-7U for guile-bugs@m.gmane.org; Wed, 10 Aug 2011 18:09:37 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:50059) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1QrGxy-0008Si-Ne for bug-guile@gnu.org; Wed, 10 Aug 2011 18:09:35 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1QrGxx-0002Mf-NR for bug-guile@gnu.org; Wed, 10 Aug 2011 18:09:34 -0400 Original-Received: from mail-yw0-f41.google.com ([209.85.213.41]:35235) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <42toes@gmail.com>) id 1QrGxx-0002MQ-Kq for bug-guile@gnu.org; Wed, 10 Aug 2011 18:09:33 -0400 Original-Received: by ywm13 with SMTP id 13so279274ywm.0 for ; Wed, 10 Aug 2011 15:09:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=sender:from:to:subject:date:message-id:user-agent:mime-version :content-type; bh=3axU6/yZgscMfPP1qHBR1QfspU80ernhP8Js31YeeWk=; b=yDE00t2m8Z+IbOnmiTmK76wst3NJRazenmiUDtv5flNwBTZRbLj4JsoKDool9++zBc QYjcewM0ymq07fhI6mzp29JooOIncbW0UWnyE2wjrVD3Rzqzf4m6C6N/ykxORDgdycwY C/azO8ReSi8wjH1/7II8TB80bc1mBH0lNpaog= Original-Received: by 10.90.17.6 with SMTP id 6mr4194641agq.66.1313014172860; Wed, 10 Aug 2011 15:09:32 -0700 (PDT) Original-Received: from goof.bjgalaxy ([208.103.134.167]) by mx.google.com with ESMTPS id p34sm1128052ann.43.2011.08.10.15.09.29 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 10 Aug 2011 15:09:31 -0700 (PDT) Original-Received: from b3po by goof.bjgalaxy with local (Exim 4.76) (envelope-from ) id 1QrCZ1-0006Cc-SM for bug-guile@gnu.org; Wed, 10 Aug 2011 13:27:31 -0400 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 209.85.213.41 X-BeenThere: bug-guile@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Original-Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.bugs:5764 Archived-At: Hi, I think the documentation (in trunk) for the open-file procedure (in file doc/ref/api-io.texi) needs clarification, especially for newbies to encoding issues such as myself. In particular, consider the description for the binary flag b: ---------------------------------------------------------------------- @item b Use binary mode. On DOS systems the default text mode converts CR+LF in the file to newline for the program, whereas binary mode reads and writes all bytes unchanged. On Unix-like systems there is no such distinction, text files already contain just newlines and no conversion is ever made. The @code{b} flag is accepted on all systems, but has no effect on Unix-like systems. (For reference, Guile leaves text versus binary up to the C library, @code{b} here just adds @code{O_BINARY} to the underlying @code{open} call, when that flag is available.) Also, open the file using the 8-bit character encoding "ISO-8859-1", ignoring any coding declaration or port encoding. ... ---------------------------------------------------------------------- I stopped reading here, thinking that the b flag "has no effect on" reading my binary data. Yet, as subsequently explained, it does indeed have an effect on the encoding used to open the file. How about something like: ---------------------------------------------------------------------- @item b Use binary mode. In general this might affect handling of line endings and file encodings. Regarding line endings, on DOS systems the default text mode converts CR+LF in the file to newline for the program, whereas binary mode reads and writes all bytes unchanged. On Unix-like systems there is no such distinction, text files already contain just newlines and no conversion is ever made. The @code{b} flag is accepted on all systems, but has no effect on Unix-like systems. (For reference, Guile leaves text versus binary up to the C library, @code{b} here just adds @code{O_BINARY} to the underlying @code{open} call, when that flag is available.) Regarding file encodings, a file opened in binary mode uses the 8-bit character encoding "ISO-8859-1", ignoring any coding declaration or port encoding. ---------------------------------------------------------------------- A bit of redundancy like this might help newbies such as myself avoid a misunderstanding here. I should also point out a grammatical mistake further on: ---------------------------------------------------------------------- When the file is opened, this procedure will scan for a coding declaration (@pxref{Character Encoding of Source Files}). If present will use that encoding for interpreting the file. Otherwise, the port's encoding will be used. To suppress this behavior, open the file in binary mode and then set the port encoding explicitly using @code{set-port-encoding!}. ---------------------------------------------------------------------- The paragraph contains in its middle the following fragment: "If present will use that encoding for interpreting the file." How about: "If it is found, the corresponding encoding will be used to interpret the file." ? Thanks, Bake