File 1241-doc-Document-UTF-8-as-default-atom-encodin... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 1241-doc-Document-UTF-8-as-default-atom-encoding-in-OTP-2.patch of Package erlang (Revision 3a70bf3d6fd4a5cb52eaedadd0de8996)

Currently displaying revision 3a70bf3d6fd4a5cb52eaedadd0de8996 , Show latest

From b999603a862b67d30f735e64d3f1f5ab62767ab6 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson <sverker@erlang.org>
Date: Fri, 22 Oct 2021 20:18:59 +0200
Subject: [PATCH] doc: Document UTF-8 as default atom encoding in OTP 26

by term_to_binary and term_to_iovec.
---
 erts/doc/src/erlang.xml                       | 13 ++++--
 .../upcoming_incompatibilities.xml            | 40 +++++++++++++++++++
 2 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 3b96ed5039..7a80d584bf 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -11093,7 +11093,7 @@ hello
 	    </item>
 	    <tag><c>1</c></tag>
 	    <item>
-              <p>This is as of Erlang/OTP 17.0 the default. It forces any floats
+              <p>This is as of Erlang/OTP 17.0 the <em>default</em>. It forces any floats
 	      in the term to be encoded in a more space-efficient and exact way
 	      (namely in the 64-bit IEEE format, rather than converted to a
 	      textual representation). As from Erlang/OTP R11B-4,
@@ -11105,9 +11105,16 @@ hello
 	    <tag><c>2</c></tag>
 	    <item>
               <p>Drops usage of the latin1 atom encoding and unconditionally
-	      use utf8 encoding for all atoms. This will be changed to the
-	      default in a future major release of Erlang/OTP. Erlang/OTP
+	      use utf8 encoding for all atoms. Erlang/OTP
 	      systems as of R16B can decode this representation.</p>
+              <note>
+                <p>In Erlang/OTP 26, the default <c>minor_version</c> is planned
+                to change from 1 to 2. See
+                <seeguide marker="system/general_info:upcoming_incompatibilities#atoms_be_utf8">
+                  Upcoming Potential Incompatibilities
+                </seeguide>.
+                </p>
+              </note>
 	    </item>
 	  </taglist>
           <p>Option <c>deterministic</c> (introduced in OTP 24.1) can
diff --git a/system/doc/general_info/upcoming_incompatibilities.xml b/system/doc/general_info/upcoming_incompatibilities.xml
index 02b9c35bda..69a0f6de16 100644
--- a/system/doc/general_info/upcoming_incompatibilities.xml
+++ b/system/doc/general_info/upcoming_incompatibilities.xml
@@ -92,5 +92,45 @@
       </p>
     </section>
 
+    <section>
+      <marker id="atoms_be_utf8"/>
+      <title>Atoms will be encoded as UTF-8 by default</title>
+      <p>
+	As of OTP 26, the functions
+        <seemfa marker="erts:erlang#term_to_binary/1">
+        <c>erlang:term_to_binary/1,2</c></seemfa> and
+        <seemfa marker="erts:erlang#term_to_iovec/1">
+        <c>erlang:term_to_iovec/1,2</c></seemfa> will encode all atoms as
+        UTF-8 by default. The current default behavior is to encode atoms as
+        Latin-1 if possible.
+      </p>
+      <p>
+	If you implement your own decoding of the Erlang external format you
+        must either:
+      </p>
+      <list type="bulleted">
+        <item>
+          <p>
+            Make sure your implementation supports the UTF-8 encodings
+            <seeguide marker="erts:erl_ext_dist#ATOM_UTF8_EXT">
+              <c>ATOM_UTF8_EXT</c></seeguide> and
+            <seeguide marker="erts:erl_ext_dist#SMALL_ATOM_UTF8_EXT">
+              <c>SMALL_ATOM_UTF8_EXT</c></seeguide>.
+          </p>
+        </item>
+        <item>
+          <p>
+            Call <seemfa marker="erts:erlang#term_to_binary/2">
+            <c>erlang:term_to_binary/2</c></seemfa> or
+            <seemfa marker="erts:erlang#term_to_iovec/2">
+            <c>erlang:term_to_iovec/2</c></seemfa>
+            with option <c>{minor_version,1}</c> to force Latin-1 encoding. This
+            is a more short-term solution as Latin-1 encoding may be phased out
+            and removed in later OTP releases.
+          </p>
+        </item>
+      </list>
+    </section>
+
   </section>
 </chapter>
-- 
2.31.1

Places

File 1241-doc-Document-UTF-8-as-default-atom-encoding-in-OTP-2.patch of Package erlang (Revision 3a70bf3d6fd4a5cb52eaedadd0de8996)

Places