erts: Editorial changes

1 files changed, 125 insertions, 101 deletions

diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml
index a88a815ef6..54507c6572 100644
--- a/erts/doc/src/init.xml
+++ b/erts/doc/src/init.xml
@@ -19,7 +19,7 @@
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.
-    
+
     </legalnotice>
 
     <title>init</title>
@@ -30,128 +30,140 @@
     <file>init.xml</file>
   </header>
   <module>init</module>
-  <modulesummary>Coordination of System Startup</modulesummary>
+  <modulesummary>Coordination of system startup.</modulesummary>
   <description>
-    <p>The <c>init</c> module is pre-loaded and contains the code for
-      the <c>init</c> system process which coordinates the start-up of
-      the system. The first function evaluated at start-up is
-      <c>boot(BootArgs)</c>, where <c>BootArgs</c> is a list of command
-      line arguments supplied to the Erlang runtime system from
-      the local operating system. See
-      <seealso marker="erts:erl">erl(1)</seealso>.</p>
-    <p><c>init</c> reads the boot script which contains instructions on
-      how to initiate the system. See
-      <seealso marker="sasl:script">script(4)</seealso> for more
-      information about boot scripts.</p>
+    <p>This module is preloaded and contains the code for
+      the <c>init</c> system process that coordinates the startup of
+      the system. The first function evaluated at startup is
+      <c>boot(BootArgs)</c>, where <c>BootArgs</c> is a list of
+      command-line arguments supplied to the Erlang runtime system from
+      the local operating system; see
+      <seealso marker="erts:erl"><c>erl(1)</c></seealso>.</p>
+
+    <p><c>init</c> reads the boot script, which contains instructions on
+      how to initiate the system. For more information about boot scripts, see
+      <seealso marker="sasl:script"><c>sasl:script(4)</c></seealso>.</p>
+
     <p><c>init</c> also contains functions to restart, reboot, and stop
       the system.</p>
   </description>
+
   <funcs>
     <func>
       <name name="boot" arity="1"/>
-      <fsummary>Start the Erlang runtime system</fsummary>
+      <fsummary>Start the Erlang runtime system.</fsummary>
       <desc>
         <p>Starts the Erlang runtime system. This function is called
-          when the emulator is started and coordinates system start-up.</p>
-        <p><c><anno>BootArgs</anno></c> are all command line arguments except
-          the emulator flags, that is, flags and plain arguments. See
-          <seealso marker="erts:erl">erl(1)</seealso>.</p>
-        <p><c>init</c> itself interprets some of the flags, see
-          <seealso marker="#flags">Command Line Flags</seealso> below.
+          when the emulator is started and coordinates system startup.</p>
+        <p><c><anno>BootArgs</anno></c> are all command-line arguments except
+          the emulator flags, that is, flags and plain arguments; see
+          <seealso marker="erts:erl"><c>erl(1)</c></seealso>.</p>
+        <p><c>init</c> interprets some of the flags, see section
+          <seealso marker="#flags">Command-Line Flags</seealso> below.
           The remaining flags ("user flags") and plain arguments are
           passed to the <c>init</c> loop and can be retrieved by calling
-          <c>get_arguments/0</c> and <c>get_plain_arguments/0</c>,
-          respectively.</p>
+          <seealso marker="#get_arguments/0"><c>get_arguments/0</c></seealso>
+          and <seealso marker="#get_plain_arguments/0">
+          <c>get_plain_arguments/0</c></seealso>, respectively.</p>
       </desc>
     </func>
+
     <func>
       <name name="get_argument" arity="1"/>
-      <fsummary>Get the values associated with a command line user flag</fsummary>
+      <fsummary>Get the values associated with a command-line user flag.
+      </fsummary>
       <desc>
-        <p>Returns all values associated with the command line user flag
-          <c><anno>Flag</anno></c>. If <c><anno>Flag</anno></c> is provided several times, each
-          <c><anno>Values</anno></c> is returned in preserved order.</p>
+        <p>Returns all values associated with the command-line user flag
+          <c><anno>Flag</anno></c>. If <c><anno>Flag</anno></c> is provided
+          several times, each <c><anno>Values</anno></c> is returned in
+          preserved order. Example:</p>
         <pre>
 % <input>erl -a b c -a d</input>
 ...
 1> <input>init:get_argument(a).</input>
 {ok,[["b","c"],["d"]]}</pre>
-        <p>There are also a number of flags, which are defined
+        <p>The following flags are defined
           automatically and can be retrieved using this function:</p>
         <taglist>
           <tag><c>root</c></tag>
           <item>
