From ed0cbff43c790d0a02cbc81775fdee6443b986c1 Mon Sep 17 00:00:00 2001
From: Wez Furlong <wez@php.net>
Date: Sat, 7 Jun 2003 14:12:51 +0000
Subject: [PATCH] Explain a bit more about the nightmare that is the
 text-mode-translation, the spawn of satan.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@130532 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/filesystem/functions/fopen.xml | 60 +++++++++++++++++++-----
 1 file changed, 48 insertions(+), 12 deletions(-)

diff --git a/reference/filesystem/functions/fopen.xml b/reference/filesystem/functions/fopen.xml
index 3a140ff22a..b00618c4f9 100644
--- a/reference/filesystem/functions/fopen.xml
+++ b/reference/filesystem/functions/fopen.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.14 $ -->
+<!-- $Revision: 1.15 $ -->
 <!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 -->
   <refentry id="function.fopen">
    <refnamediv>
@@ -122,25 +122,61 @@
     </para>
     <note>
      <para>
-      On systems that differentiate between binary ('b') and text ('t') mode
-      translation (such as Windows), the <parameter>mode</parameter> may contain
-      either the letter 'b' or the letter 't' as the last character to force
-      the translation mode to be either binary or text mode respectively.
+      Different operating system families have different line-ending
+      conventions.  When you write a text file and want to insert a line
+      break, you need to use the correct line-ending character(s) for your
+      operating system.  Unix based systems use <literal>\n</literal> as the
+      line ending character, Windows based systems use <literal>\r\n</literal>
+      as the line ending characters and Macintosh based systems use
+      <literal>\r</literal> as the the line ending character.
      </para>
      <para>
-      The default translation mode depends on the SAPI that you are using, so
-      you are encouraged to always specify the appropriate flag; you will
-      usually always want to specify 'b' if you intend for your script to be
-      portable between different platforms.
+      If you use the wrong line ending characters when writing your files, you
+      might find that other applications that open those files will "look
+      funny".
+     </para>
+     <para>
+      Windows offers a text-mode translation flag (<literal>'t'</literal>)
+      which will transparently translate <literal>\n</literal> to
+      <literal>\r\n</literal> when working with the file.  In contrast, you
+      can also use <literal>'b'</literal> to force binary mode, which will not
+      translate your data.  To use these flags, specify either
+      <literal>'b'</literal> or <literal>'t'</literal> as the last character
+      of the <parameter>mode</parameter> parameter.
+     </para>
+     <para>
+      The default translation mode depends on the SAPI and version of PHP that
+      you are using, so you are encouraged to always specify the appropriate
+      flag for portability reasons.  You should use the <literal>'t'</literal>
+      mode if you are working with plain-text files and you use
+      <literal>\n</literal> to delimit your line endings in your script, but
+      expect your files to be readable with applications such as notepad.  You
+      should use the <literal>'b'</literal> in all other cases.
      </para>
      <para>
       If you do not specify the 'b' flag when working with binary files, you
-      will experience strange problems with your data, including broken image
+      may experience strange problems with your data, including broken image
       files and strange problems with <literal>\r\n</literal> characters.
      </para>
      <para>
-      <emphasis>It is strongly recommended that you always use the 'b' flag
-      when opening files with <function>fopen</function></emphasis>.
+      <emphasis>For portability, it is strongly recommended that you always
+       use the 'b' flag when opening files with <function>fopen</function>.
+      </emphasis>
+     </para>
+     <para>
+      <emphasis>Again, for portability, it is also strongly recommended that
+       you re-write code that uses or relies upon the <literal>'t'</literal>
+       mode so that it uses the correct line endings and
+       <literal>'b'</literal> mode instead.
+      </emphasis>
+     </para>
+     <para>
+      <emphasis>As of PHP 4.3.2, the default mode is set to binary for all
+       platforms that distinguish between binary and text mode.  If you are
+       having problems with your scripts after upgrading, try using the
+       <literal>'t'</literal> flag as a workaround until you have made your
+       script more portable as mentioned above.
+      </emphasis>
      </para>
     </note>
     <para>