Merge pull request #6894 from bjorng/bjorn/doc/ref-manual-changes

Reference Manual: Use the change tag for clarity

13 files changed, 181 insertions, 156 deletions

diff --git a/system/doc/reference_manual/character_set.xml b/system/doc/reference_manual/character_set.xml
index 6d37700da3..ec8e8c2c52 100644
--- a/system/doc/reference_manual/character_set.xml
+++ b/system/doc/reference_manual/character_set.xml
@@ -41,7 +41,7 @@
           shown without the escape backslash convention.</p>
       </item>
       <item>
-        <p>Atoms and variables can use all Latin-1 letters.</p>
+        <p>Unquoted atoms and variables can use all Latin-1 letters.</p>
       </item>
     </list>
     <table>
@@ -101,17 +101,35 @@
       </row>
       <tcaption>Character Classes</tcaption>
     </table>
-    <p>In Erlang/OTP R16B the syntax of Erlang tokens was extended to
-       handle Unicode. The support was limited to
-       string literals and comments.
-       More about the usage of Unicode in Erlang source files
-       can be found in <seeguide
-       marker="stdlib:unicode_usage#unicode_in_erlang">STDLIB's User's
-       Guide</seeguide>.</p>
-       <p>From Erlang/OTP 20, atoms and function names are also allowed
-       to contain Unicode characters outside the ISO-Latin-1 range.
-       Module names, application names, and node names are still
-       restricted to the ISO-Latin-1 range.</p>
+
+    <p>The following tokens are allowed to also use Unicode characters
+    outside of the Latin-1 range:</p>
+
+    <list type="bulleted">
+      <item>
+        <p>String literals. Example: <c>"√π"</c></p>
+      </item>
+      <item>
+        <p>Character literals. Example: <c>$∑</c></p>
+      </item>
+      <item>
+        <p>Comments in code.</p>
+      </item>
+      <item>
+        <p>Quoted atoms. Example: <c>'μs'</c></p>
+      </item>
+      <item>
+        <p>Function names. Example: <c>'s_to_μs'(S) -> S * 1_000_000.</c></p>
+      </item>
+    </list>
+
+    <p>Atoms used as module names, application names, and node names are
+    restricted to the Latin-1 range.</p>
+
+    <change><p>Support for Unicode in string literals, character literals,
+    and comments was introduced in Erlang/OTP R16B. Support for Unicode in
+    atom and function names was introduced in Erlang/OTP 20.</p>
+    </change>
   </section>
   <section>
     <title>Source File Encoding</title>
@@ -123,15 +141,17 @@
       the matching string is an invalid encoding, it is ignored. The
       valid encodings are <c>Latin-1</c> and <c>UTF-8</c>, where the
       case of the characters can be chosen freely.</p>
-    <p>The following example selects UTF-8 as default encoding:</p>
-      <pre>
-%% coding: utf-8</pre>
-    <p>Two more examples, both selecting Latin-1 as default encoding:</p>
+
+      <p>The default Erlang source file encoding if no valid
+      <c>coding</c> comment is present is UTF-8.</p>
+
+    <p>Two examples, both selecting Latin-1 as the source file encoding:</p>
       <pre>
 %% For this file we have chosen encoding = Latin-1</pre>
       <pre>
 %% -*- coding: latin-1 -*-</pre>
-    <p>The default encoding for Erlang source files is changed from
-      Latin-1 to UTF-8 since Erlang/OTP 17.0.</p>
+
+     <change><p>The default encoding for Erlang source files was changed from
+     Latin-1 to UTF-8 in Erlang/OTP 17.0.</p></change>
   </section>
 </chapter>
diff --git a/system/doc/reference_manual/code_loading.xml b/system/doc/reference_manual/code_loading.xml
index b64b2eecf9..c43f92ea31 100644
--- a/system/doc/reference_manual/code_loading.xml
+++ b/system/doc/reference_manual/code_loading.xml
@@ -157,12 +157,12 @@ loop() ->
     before the <c>on_load</c> function has finished will be suspended
     until the <c>on_load</c> function have finished.</p>
 