-            <p>The installation directory of Erlang/OTP, <c>$ROOT</c>.</p>
+            <p>The installation directory of Erlang/OTP, <c>$ROOT</c>:</p>
             <pre>
 2> <input>init:get_argument(root).</input>
 {ok,[["/usr/local/otp/releases/otp_beam_solaris8_r10b_patched"]]}</pre>
           </item>
           <tag><c>progname</c></tag>
           <item>
-            <p>The name of the program which started Erlang.</p>
+            <p>The name of the program which started Erlang:</p>
             <pre>
 3> <input>init:get_argument(progname).</input>
 {ok,[["erl"]]}</pre>
           </item>
           <tag><c>home</c></tag>
           <item>
-            <p>The home directory.</p>
+            <p>The home directory:</p>
             <pre>
 4> <input>init:get_argument(home).</input>
 {ok,[["/home/harry"]]}</pre>
           </item>
         </taglist>
-        <p>Returns <c>error</c> if there is no value associated with
-          <c>Flag</c>.</p>
+        <p>Returns <c>error</c> if no value is associated with <c>Flag</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="get_arguments" arity="0"/>
-      <fsummary>Get all command line user flags</fsummary>
+      <fsummary>Get all command-line user flags.</fsummary>
       <desc>
-        <p>Returns all command line flags, as well as the system
-          defined flags, see <c>get_argument/1</c>.</p>
+        <p>Returns all command-line flags and the system-defined flags, see
+          <seealso marker="#get_argument/1"><c>get_argument/1</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
       <name name="get_plain_arguments" arity="0"/>
-      <fsummary>Get all non-flag command line arguments</fsummary>
+      <fsummary>Get all non-flag command-line arguments.</fsummary>
       <desc>
-        <p>Returns any plain command line arguments as a list of strings
+        <p>Returns any plain command-line arguments as a list of strings
           (possibly empty).</p>
       </desc>
     </func>
+
     <func>
       <name name="get_status" arity="0"/>
-      <fsummary>Get system status information</fsummary>
+      <fsummary>Get system status information.</fsummary>
       <type name="internal_status"/>
       <desc>
         <p>The current status of the <c>init</c> process can be
           inspected. During system startup (initialization),
           <c><anno>InternalStatus</anno></c> is <c>starting</c>, and
-          <c><anno>ProvidedStatus</anno></c> indicates how far the boot script has
-          been interpreted. Each <c>{progress, Info}</c> term
-          interpreted in the boot script affects <c><anno>ProvidedStatus</anno></c>,
-          that is, <c><anno>ProvidedStatus</anno></c> gets the value of <c>Info</c>.</p>
+          <c><anno>ProvidedStatus</anno></c> indicates how far the boot
+          script has been interpreted. Each <c>{progress, Info}</c> term
+          interpreted in the boot script affects
+          <c><anno>ProvidedStatus</anno></c>, that is,
+          <c><anno>ProvidedStatus</anno></c> gets the value of <c>Info</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="reboot" arity="0"/>
-      <fsummary>Take down and restart an Erlang node smoothly</fsummary>
+      <fsummary>Take down and restart an Erlang node smoothly.</fsummary>
       <desc>
         <p>All applications are taken down smoothly, all code is
           unloaded, and all ports are closed before the system
-          terminates. If the <c>-heart</c> command line flag was given,
-          the <c>heart</c> program will try to reboot the system. Refer
-          to <c>heart(3)</c> for more information.</p>
+          terminates. If command-line flag <c>-heart</c> was specified,
+          the <c>heart</c> program tries to reboot the system. For more
+          information, see
+          <seealso marker="kernel:heart"><c>kernel:heart(3)</c></seealso>.</p>
         <p>To limit the shutdown time, the time <c>init</c> is allowed
-          to spend taking down applications, the <c>-shutdown_time</c>
-          command line flag should be used.</p>
+          to spend taking down applications, command-line flag
+          <c>-shutdown_time</c> is to be used.</p>
       </desc>
     </func>
+
     <func>
       <name name="restart" arity="0"/>
-      <fsummary>Restart the running Erlang node</fsummary>
+      <fsummary>Restart the running Erlang node.</fsummary>
       <desc>
         <p>The system is restarted <em>inside</em> the running Erlang
           node, which means that the emulator is not restarted. All
@@ -160,80 +172,91 @@
           the same way as initially started. The same <c>BootArgs</c>
           are used again.</p>
         <p>To limit the shutdown time, the time <c>init</c> is allowed
-          to spend taking down applications, the <c>-shutdown_time</c>
-          command line flag should be used.</p>
+          to spend taking down applications, command-line flag
+          <c>-shutdown_time</c> is to be used.</p>
       </desc>
     </func>
+
     <func>
       <name name="script_id" arity="0"/>
-      <fsummary>Get the identity of the used boot script</fsummary>
+      <fsummary>Get the identity of the used boot script.</fsummary>
       <desc>
-        <p>Get the identity of the boot script used to boot the system.
+        <p>Gets the identity of the boot script used to boot the system.
           <c><anno>Id</anno></c> can be any Erlang term. In the delivered boot
-          scripts, <c><anno>Id</anno></c> is <c>{Name, Vsn}</c>. <c>Name</c> and
-          <c>Vsn</c> are strings.</p>
+          scripts, <c><anno>Id</anno></c> is <c>{Name, Vsn}</c>. <c>Name</c>
+          and <c>Vsn</c> are strings.</p>
       </desc>
     </func>
+
     <func>
       <name name="stop" arity="0"/>
-      <fsummary>Take down an Erlang node smoothly</fsummary>
+      <fsummary>Take down an Erlang node smoothly.</fsummary>
       <desc>
         <p>The same as
 	<seealso marker="#stop/1"><c>stop(0)</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
       <name name="stop" arity="1"/>
-      <fsummary>Take down an Erlang node smoothly</fsummary>
+      <fsummary>Take down an Erlang node smoothly.</fsummary>
       <desc>
         <p>All applications are taken down smoothly, all code is
           unloaded, and all ports are closed before the system
-          terminates by calling <c>halt(<anno>Status</anno>)</c>. If the
-          <c>-heart</c> command line flag was given, the <c>heart</c>
-          program is terminated before the Erlang node
-          terminates. Refer to <c>heart(3)</c> for more
-          information.</p>
+          terminates by calling <c>halt(<anno>Status</anno>)</c>. If
+          command-line flag <c>-heart</c> was specified, the <c>heart</c>
+          program is terminated before the Erlang node terminates.
+          For more information, see
+          <seealso marker="kernel:heart"><c>kernel:heart(3)</c></seealso>.</p>
         <p>To limit the shutdown time, the time <c>init</c> is allowed
-          to spend taking down applications, the <c>-shutdown_time</c>
-          command line flag should be used.</p>
+          to spend taking down applications, command-line flag
+          <c>-shutdown_time</c> is to be used.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
     <marker id="flags"></marker>
-    <title>Command Line Flags</title>
-    <warning><p>The support for loading of code from archive files is
-     experimental. The sole purpose of releasing it before it is ready
-     is to obtain early feedback. The file format, semantics,
-     interfaces etc. may be changed in a future release. The
-     <c>-code_path_choice</c> flag is also experimental.</p></warning>
+    <title>Command-Line Flags</title>
+    <warning>
+      <p>The support for loading of code from archive files is
+        experimental. The only purpose of releasing it before it is ready
+	is to obtain early feedback. The file format, semantics,
+	interfaces, and so on, can  be changed in a future release. The
+        <c>-code_path_choice</c> flag is also experimental.</p>
+    </warning>
 
-    <p>The <c>init</c> module interprets the following command line
-      flags:</p>
+    <p>The <c>init</c> module interprets the following command-line flags:</p>
 
     <taglist>
       <tag><c>--</c></tag>
       <item>
         <p>Everything following <c>--</c> up to the next flag is
           considered plain arguments and can be retrieved using
-          <c>get_plain_arguments/0</c>.</p>
+          <seealso marker="#get_plain_arguments/0">
+          <c>get_plain_arguments/0</c></seealso>.</p>
       </item>
       <tag><c>-code_path_choice Choice</c></tag>
       <item>
-        <p>This flag can be set to <c>strict</c> or <c>relaxed</c>. It
-         controls whether each directory in the code path should be
-         interpreted strictly as it appears in the <c>boot script</c> or if
-         <c>init</c> should be more relaxed and try to find a suitable
-         directory if it can choose from a regular ebin directory and
-         an ebin directory in an archive file. This flag is particular
-         useful when you want to elaborate with code loading from
-         archives without editing the <c>boot script</c>. See <seealso
-         marker="sasl:script">script(4)</seealso> for more information
-         about interpretation of boot scripts. The flag does also have
-         a similar affect on how the code server works. See <seealso
-         marker="kernel:code">code(3)</seealso>.</p>
-	 
+        <p>Can be set to <c>strict</c> or <c>relaxed</c>. It controls how each
+          directory in the code path is to be interpreted:</p>
+        <list type="bulleted">
+          <item>
+            <p>Strictly as it appears in the <c>boot script</c>, or</p>
+          </item>
+          <item>
+            <p><c>init</c> is to be more relaxed and try to find a suitable
+              directory if it can choose from a regular <c>ebin</c> directory
+              and an <c>ebin</c> directory in an archive file.</p>
+          </item>
+        </list>
+        <p>This flag is particular
+          useful when you want to elaborate with code loading from
+          archives without editing the <c>boot script</c>. For more
+          information about interpretation of boot scripts, see
+          <seealso marker="sasl:script"><c>sasl:script(4)</c></seealso>.
+          The flag has also a similar effect on how the code server works; see
+          <seealso marker="kernel:code"><c>kernel:code(3)</c></seealso>.</p>
       </item>
       <tag><c>-epmd_module Module</c></tag>
       <item>
@@ -242,11 +265,11 @@
       </item>
       <tag><c>-eval Expr</c></tag>
       <item>
-        <p>Scans, parses and evaluates an arbitrary expression
+        <p>Scans, parses, and evaluates an arbitrary expression
           <c>Expr</c> during system initialization. If any of these
-          steps fail (syntax error, parse error or exception during
-          evaluation), Erlang stops with an error message. Here is an
-          example that uses Erlang as a hexadecimal calculator:</p>
+          steps fail (syntax error, parse error, or exception during
+          evaluation), Erlang stops with an error message. In the following
+          example Erlang is used as a hexadecimal calculator:</p>
         <pre>
 % <input>erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' \\</input>
 <input>-s erlang halt</input>
@@ -256,14 +279,15 @@ BF</pre>
           <c>-eval</c> expressions are evaluated sequentially with
           <c>-s</c> and <c>-run</c> function calls (this also in
           the order specified). As with <c>-s</c> and <c>-run</c>, an
-          evaluation that does not terminate, blocks the system
+          evaluation that does not terminate blocks the system
           initialization process.</p>
       </item>
       <tag><c>-extra</c></tag>
       <item>
         <p>Everything following <c>-extra</c> is considered plain
           arguments and can be retrieved using
-          <c>get_plain_arguments/0</c>.</p>
+          <seealso marker="#get_plain_arguments/0">
+          <c>get_plain_arguments/0</c></seealso>.</p>
       </item>
       <tag><c>-run Mod [Func [Arg1, Arg2, ...]]</c></tag>
       <item>
@@ -285,8 +309,8 @@ foo:bar()
 foo:bar(["baz", "1", "2"]).</code>
         <p>The functions are executed sequentially in an initialization
           process, which then terminates normally and passes control to
-          the user. This means that a <c>-run</c> call which does not
-          return will block further processing; to avoid this, use
+          the user. This means that a <c>-run</c> call that does not
+          return blocks further processing; to avoid this, use
           some variant of <c>spawn</c> in such cases.</p>
       </item>
       <tag><c>-s Mod [Func [Arg1, Arg2, ...]]</c></tag>
@@ -309,11 +333,11 @@ foo:bar()
 foo:bar([baz, '1', '2']).</code>
         <p>The functions are executed sequentially in an initialization
           process, which then terminates normally and passes control to
-          the user. This means that a <c>-s</c> call which does not
-          return will block further processing; to avoid this, use
+          the user. This means that a <c>-s</c> call that does not
+          return blocks further processing; to avoid this, use
           some variant of <c>spawn</c> in such cases.</p>
-        <p>Due to the limited length of atoms, it is recommended that
-          <c>-run</c> be used instead.</p>
+        <p>Because of the limited length of atoms, it is recommended to
+          use <c>-run</c> instead.</p>
       </item>
     </taglist>
   </section>
@@ -335,9 +359,9 @@ error</pre>
   </section>
 
   <section>
-    <title>SEE ALSO</title>
-    <p><seealso marker="erl_prim_loader">erl_prim_loader(3)</seealso>, 
-      <seealso marker="kernel:heart">heart(3)</seealso></p>
+    <title>See Also</title>
+    <p><seealso marker="erl_prim_loader"><c>erl_prim_loader(3)</c></seealso>, 
+      <seealso marker="kernel:heart"><c>kernel:heart(3)</c></seealso></p>
   </section>
 </erlref>