Update the documentation about the maybe feature

While at it, split the note about fun creator pid into two sections.

Closes #6950

2 files changed, 58 insertions, 4 deletions

diff --git a/system/doc/general_info/upcoming_incompatibilities.xml b/system/doc/general_info/upcoming_incompatibilities.xml
index 2fd70093b7..29108a7b0f 100644
--- a/system/doc/general_info/upcoming_incompatibilities.xml
+++ b/system/doc/general_info/upcoming_incompatibilities.xml
@@ -115,7 +115,7 @@
 
     <section>
       <marker id="fun_creator_pid"/>
-      <title>Fun creator pid will be removed</title>
+      <title>Fun creator pid will always be local init process</title>
       <p>
         As of OTP 27, the functions
         <seemfa marker="erts:erlang#fun_info/1">
@@ -124,7 +124,56 @@
         node the fun was originally created on.
       </p>
       <p>
-        In OTP 28, the <c>{pid,_}</c>element will be removed altogether.
+        In OTP 28, the <c>{pid,_}</c>element will be removed altogether.</p>
+    </section>
+
+    <section>
+      <title>Feature maybe_expr will be enabled by default</title>
+      <p>
+	As of OTP 27, the <c>maybe_expr</c> feature will be approved
+	and enabled by default. That means that code that uses the
+	unquoted atom <c>maybe</c> will fail to compile. All uses of
+	<c>maybe</c> as an atom will need to be quoted. Alternatively, as a
+	short-term solution, the <c>maybe_expr</c> feature can be
+	disabled.
+      </p>
+      <p>
+        It is recommend to quote all uses of the atom <c>maybe</c> as soon as
+        possible. The compiler option <c>warn_keywords</c> can be used to emit
+        warnings about all occurrences of <c>maybe</c> without quotes.
+      </p>
+    </section>
+  </section>
+
+  <section>
+    <title>OTP 28</title>
+
+    <section>
+      <marker id="fun_creator_pid"/>
+      <title>Fun creator pid will be removed</title>
+      <p>
+        As of OTP 28, the function <seemfa
+        marker="erts:erlang#fun_info/1"><c>erlang:fun_info/1</c></seemfa>
+        will no include the <c>{pid,_}</c> element and the function
+        <seemfa marker="erts:erlang#fun_info/2"><c>erlang:fun_info/2</c></seemfa>
+        will no longer accept <c>pid</c> as the second argument.</p>
+    </section>
+  </section>
+
+  <section>
+    <title>OTP 29</title>
+
+    <section>
+      <title>It will no longer be possible to disable feature maybe_expr</title>
+      <p>
+	As of OTP 29, the <c>maybe_expr</c> feature will become
+	permanent and no longer possible to disable. All uses of
+	<c>maybe</c> as an atom will need to be	quoted.
+      </p>
+      <p>
+        It is recommend to quote all uses of the atom <c>maybe</c> as soon as
+        possible. The compiler option <c>warn_keywords</c> can be used to emit
+        warnings about all occurrences of <c>maybe</c> without quotes.
       </p>
     </section>
   </section>
diff --git a/system/doc/reference_manual/introduction.xml b/system/doc/reference_manual/introduction.xml
index f823c6921b..d188ff8601 100644
--- a/system/doc/reference_manual/introduction.xml
+++ b/system/doc/reference_manual/introduction.xml
@@ -95,10 +95,15 @@
     <title>Reserved Words</title>
     <p>The following are reserved words in Erlang:</p>
     <p><c>after and andalso band begin bnot bor bsl bsr bxor case catch
-      cond div end fun if let not of or orelse receive rem try
+      cond div end fun if let maybe not of or orelse receive rem try
       when xor</c></p>
     <p><strong>Note</strong>: <c>cond</c> and <c>let</c>, while reserved,
-      are currently not used by the language.</p>
+    are currently not used by the language.</p>
+    <change><p><c>maybe</c> is a reserved word only if feature
+    <c>maybe_expr</c> is enabled. In Erlang/OTP 25 and 26,
+    <c>maybe_expr</c> is disabled by default. Starting from
+    Erlang/OTP 27, <c>maybe_expr</c> is enabled by
+    default.</p></change>
   </section>
 
 </chapter>