-    <note>
-      <p>Before OTP 19, if the <c>on_load</c> function failed, any
+    <change>
+      <p>Before Erlang/OTP 19, if the <c>on_load</c> function failed, any
       previously current code would become old, essentially leaving
       the system without any working and reachable instance of the
-      module.  That problem has been eliminated in OTP 19.</p>
-    </note>
+      module.</p>
+    </change>
 
     <p>In embedded mode, first all modules are loaded.
       Then all <c>on_load</c> functions are called. The system is
diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml
index b8e2f5d7d5..206f7c8a4a 100644
--- a/system/doc/reference_manual/data_types.xml
+++ b/system/doc/reference_manual/data_types.xml
@@ -305,9 +305,10 @@ adam
       in STDLIB.</p>
     <p>Read more about maps in <seeguide marker="expressions#map_expressions">
       Map Expressions</seeguide>.</p>
-  <note>
-    <p>Maps are considered to be experimental during Erlang/OTP R17.</p>
-  </note>
+  <change>
+    <p>Maps were introduced as an experimental feature in Erlang/OTP R17. Their
+    functionality was extended and became fully supported in Erlang/OTP 18.</p>
+  </change>
   </section>
 
   <section>
@@ -520,10 +521,10 @@ true</pre>
     </table>
 
 
-    <note><p>As of Erlang/OTP 26, the value of <c>$\^?</c> has been
+    <change><p>As of Erlang/OTP 26, the value of <c>$\^?</c> has been
     changed to be 127 (Delete), instead of 31. Previous releases
     would allow any character following <c>$\^</c>; as of Erlang/OTP
-    26, only the documented characters are allowed.</p></note>
+    26, only the documented characters are allowed.</p></change>
   </section>
 
   <section>
diff --git a/system/doc/reference_manual/distributed.xml b/system/doc/reference_manual/distributed.xml
index f8fb159be3..6e4c28d3e2 100644
--- a/system/doc/reference_manual/distributed.xml
+++ b/system/doc/reference_manual/distributed.xml
@@ -167,14 +167,14 @@ dilbert@uab</pre>
        can be made to get a new dynamic node name. The node name may
        change if the distribution is dropped and then set up again.
      </p>
-     <note>
+     <change>
        <p>
-	 The <em>dynamic node name</em> feature is supported from OTP 23.
+	 The <em>dynamic node name</em> feature is supported from Erlang/OTP 23.
          Both the temporary client node and the first connected peer node
-         (supplying the dynamic node name) must be at least OTP 23 for it to
+         (supplying the dynamic node name) must be at least Erlang/OTP 23 for it to
          work.
        </p>
-     </note>
+     </change>
   </section>
 
   <section>
diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index deb9362388..8f0ec51479 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -376,13 +376,13 @@ spawn(m, init, [])</code>
     being auto-imported. In certain situations, such a compile-directive
     is mandatory.</p>
 
-    <warning><p>Before OTP R14A (ERTS version 5.8), an implicitly
+    <change><p>Before OTP R14A (ERTS version 5.8), an implicitly
     qualified function call to a function having the same name as an
     auto-imported BIF always resulted in the BIF being called. In
     newer versions of the compiler, the local function is called instead.
     This is to avoid that future additions to the
     set of auto-imported BIFs do not silently change the behavior
-    of old code.</p>
+    of old code.</p></change>
 
     <p>However, to avoid that old (pre R14) code changed its
     behavior when compiled with OTP version R14A or later, the
@@ -392,7 +392,7 @@ spawn(m, init, [])</code>
     your code, you either need to explicitly remove the auto-import
     using a compiler directive, or replace the call with a fully
     qualified function call. Otherwise you get a compilation
-    error. See the following example:</p> </warning>
+    error. See the following example:</p>
 
     <code type="none">
 -export([length/1,f/1]).
