Reword docs related to the runtime system mode

The existing wording may be interpreted as saying that embedded mode
eager loads all modules. This revision makes clear embedded mode only
disables module auto loading.

Since I was on it, I have reordered a couple of places to describe
interactive first, and then embedded. It feels natural to cover first
the default and positive mode (auto loads), and then its negation.

3 files changed, 18 insertions, 16 deletions

diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index bd824b3405..99f0421080 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -360,11 +360,12 @@
       </item>
       <tag><c><![CDATA[-mode interactive | embedded]]></c></tag>
       <item>
-        <p>Indicates if the system is to load code dynamically
-          (<c><![CDATA[interactive]]></c>), or if all code is to be loaded
-          during system initialization (<c><![CDATA[embedded]]></c>); see
-          <seealso marker="kernel:code"><c>code(3)</c></seealso>.
-          Defaults to <c><![CDATA[interactive]]></c>.</p>
+        <p>Modules are auto loaded when they are first referenced if the
+          runtime system runs in <c><![CDATA[interactive]]></c> mode, which is
+          the default. In <c><![CDATA[embedded]]></c> mode modules are not auto
+          loaded. The latter is recommended when the boot script preloads all
+          modules, as conventionally happens in OTP releases. See
+          <seealso marker="kernel:code"><c>code(3)</c></seealso></p>.
       </item>
       <tag><c><![CDATA[-name Name]]></c></tag>
       <item>
@@ -1693,4 +1694,3 @@ code:load_abs("..../user_default").    ]]></code>
       <seealso marker="tools:make"><c>make(3)</c></seealso></p>
   </section>
 </comref>
-
diff --git a/erts/preloaded/src/init.erl b/erts/preloaded/src/init.erl
index 679a2241d2..e0ae6b1656 100644
--- a/erts/preloaded/src/init.erl
+++ b/erts/preloaded/src/init.erl
@@ -32,8 +32,8 @@
 %%                         (Optional - default efile)
 %%        -hosts [Node]  : List of hosts from which we can boot.
 %%                         (Mandatory if -loader inet)
-%%        -mode embedded : Load all modules at startup, no automatic loading
-%%        -mode interactive : Auto load modules (default system behaviour).
+%%        -mode interactive : Auto load modules not needed at startup (default system behaviour).
+%%        -mode embedded : Load all modules in the boot script, disable auto loading.
 %%        -path          : Override path in bootfile.
 %%        -pa Path+      : Add my own paths first.
 %%        -pz Path+      : Add my own paths last.
diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml
index c94f612c01..bd95819636 100644
--- a/lib/kernel/doc/src/code.xml
+++ b/lib/kernel/doc/src/code.xml
@@ -34,26 +34,28 @@
     <p>This module contains the interface to the Erlang
       <em>code server</em>, which deals with the loading of compiled
       code into a running Erlang runtime system.</p>
-    <p>The runtime system can be started in <em>embedded</em> or
-      <em>interactive</em> mode. Which one is decided by command-line
+    <p>The runtime system can be started in <em>interactive</em> or
+      <em>embedded</em> mode. Which one is decided by the command-line
       flag <c>-mode</c>:</p>
     <pre>
 % <input>erl -mode interactive</input></pre>
     <p>The modes are as follows:</p>
     <list type="bulleted">
       <item>
-        <p>In embedded mode, all code is loaded during system startup
-          according to the boot script. (Code can also be loaded later
-          by explicitly ordering the code server to do so).</p>
-      </item>
-      <item>
         <p>In interactive mode, which is default, only some code is loaded
-	  during system startup, basically the modules needed by the runtime
+          during system startup, basically the modules needed by the runtime
           system. Other code is dynamically loaded when first
           referenced. When a call to a function in a certain module is
           made, and the module is not loaded, the code server searches
           for and tries to load the module.</p>
       </item>
+      <item>
+        <p>In embedded mode, modules are not auto loaded. Trying to use
+        a module that has not been loaded results in an error. This mode is
+        recommended when the boot script loads all modules, as it is
+        typically done in OTP releases. (Code can still be loaded later
+        by explicitly ordering the code server to do so).</p>
+      </item>
     </list>
     <p>To prevent accidentally reloading of modules affecting the Erlang
       runtime system, directories <c>kernel</c>, <c>stdlib</c>,