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, 35 insertions, 32 deletions

diff --git a/system/doc/design_principles/included_applications.xml b/system/doc/design_principles/included_applications.xml
index 3aa43fd595..7f139edf76 100644
--- a/system/doc/design_principles/included_applications.xml
+++ b/system/doc/design_principles/included_applications.xml
@@ -28,35 +28,36 @@
     <rev></rev>
     <file>included_applications.xml</file>
   </header>
+  <marker id="included appl"></marker>
 
   <section>
-    <title>Definition</title>
+    <title>Introduction</title>
     <p>An application can <em>include</em> other applications.
       An <em>included application</em> has its own application directory
       and <c>.app</c> file, but it is started as part of the supervisor
       tree of another application.</p>
     <p>An application can only be included by one other application.</p>
     <p>An included application can include other applications.</p>
-    <p>An application which is not included by any other application is 
+    <p>An application that is not included by any other application is
       called a <em>primary application</em>.</p>
     <marker id="inclappls"></marker>
     <image file="../design_principles/inclappls.gif">
-      <icaption>Primary Application and Included Applications.</icaption>
+      <icaption>Primary Application and Included Applications</icaption>
     </image>
-    <p>The application controller will automatically load any included
-      applications when loading a primary application, but not start
+    <p>The application controller automatically loads any included
+      applications when loading a primary application, but does not start
       them. Instead, the top supervisor of the included application
       must be started by a supervisor in the including application.</p>
     <p>This means that when running, an included application is in fact
-      part of the primary application and a process in an included
-      application will consider itself belonging to the primary
+      part of the primary application, and a process in an included
+      application considers itself belonging to the primary
       application.</p>
   </section>
 
   <section>
     <title>Specifying Included Applications</title>
     <p>Which applications to include is defined by
-      the <c>included_applications</c> key in the <c>.app</c> file.</p>
+      the <c>included_applications</c> key in the <c>.app</c> file:</p>
     <pre>
 {application, prim_app,
  [{description, "Tree application"},
@@ -71,7 +72,7 @@
   </section>
 
   <section>
-    <title>Synchronizing Processes During Startup</title>
+    <title>Synchronizing Processes during Startup</title>
     <p>The supervisor tree of an included application is started as
       part of the supervisor tree of the including application.
       If there is a need for synchronization between processes in
@@ -79,12 +80,12 @@
       by using <em>start phases</em>.</p>
     <p>Start phases are defined by the <c>start_phases</c> key in
       the <c>.app</c> file as a list of tuples <c>{Phase,PhaseArgs}</c>,
-      where <c>Phase</c> is an atom and <c>PhaseArgs</c> is a term.
-      Also, the value of the <c>mod</c> key of the including application
+      where <c>Phase</c> is an atom and <c>PhaseArgs</c> is a term.</p>
+    <p>The value of the <c>mod</c> key of the including application
       must be set to <c>{application_starter,[Module,StartArgs]}</c>,
-      where <c>Module</c> as usual is the application callback module
-      and <c>StartArgs</c> a term provided as argument to the callback
-      function <c>Module:start/2</c>.</p>
+      where <c>Module</c> as usual is the application callback module.
+      <c>StartArgs</c> is a term provided as argument to the callback
+      function <c>Module:start/2</c>:</p>
     <code type="none">
 {application, prim_app,
  [{description, "Tree application"},
@@ -108,36 +109,38 @@
   {mod, {incl_app_cb,[]}}
  ]}.</code>
     <p>When starting a primary application with included applications,
-      the primary application is started the normal way:
-      The application controller creates an application master for
-      the application, and the application master calls
+    the primary application is started the normal way, that is:</p>
+    <list type="bulleted">
+      <item>The application controller creates an application master for
+      the application</item>
+      <item>The application master calls
       <c>Module:start(normal, StartArgs)</c> to start the top
-      supervisor.</p>
+      supervisor.</item>
+    </list>
     <p>Then, for the primary application and each included application
       in top-down, left-to-right order, the application master calls
       <c>Module:start_phase(Phase, Type, PhaseArgs)</c> for each phase
-      defined for for the primary application, in that order.
-      Note that if a phase is not defined for an included application,
+      defined for the primary application, in that order. If a phase
+      is not defined for an included application,
       the function is not called for this phase and application.</p>
     <p>The following requirements apply to the <c>.app</c> file for
       an included application:</p>
     <list type="bulleted">
-      <item>The <c>{mod, {Module,StartArgs}}</c> option must be
-       included. This option is used to find the callback module
-      <c>Module</c> of the application. <c>StartArgs</c> is ignored,
-       as <c>Module:start/2</c> is called only for the primary
-       application.</item>
+      <item>The <c>{mod, {Module,StartArgs}}</c> option must be included.
+      This option is used to find the callback module <c>Module</c> of the
+      application. <c>StartArgs</c> is ignored, as <c>Module:start/2</c>
+      is called only for the primary application.</item>
       <item>If the included application itself contains included
-       applications, instead the option
-      <c>{mod, {application_starter, [Module,StartArgs]}}</c> must be
-       included.</item>
+      applications, instead the
+      <c>{mod, {application_starter, [Module,StartArgs]}}</c> option
+      must be included.</item>
       <item>The <c>{start_phases, [{Phase,PhaseArgs}]}</c> option must
-       be included, and the set of specified phases must be a subset
-       of the set of phases specified for the primary application.</item>
+      be included, and the set of specified phases must be a subset
+      of the set of phases specified for the primary application.</item>
     </list>
     <p>When starting <c>prim_app</c> as defined above, the application
-      controller will call the following callback functions, before
-      <c>application:start(prim_app)</c> returns a value:</p>
+    controller calls the following callback functions before
+    <c>application:start(prim_app)</c> returns a value:</p>
     <code type="none">
 application:start(prim_app)
  => prim_app_cb:start(normal, [])