extend UPGRADING

diff --git a/UPGRADING b/UPGRADING
index cbf1e8a8ea52505af88d0d72036367ad3e950ebd..0e3115e19ae57b6ce921dc16b7a1dd8a3df16d0e 100644 (file)
--- a/UPGRADING
+++ b/UPGRADING
@@ -417,7 +417,7 @@ PHP 7.1 UPGRADE NOTES
 - Core:
   . Support for long and UTF-8 path;
 
-    If an application is UTF-8 conform, no further action is required. For
+    If a web application is UTF-8 conform, no further action is required. For
     applications depending on paths in non UTF-8 encodings for I/O, an explicit
     INI directive has to be set. The encoding INI settings check relies on the
     order in the core:
@@ -443,8 +443,26 @@ PHP 7.1 UPGRADE NOTES
     particular console program used. PHP automatically sets the console codepage
     according to the encoding rules from php.ini. Using alternative consoles
     instead of cmd.exe directly might bring better experience in some cases.
+
     Nevertheless be aware, runtime codepage switch after the request start
-    might bring unexpected side effects on CLI. The preferrable way is php.ini.
+    might bring unexpected side effects on CLI. The preferrable way is php.ini,
+    When PHP CLI is used in a console emulator, that doesn't support Unicode,
+    it might possibly be required, to avoid changing the console codepage. The
+    best way to achieve it is by setting the default or internal encoding to
+    correspond the ANSI codepage. Another method is to set the INI directives
+    output_encoding and input_encoding to the required codepage, in which case
+    however the difference between internal and I/O codepage is likely to cause
+    mojibake. In rare cases, if PHP happens to crash gracefully, the original
+    console codepage might be not restored. In this case, the chcp command
+    can be used, to restore it manually.
+
+    Special awareness for the DBCS systems - the codepage switch on runtime
+    using ini_set() is likely to cause display issues. The difference to the
+    non DBCS systems is, that the extended characters require two console cells
+    to be displayed. In certain case, only the mapping of the characters into
+    the glyph set of the font could happen, no actual font change. This is the
+    nature of DBCS systems, the most simple way to prevent display issues is
+    to avoid usage of ini_set() for the codepage change.
 
     As a result of UTF-8 support in the streams, PHP scripts are not limited
     to ASCII or ANSI filenames anymore. This is supported out of the box on
@@ -456,8 +474,10 @@ PHP 7.1 UPGRADE NOTES
     2048 bytes. Be aware, that the path segment limit (basename length) still
     persists.
 
-    The recommended way to handle file paths, I/O and other related topics is
-    by utilizing UTF-8.
+    For the best portability, it is strongely recommended to handle filenames,
+    I/O and other related topics UTF-8. Additionally, for the console applications,
+    the usage of a TrueType font is preferrable and the usage of ini_set() for
+    the codepage change is discouraged.
 
   . Support for ftok()