@@ -505,13 +505,13 @@ is_valid_signal(Signal) ->
   <section>
     <marker id="maybe"></marker>
     <title>Maybe</title>
-    <note><p><c>maybe</c> is an experimental new <seeguide
+    <change><p><c>maybe</c> is an experimental <seeguide
     marker="system/reference_manual:features#features">feature</seeguide>
-    introduced in OTP 25. By default, it is disabled. To enable
+    introduced in Erlang/OTP 25. By default, it is disabled. To enable
     <c>maybe</c>, either use the <c>-feature(maybe_expr,enable)</c>
     directive (from within source code), or the compiler option
     <c>{feature,maybe_expr,enable}</c>.</p>
-    </note>
+    </change>
 
     <code type="erl"><![CDATA[
 maybe
@@ -1044,16 +1044,21 @@ case A >= -1.0 andalso math:sqrt(A+1) > B of</pre>
 OnlyOne = is_atom(L) orelse
          (is_list(L) andalso length(L) == 1),</pre>
 
-    <p>From Erlang/OTP R13A, <c>Expr2</c> is no longer required to evaluate to a
-    Boolean value. As a consequence, <c>andalso</c> and <c>orelse</c>
-    are now tail-recursive.  For instance, the following function is
-    tail-recursive in Erlang/OTP R13A and later:</p>
+    <p><c>Expr2</c> is not required to evaluate to a Boolean
+    value. Because of that, <c>andalso</c> and <c>orelse</c> are
+    tail-recursive.</p>
 
+    <p><em>Example 3 (tail-recursive function):</em></p>
     <pre>
 all(Pred, [Hd|Tail]) ->
     Pred(Hd) andalso all(Pred, Tail);
 all(_, []) ->
     true.</pre>
+
+    <change><p>Before Erlang/OTP R13A, <c>Expr2</c> was required to
+    evaluate to a Boolean value, and as consequence, <c>andalso</c>
+    and <c>orelse</c> were <strong>not</strong>
+    tail-recursive.</p></change>
   </section>
 
   <section>
@@ -1233,9 +1238,9 @@ M4 = M3#{a := 2, b := 3}.  % 'a' and 'b' was added in `M1` and `M2`.</code>
 		  with the key <c>K</c>, which must exist in the map <c>M</c>. If the variable
 		  <c>V</c> is bound, it must match the value associated with <c>K</c> in <c>M</c>.
 	  </p>
-	  <note><p>Before OTP 23, the expression defining the key
+	  <change><p>Before Erlang/OTP 23, the expression defining the key
 	  <c>K</c> was restricted to be either a single variable or a
-	  literal.</p></note>
+	  literal.</p></change>
 	  <p><em>Example:</em></p>
 <pre>
 1> <input>M = #{"tuple" => {1,2}}.</input>
@@ -1373,8 +1378,8 @@ Ei = Value |
     that evaluates to an integer. All variables in the guard expression
     must be already bound.</p>
 
-    <note><p>Before OTP 23, <c>Size</c> was restricted to be an
-    integer or a variable bound to an integer.</p></note>
+    <change><p>Before Erlang/OTP 23, <c>Size</c> was restricted to be an
+    integer or a variable bound to an integer.</p></change>
 
     <p>The value of <c>Size</c> specifies the size of the segment in
     units (see below). The default value depends on the type (see
@@ -1555,14 +1560,15 @@ fun Module:Name/Arity</pre>
       syntactic sugar for:</p>
     <pre>
 fun (Arg1,...,ArgN) -> Name(Arg1,...,ArgN) end</pre>
-    <p>In <c>Module:Name/Arity</c>, <c>Module</c>, and <c>Name</c> are atoms
-      and <c>Arity</c> is an integer. Starting from Erlang/OTP R15,
-      <c>Module</c>, <c>Name</c>, and <c>Arity</c> can also be variables.
-      A fun defined in this way refers to the function <c>Name</c>
-      with arity <c>Arity</c> in the <em>latest</em> version of module
-      <c>Module</c>. A fun defined in this way is not dependent on
-      the code for the module in which it is defined.
-      </p>
+    <p>In <c>Module:Name/Arity</c>, <c>Module</c>, and <c>Name</c> are
+    atoms and <c>Arity</c> is an integer. <c>Module</c>, <c>Name</c>,
+    and <c>Arity</c> can also be variables. A fun defined in this way
+    refers to the function <c>Name</c> with arity <c>Arity</c> in the
+    <em>latest</em> version of module <c>Module</c>. A fun defined in
+    this way is not dependent on the code for the module in which it
+    is defined.</p>
+    <change><p>Before Erlang/OTP R15, <c>Module</c>, <c>Name</c>, and <c>Arity</c> were
+    not allowed to be variables.</p></change>
     <p>More examples are provided in
       <seeguide marker="system/programming_examples:funs">
       Programming Examples</seeguide>.</p>
diff --git a/system/doc/reference_manual/features.xml b/system/doc/reference_manual/features.xml
index 882cdd2582..3beae96ba3 100644
--- a/system/doc/reference_manual/features.xml
+++ b/system/doc/reference_manual/features.xml
@@ -150,19 +150,13 @@
       enable|disable)</c></seeguide> directive.  This is the preferred
       method of enabling and disabling features.</item>
     </taglist>
-    <p>
-      Note that to load a module compiled with features enabled, the
-      corresponding features must be enabled in the runtime.  This
-      is done using options <seecom
-      marker="erts:erl#enable-feature"><c>-enable-feature</c></seecom>
-      and <seecom
-      marker="erts:erl#disable-feature"><c>-disable-feature</c></seecom>
-      to <c>erl</c>.  This is to allow the possibility to prevent
-      the use of experimental features in, e.g., production.  This
-      will catch experimental features used in both own and third
-      party components.  An active choice to use experimental
-      features must be done.
-    </p>
+    <change>
+      <p>In Erlang/OTP 25, in order to load a module with a feature
+      enabled, it was necessary to also enable the feature in the runtime.
+      This was done using option <seecom
+      marker="erts:erl#enable-feature"><c>-enable-feature</c></seecom> to
+      <c>erl</c>. This requirement was removed in Erlang/OTP 26.</p>
+    </change>
   </section>
 
   <section>
diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml
index e54e0e1d30..2ebd23f23b 100644
--- a/system/doc/reference_manual/macros.xml
+++ b/system/doc/reference_manual/macros.xml
@@ -155,18 +155,20 @@ bar(X) ->
       <item>The OTP release that the currently executing ERTS
         application is part of, as an integer. For details, see
         <seemfa marker="erts:erlang#system_info/1"><c>erlang:system_info(otp_release)</c></seemfa>.
-        This macro was introduced in OTP release 21.</item>
+        <change><p>The <c>?OTP_RELEASE</c> macro was introduced in Erlang/OTP 21.</p></change></item>
         <tag><c>?FEATURE_AVAILABLE(Feature)</c></tag>
         <item>Expands to <c>true</c> if the <seeguide
         marker="system/reference_manual:features#features">feature</seeguide>
         <c>Feature</c> is available.  The feature might or might not
-        be enabled.  This macro was introduced with OTP release
-        25.</item>
+        be enabled.
+        <change><p>The <c>?FEATURE_AVAILABLE()</c> macro was introduced in Erlang/OTP 25.</p></change>
+        </item>
         <tag><c>?FEATURE_ENABLED(Feature)</c></tag>
         <item>Expands to <c>true</c> if the <seeguide
         marker="system/reference_manual:features#features">feature</seeguide>
-        <c>Feature</c> is enabled.  This macro was introduced with OTP
-        release 25.</item>
+        <c>Feature</c> is enabled.
+        <change><p>The <c>?FEATURE_ENABLED()</c> macro was introduced in Erlang/OTP 25.</p></change>
+        </item>
     </taglist>
   </section>
 
@@ -175,7 +177,8 @@ bar(X) ->
     <p>It is possible to overload macros, except for predefined
       macros. An overloaded macro has more than one definition,
       each with a different number of arguments.</p>
-    <p>The feature was added in Erlang 5.7.5/OTP R13B04.</p>
+      <change><p>Support for overloading of macros was added in Erlang
+      5.7.5/OTP R13B04.</p></change>
     <p>A macro <c>?Func(Arg1,...,ArgN)</c> with a (possibly empty)
       list of arguments results in an error message if there is at
       least one definition of <c>Func</c> with arguments, but none
@@ -339,8 +342,8 @@ version() -> ?VERSION.</code>
 % <input>erlc t.erl</input>
 t.erl:5: Warning: -warning("Macro VERSION not defined -- using default version.").</pre>
 
-  <p>The <c>-error()</c> and <c>-warning()</c> directives were added
-  in OTP 19.</p>
+  <change><p>The <c>-error()</c> and <c>-warning()</c> directives were added
+  in Erlang/OTP 19.</p></change>
 
   </section>
 
diff --git a/system/doc/reference_manual/modules.xml b/system/doc/reference_manual/modules.xml
index 63ccf1ee95..3b888f2e1e 100644
--- a/system/doc/reference_manual/modules.xml
+++ b/system/doc/reference_manual/modules.xml
@@ -141,24 +141,23 @@ fact(0) ->           %  |
             <c>[Name1/Arity1, ..., NameN/ArityN]</c>, where each
             <c>NameI</c> is an atom and <c>ArityI</c> an integer.
           </p>
-          <note>
-            <p>
-              The <c>-nifs()</c> attribute was introduced in OTP 25.0. For older
-              Erlang source code without it, any functions in the module may be
-              loaded as NIFs. However, it is recommended to declare the NIFs with
-              the <c>-nifs</c> attribute. This allows the compiler to make better
-              decisions regarding optimizations for example.
-            </p>
+          <p>While not strictly necessary, it is recommended to use <c>-nifs()</c>
+          attribute in any module that load NIFs, to allow the compiler to make
+          better decisions regarding optimizations.</p>
+          <p>There is no need to add <c>-nifs([])</c> in modules that do not
+          load NIFs. The lack of any call to
+          <seemfa marker="erts:erlang#load_nif/2"><c>erlang:load_nif/2</c></seemfa>,
+          from within the module, is enough for the compiler to draw the
+          same conclusion.
+          </p>
+          <change>
             <p>
-              There is no need to add <c>-nifs([])</c> in modules that do not
-              load NIFs. The lack of any call to
-              <seemfa marker="erts:erlang#load_nif/2"><c>erlang:load_nif/2</c></seemfa>,
-              from within the module, is enough for the compiler to draw the
-              same conclusion.
+              The special meaning for the <c>-nifs()</c> attribute was
+              introduced in Erlang/OTP 25.0. In previous releases, the
+              <c>-nifs()</c> was accepted, but had no special meaning.
             </p>
-          </note>
+          </change>
         </item>
-
       </taglist>
     </section>
 
diff --git a/system/doc/reference_manual/opaques.xml b/system/doc/reference_manual/opaques.xml
index 8fa3bae3e5..ad71ed111c 100644
--- a/system/doc/reference_manual/opaques.xml
+++ b/system/doc/reference_manual/opaques.xml
@@ -33,28 +33,30 @@
 
   <section>
     <title>Opaque Type Aliases</title>
-    <p>The main use case for opacity in Erlang is to hide the implementation of a data type, enabling evolving the API while minimizing the risk of breaking consumers. The runtime does not check opacity. Dialyzer provides some opacity-checking, but the rest is up to convention.
+    <p>The main use case for opacity in Erlang is to hide the
+    implementation of a data type, enabling evolving the API while
+    minimizing the risk of breaking consumers. The runtime does not
+    check opacity. Dialyzer provides some opacity-checking, but the
+    rest is up to convention.
     </p>
     <p>
-      This document explains what Erlang opacity is (and the trade-offs involved) via the example of OTP's
-      <c>sets:set()</c>
-      data type. This type
-      <em>was</em>
-      defined in `sets` module like this:
+      This document explains what Erlang opacity is (and the
+      trade-offs involved) via the example of the <c>sets:set()</c>
+      data type. This type <em>was</em> defined in the <c>sets</c>
+      module like this:
     </p>
     <code type="erl">-opaque set(Element) :: #set{segs :: segs(Element)}.</code>
-    <p>OTP 24  changed the definition to the following, in
-    <url href="https://github.com/erlang/otp/commit/e66941e8d7c47b973dff94c0308ea85a6be1958e">this commit</url>
+    <p>OTP 24  changed the definition to the following in
+    <url href="https://github.com/erlang/otp/commit/e66941e8d7c47b973dff94c0308ea85a6be1958e">this commit</url>.
     </p>
     <code type="erl">-opaque set(Element) :: #set{segs :: segs(Element)} | #{Element => ?VALUE}.</code>
     <p>
-      And this change was safer and more backwards-compatible than if the type had been defined with
-      <c>-type</c>
-      instead of
-      <c>-opaque</c>
-      . Here's why: when a module defines an
-      <c>-opaque</c>
-      , the contract is that only the defining module should rely on the definition of the type: no other modules should rely on the definition.
+      And this change was safer and more backwards-compatible than if
+      the type had been defined with <c>-type</c> instead of
+      <c>-opaque</c>.  Here is why: when a module defines an
+      <c>-opaque</c>, the contract is that only the defining module
+      should rely on the definition of the type: no other modules
+      should rely on the definition.
     </p>
     <p>
       This means that code that pattern-matched on
@@ -62,8 +64,8 @@
       as a record/tuple technically broke the contract, and opted in to being potentially broken when the definition of
       <c>set()</c>
       changed. Before OTP 24, this code printed
-      <c>ok</c>
-      . In OTP 24 it may error:
+      <c>ok</c>.
+      In OTP 24 it may error:
     </p>
     <code type="erl">
 case sets:new() of
@@ -85,12 +87,9 @@ end.
         Instead, use functions provided by the module for working with the type. For example,
         <c>sets</c>
         module provides
-        <c>sets:new/0</c>
-        ,
-        <c>sets:add/2</c>
-        ,
-        <c>sets:is_element/2</c>
-        , etc.
+        <c>sets:new/0</c>,
+        <c>sets:add/2</c>,
+        <c>sets:is_element/2</c>, and so on.
       </item>
       <item>
         <c>sets:set(a)</c>
@@ -108,34 +107,40 @@ end.
     </p>
     <list type="bulleted">
       <item>
-        Since consumers are expected to not rely on the definition of the opaque type, you must provide functions for constructing and querying/deconstructing intances of your opaque type. For example, sets can be constructed with
-        <c>sets:new/0</c>, <c>sets:from_list/1</c>, <c>sets:add/2</c>, queried with <c>sets:is_element/2</c>, and deconstructed with<c>sets:to_list/1</c>.
+        Since consumers are expected to not rely on the definition of
+        the opaque type, you must provide functions for constructing,
+        querying, and deconstructing instances of your opaque type. For
+        example, sets can be constructed with <c>sets:new/0</c>,
+        <c>sets:from_list/1</c>, <c>sets:add/2</c>, queried with
+        <c>sets:is_element/2</c>, and deconstructed
+        with<c>sets:to_list/1</c>.
       </item>
       <item>
-        Don't define an opaque with a type variable in parameter position. This breaks the normal and expected behavior that (for example)
-        <c>my_type(a)</c> is a subtype of <c>my_type(a | b)</c>
+        Don't define an opaque with a type variable in parameter
+        position. This breaks the normal and expected behavior that
+        (for example) <c>my_type(a)</c> is a subtype of <c>my_type(a |
+        b)</c>
       </item>
       <item>
         Add <seeguide marker="typespec">specs</seeguide> to exported functions that use the opaque type
       </item>
     </list>
-    <p>Note that opaques can be harder to work with for consumers, since the consumer is expected not to pattern-match and must instead use functions that the author of the opaque type provides to use instances of the type.</p>
+    <p>Note that opaques can be harder to work with for consumers,
+    since the consumer is expected not to pattern-match and must
+    instead use functions that the author of the opaque type provides
+    to use instances of the type.</p>
     <p>
-      Also, opacity in Erlang is skin-deep: the runtime does not enforce opacity-checking. So now that sets are implemented in terms of maps, an
-      <c>is_map</c>
-      check on a set
-      <em>will</em>
-      pass. The opacity rules are only enforced by convention and by additional tooling such as Dialyzer. And this enforcement is not total: For example, determined consumer of
-      <c>sets</c>
-      can still do things that reveal the structure of the set, such as by printing, serializing, or using a set as
-      <c>term()</c>
-      and then inspecting via functions like
-      <c>is_map</c>
-      or
-      <c>maps:get/2</c>
-      . And Dialyzer must make some
-      <url href="https://github.com/erlang/otp/issues/5118">approximations</url>
-      . Opacity checking has limitations, but is still a vital tool in scalable Erlang development.
+      Also, opacity in Erlang is skin-deep: the runtime does not
+      enforce opacity-checking. So now that sets are implemented in
+      terms of maps, an <c>is_map/1</c> check on a set <em>will</em>
+      pass. The opacity rules are only enforced by convention and by
+      additional tooling such as Dialyzer, and this enforcement is not
+      total. A determined consumer of <c>sets</c> can still reveal the
+      structure of the set, for example by printing, serializing, or
+      using a set as a <c>term()</c> and inspecting it via functions
+      like <c>is_map/1</c> or <c>maps:get/2</c>. Also, Dialyzer must make
+      some <url
+      href="https://github.com/erlang/otp/issues/5118">approximations</url>.
     </p>
   </section>
 </chapter>
diff --git a/system/doc/reference_manual/ports.xml b/system/doc/reference_manual/ports.xml
index 26ecc084c5..3da54b2018 100644
--- a/system/doc/reference_manual/ports.xml
+++ b/system/doc/reference_manual/ports.xml
@@ -103,12 +103,9 @@
       <c>Port</c> by sending and receiving messages. (In fact, any
       process can send the messages to the port, but the port owner must
       be identified in the message).</p>
-    <p>As of Erlang/OTP R16, messages sent to ports are delivered truly
-      asynchronously. The underlying implementation previously
-      delivered messages to ports synchronously. Message passing has
-      however always been documented as an asynchronous operation. Hence,
-      this is not to be an issue for an Erlang program communicating
-      with ports, unless false assumptions about ports have been made.</p>
+      <p>Messages sent to ports are delivered asynchronously.</p>
+      <change><p>Before Erlang/OTP 16, messages to ports were
+      delivered synchronously.</p></change>
     <p>In the following tables of examples, <c>Data</c> must be an I/O list.
       An I/O list is a binary or a (possibly deep) list of binaries
       or integers in the range 0..255:</p>
diff --git a/system/doc/reference_manual/processes.xml b/system/doc/reference_manual/processes.xml
index 7e9323cfc2..afc1215eaf 100644
--- a/system/doc/reference_manual/processes.xml
+++ b/system/doc/reference_manual/processes.xml
@@ -700,13 +700,14 @@ spawn(Module, Name, Args) -> pid()
 	    <seecom marker="erts:erl#+zdbbl"><c>+zdbbl</c></seecom>. Note
 	    that if you do raise the limit like this, you need to take care
 	    of flow control yourself to ensure that you do not get into a
-	    situation with excessive memory usage. As of OTP @OTP-18454@ it is
+	  situation with excessive memory usage.</p>
+          <change><p>As of OTP @OTP-18454@ it is
             also possible to enable <i>fully asynchronous distributed
             signaling</i> on a per process level using
             <seeerl marker="erts:erlang#process_flag_async_dist">
               <c>process_flag(async_dist, Bool)</c></seeerl>. Also in this case
             you need to take care of flow control yourself.
-	  </p>
+	  </p></change>
 	</item>
       </taglist>
       <p>
diff --git a/system/doc/reference_manual/records.xml b/system/doc/reference_manual/records.xml
index d5712bded0..14cf781417 100644
--- a/system/doc/reference_manual/records.xml
+++ b/system/doc/reference_manual/records.xml
@@ -151,25 +151,23 @@ is_person(_P) ->
 
   <section>
     <title>Nested Records</title>
-    <p>Beginning with Erlang/OTP R14, parentheses when accessing or updating nested
-      records can be omitted. Assume the following record
-      definitions:</p>
+    <p>Assume the following record definitions:</p>
     <pre>
 -record(nrec0, {name = "nested0"}).
 -record(nrec1, {name = "nested1", nrec0=#nrec0{}}).
 -record(nrec2, {name = "nested2", nrec1=#nrec1{}}).
 
-N2 = #nrec2{},
-    </pre>
-    <p>Before R14, parentheses were needed as follows:</p>
-    <pre>
-"nested0" = ((N2#nrec2.nrec1)#nrec1.nrec0)#nrec0.name,
-N0n = ((N2#nrec2.nrec1)#nrec1.nrec0)#nrec0{name = "nested0a"},
-    </pre>
-    <p>Since R14, the following can also be written:</p>
+N2 = #nrec2{},</pre>
+    <p>Accessing or updating nested records can be written without parentheses:</p>
     <pre>
 "nested0" = N2#nrec2.nrec1#nrec1.nrec0#nrec0.name,
-N0n = N2#nrec2.nrec1#nrec1.nrec0#nrec0{name = "nested0a"},</pre>
+    N0n = N2#nrec2.nrec1#nrec1.nrec0#nrec0{name = "nested0a"},</pre>
+    <p>which is equivalent to:</p>
+    <pre>
+"nested0" = ((N2#nrec2.nrec1)#nrec1.nrec0)#nrec0.name,
+N0n = ((N2#nrec2.nrec1)#nrec1.nrec0)#nrec0{name = "nested0a"},</pre>
+    <change><p>Before Erlang/OTP R14, parentheses were necessary when accessing or updating nested
+    records.</p></change>
   </section>
 
   <section>
diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml
index fbcc3315a7..e4b9c4f62c 100644
--- a/system/doc/reference_manual/typespec.xml
+++ b/system/doc/reference_manual/typespec.xml
@@ -343,9 +343,10 @@
 
   <section>
     <title>Redefining built-in types</title>
-    <p>
+    <change><p>
       Starting from Erlang/OTP 26, is is permitted to define a type
-      having the same name as a built-in type. It is recommended to
+      having the same name as a built-in type.</p></change>
+      <p>It is recommended to
       avoid deliberately reusing built-in names because it can be
       confusing. However, when an Erlang/OTP release introduces a new
       type, code that happened to define its own type having the same
@@ -463,7 +464,7 @@
       This is checked by the compiler and results in a compilation error
       if a violation is detected.
     </p>
-    <note>
+    <change>
       <p>Before Erlang/OTP 19, for fields without initial values,
       the singleton type <c>'undefined'</c> was added to all declared types.
       In other words, the following two record declarations had identical
@@ -480,7 +481,7 @@
       This is no longer the case. If you require <c>'undefined'</c> in your record field
       type, you must explicitly add it to the typespec, as in the 2nd example.
     </p>
-    </note>
+    </change>
     <p>
       Any record, containing type information or not, once defined,
       can be used as a type using the following syntax: