Update Design Principles

Language cleaned up by the technical writers xsipewe and tmanevik
from Combitech. Proofreading and corrections by Björn Gustavsson.

1 files changed, 94 insertions, 88 deletions

diff --git a/system/doc/design_principles/distributed_applications.xml b/system/doc/design_principles/distributed_applications.xml
index 4d4ba3136e..f40a24fdf5 100644
--- a/system/doc/design_principles/distributed_applications.xml
+++ b/system/doc/design_principles/distributed_applications.xml
@@ -28,71 +28,73 @@
     <rev></rev>
     <file>distributed_applications.xml</file>
   </header>
+  <marker id="distributed appl"></marker>
 
   <section>
-    <title>Definition</title>
-    <p>In a distributed system with several Erlang nodes, there may be
-      a need to control applications in a distributed manner. If
+    <title>Introduction</title>
+    <p>In a distributed system with several Erlang nodes, it can be
+      necessary to control applications in a distributed manner. If
       the node, where a certain application is running, goes down,
-      the application should be restarted at another node.</p>
+      the application is to be restarted at another node.</p>
     <p>Such an application is called a <em>distributed application</em>.
-      Note that it is the control of the application which is
-      distributed, all applications can of course be distributed in
-      the sense that they, for example, use services on other nodes.</p>
-    <p>Because a distributed application may move between nodes, some
+      Notice that it is the control of the application that is distributed.
+      All applications can be distributed in the sense that they,
+      for example, use services on other nodes.</p>
+    <p>Since a distributed application can move between nodes, some
       addressing mechanism is required to ensure that it can be
       addressed by other applications, regardless on which node it
       currently executes. This issue is not addressed here, but the
-      Kernel modules <c>global</c> or <c>pg2</c> can be
-      used for this purpose.</p>
+      <c>global</c> or <c>pg2</c> modules in Kernel
+      can be used for this purpose.</p>
   </section>
 
   <section>
     <title>Specifying Distributed Applications</title>
     <p>Distributed applications are controlled by both the application
-      controller and a distributed application controller process,
-      <c>dist_ac</c>. Both these processes are part of the <c>kernel</c>
-      application. Therefore, distributed applications are specified by
-      configuring the <c>kernel</c> application, using the following
-      configuration parameter (see also <c>kernel(6)</c>):</p>
-    <taglist>
-      <tag><c>distributed = [{Application, [Timeout,] NodeDesc}]</c></tag>
-      <item>
-        <p>Specifies where the application <c>Application = atom()</c>
-          may execute. <c>NodeDesc = [Node | {Node,...,Node}]</c> is
-          a list of node names in priority order. The order between
-          nodes in a tuple is undefined.</p>
-        <p><c>Timeout = integer()</c> specifies how many milliseconds to
-          wait before restarting the application at another node.
-          Defaults to 0.</p>
-      </item>
-    </taglist>
+    controller and a distributed application controller process,
+    <c>dist_ac</c>. Both these processes are part of the Kernel
+    application. Distributed applications are thus specified by
+    configuring the Kernel application, using the following
+    configuration parameter (see also <c>kernel(6)</c>):</p>
+    <p><c>distributed = [{Application, [Timeout,] NodeDesc}]</c></p>
+    <list type="bulleted">
+      <item>Specifies where the application <c>Application = atom()</c>
+      can execute.</item>
+      <item>><c>NodeDesc = [Node | {Node,...,Node}]</c> is a list of
+      node names in priority order. The order between nodes in a tuple
+      is undefined.</item>
+      <item><c>Timeout = integer()</c> specifies how many milliseconds
+      to wait before restarting the application at another node. It
+      defaults to 0.</item>
+    </list>
     <p>For distribution of application control to work properly,
-      the nodes where a distributed application may run must contact
+      the nodes where a distributed application can run must contact
       each other and negotiate where to start the application. This is
-      done using the following <c>kernel</c> configuration parameters:</p>
-    <taglist>
-      <tag><c>sync_nodes_mandatory = [Node]</c></tag>
-      <item>Specifies which other nodes must be started (within
-       the timeout specified by <c>sync_nodes_timeout</c>.</item>
-      <tag><c>sync_nodes_optional = [Node]</c></tag>
-      <item>Specifies which other nodes can be started (within
-       the timeout specified by <c>sync_nodes_timeout</c>.</item>
-      <tag><c>sync_nodes_timeout = integer() | infinity</c></tag>
-      <item>Specifies how many milliseconds to wait for the other nodes
-       to start.</item>
-    </taglist>
-    <p>When started, the node will wait for all nodes specified by
+      done using the following configuration parameters in
+      Kernel:</p>
+      <list type="bulleted">
+	<item><c>sync_nodes_mandatory = [Node]</c> - Specifies which
+	other nodes must be started (within the time-out specified by
+	<c>sync_nodes_timeout</c>).</item>
+	<item><c>sync_nodes_optional = [Node]</c> - Specifies which
+	other nodes can be started (within the time-out specified by
+	<c>sync_nodes_timeout</c>).</item>
+	<item><c>sync_nodes_timeout = integer() | infinity</c> -
+	Specifies how many milliseconds to wait for the other nodes to
+	start.</item>
+      </list>
+    <p>When started, the node waits for all nodes specified by
       <c>sync_nodes_mandatory</c> and <c>sync_nodes_optional</c> to
-      come up. When all nodes have come up, or when all mandatory nodes
-      have come up and the time specified by <c>sync_nodes_timeout</c>
-      has elapsed, all applications will be started. If not all
-      mandatory nodes have come up, the node will terminate.</p>
-    <p>Example: An application <c>myapp</c> should run at the node
-      <c>cp1@cave</c>. If this node goes down, <c>myapp</c> should
+      come up. When all nodes are up, or when all mandatory nodes
+      are up and the time specified by <c>sync_nodes_timeout</c>
+      has elapsed, all applications start. If not all
+      mandatory nodes are up, the node terminates.</p>
+    <p><em>Example:</em></p>
+    <p>An application <c>myapp</c> is to run at the node
+      <c>cp1@cave</c>. If this node goes down, <c>myapp</c> is to
       be restarted at <c>cp2@cave</c> or <c>cp3@cave</c>. A system
-      configuration file <c>cp1.config</c> for <c>cp1@cave</c> could
-      look like:</p>
+      configuration file <c>cp1.config</c> for <c>cp1@cave</c> can
+      look as follows:</p>
     <code type="none">
 [{kernel,
   [{distributed, [{myapp, 5000, [cp1@cave, {cp2@cave, cp3@cave}]}]},
@@ -103,13 +105,13 @@
 ].</code>
     <p>The system configuration files for <c>cp2@cave</c> and
       <c>cp3@cave</c> are identical, except for the list of mandatory
-      nodes which should be <c>[cp1@cave, cp3@cave]</c> for
+      nodes, which is to be <c>[cp1@cave, cp3@cave]</c> for
       <c>cp2@cave</c> and <c>[cp1@cave, cp2@cave]</c> for
       <c>cp3@cave</c>.</p>
     <note>
       <p>All involved nodes must have the same value for
-        <c>distributed</c> and <c>sync_nodes_timeout</c>, or
-        the behaviour of the system is undefined.</p>
+        <c>distributed</c> and <c>sync_nodes_timeout</c>.
+        Otherwise the system behaviour is undefined.</p>
     </note>
   </section>
 
@@ -117,28 +119,29 @@
     <title>Starting and Stopping Distributed Applications</title>
     <p>When all involved (mandatory) nodes have been started,
       the distributed application can be started by calling
-      <c>application:start(Application)</c> at <em>all of these nodes.</em></p>
-    <p>It is of course also possible to use a boot script (see
-      <seealso marker="release_structure">Releases</seealso>) which
-      automatically starts the application.</p>
-    <p>The application will be started at the first node, specified
-      by the <c>distributed</c> configuration parameter, which is up
-      and running. The application is started as usual. That is, an
-      application master is created and calls the application callback
-      function:</p>
+      <c>application:start(Application)</c> at <em>all of these
+      nodes.</em></p>
+    <p>A boot script (see
+      <seealso marker="release_structure">Releases</seealso>)
+      can be used that automatically starts the application.</p>
+    <p>The application is started at the first operational node that
+      is listed in the list of nodes in the <c>distributed</c>
+      configuration parameter. The application is started as usual.
+      That is, an application master is created and calls the
+      application callback function:</p>
     <code type="none">
 Module:start(normal, StartArgs)</code>
-    <p>Example: Continuing the example from the previous section,
-      the three nodes are started, specifying the system configuration
-      file:</p>
+    <p>Example:</p>
+    <p>Continuing the example from the previous section, the three nodes
+    are started, specifying the system configuration file:</p>
     <pre>
 > <input>erl -sname cp1 -config cp1</input>
 > <input>erl -sname cp2 -config cp2</input>
 > <input>erl -sname cp3 -config cp3</input></pre>
-    <p>When all nodes are up and running, <c>myapp</c> can be started.
+    <p>When all nodes are operational, <c>myapp</c> can be started.
       This is achieved by calling <c>application:start(myapp)</c> at
       all three nodes. It is then started at <c>cp1</c>, as shown in
-      the figure below.</p>
+      the following figure:</p>
     <marker id="dist1"></marker>
     <image file="../design_principles/dist1.gif">
       <icaption>Application myapp - Situation 1</icaption>
@@ -150,31 +153,33 @@ Module:start(normal, StartArgs)</code>
   <section>
     <title>Failover</title>
     <p>If the node where the application is running goes down,
-      the application is restarted (after the specified timeout) at
-      the first node, specified by the <c>distributed</c> configuration
-      parameter, which is up and running. This is called a
+      the application is restarted (after the specified time-out) at
+      the first operational node that is listed in the list of nodes
+      in the <c>distributed</c> configuration parameter. This is called a
       <em>failover</em>.</p>
     <p>The application is started the normal way at the new node,
       that is, by the application master calling:</p>
     <code type="none">
 Module:start(normal, StartArgs)</code>
-    <p>Exception: If the application has the <c>start_phases</c> key
-      defined (see <seealso marker="included_applications">Included Applications</seealso>), then the application is instead started
-      by calling:</p>
+    <p>An exception is if the application has the <c>start_phases</c>
+      key defined
+      (see <seealso marker="included_applications">Included Applications</seealso>).
+      The application is then instead started by calling:</p>
     <code type="none">
 Module:start({failover, Node}, StartArgs)</code>
-    <p>where <c>Node</c> is the terminated node.</p>
-    <p>Example: If <c>cp1</c> goes down, the system checks which one of
+    <p>Here <c>Node</c> is the terminated node.</p>
+    <p><em>Example:</em></p>
+    <p> If <c>cp1</c> goes down, the system checks which one of
       the other nodes, <c>cp2</c> or <c>cp3</c>, has the least number of
       running applications, but waits for 5 seconds for <c>cp1</c> to
       restart. If <c>cp1</c> does not restart and <c>cp2</c> runs fewer
-      applications than <c>cp3,</c> then <c>myapp</c> is restarted on
+      applications than <c>cp3</c>, <c>myapp</c> is restarted on
       <c>cp2</c>.</p>
     <marker id="dist2"></marker>
     <image file="../design_principles/dist2.gif">
       <icaption>Application myapp - Situation 2</icaption>
     </image>
-    <p>Suppose now that <c>cp2</c> goes down as well and does not
+    <p>Suppose now that <c>cp2</c> goes also down and does not
       restart within 5 seconds. <c>myapp</c> is now restarted on
       <c>cp3</c>.</p>
     <marker id="dist3"></marker>
@@ -186,28 +191,29 @@ Module:start({failover, Node}, StartArgs)</code>
   <section>
     <title>Takeover</title>
     <p>If a node is started, which has higher priority according
-      to <c>distributed</c>, than the node where a distributed
-      application is currently running, the application will be
-      restarted at the new node and stopped at the old node. This is
+      to <c>distributed</c> than the node where a distributed
+      application is running, the application is restarted at the
+      new node and stopped at the old node. This is
       called a <em>takeover</em>.</p>
     <p>The application is started by the application master calling:</p>
     <code type="none">
 Module:start({takeover, Node}, StartArgs)</code>
-    <p>where <c>Node</c> is the old node.</p>
-    <p>Example: If <c>myapp</c> is running at <c>cp3</c>, and if
-      <c>cp2</c> now restarts, it will not restart <c>myapp</c>,
-      because the order between nodes <c>cp2</c> and <c>cp3</c> is
+    <p>Here <c>Node</c> is the old node.</p>
+    <p><em>Example: </em></p>
+    <p>If <c>myapp</c> is running at <c>cp3</c>, and if
+      <c>cp2</c> now restarts, it does not restart <c>myapp</c>,
+      as the order between the <c>cp2</c> and <c>cp3</c> nodes is
       undefined.</p>
     <marker id="dist4"></marker>
     <image file="../design_principles/dist4.gif">
       <icaption>Application myapp - Situation 4</icaption>
     </image>
-    <p>However, if <c>cp1</c> restarts as well, the function
+    <p>However, if <c>cp1</c> also restarts, the function
       <c>application:takeover/2</c> moves <c>myapp</c> to <c>cp1</c>,
-      because <c>cp1</c> has a higher priority than <c>cp3</c> for this
-      application.  In this case,
-      <c>Module:start({takeover, cp3@cave}, StartArgs)</c> is executed
-      at <c>cp1</c> to start the application.</p>
+      as <c>cp1</c> has a higher priority than <c>cp3</c> for this
+      application. In this case,
+      <c>Module:start({takeover, cp3@cave}, StartArgs)</c> is
+      executed at <c>cp1</c> to start the application.</p>
     <marker id="dist5"></marker>
     <image file="../design_principles/dist5.gif">
       <icaption>Application myapp - Situation 5</icaption>