Merge branch 'siri/sasl/doc-editors/OTP-13000' into maint

* siri/sasl/doc-editors/OTP-13000:
  sasl: Editorial changes

1 files changed, 93 insertions, 85 deletions

diff --git a/lib/sasl/doc/src/sasl_app.xml b/lib/sasl/doc/src/sasl_app.xml
index fe38e69ce3..8d79251c7e 100644
--- a/lib/sasl/doc/src/sasl_app.xml
+++ b/lib/sasl/doc/src/sasl_app.xml
@@ -27,12 +27,11 @@
     <docno></docno>
     <date></date>
     <rev></rev>
-  </header>
-  <app>sasl</app>
-  <appsummary>The SASL Application</appsummary>
-  <description>
-    <p>This section describes the SASL (System Architecture Support Libraries)
-      application which provides the following services:</p>
+    </header>
+    <app>sasl</app>
+    <appsummary>The SASL application</appsummary>
+    <description>
+    <p>The <c>SASL</c> application provides the following services:</p>
     <list type="bulleted">
       <item><c>alarm_handler</c></item>
       <item><c>overload</c></item>
@@ -40,138 +39,147 @@
       <item><c>release_handler</c></item>
       <item><c>systools</c></item>
     </list>
-    <p>The SASL application also includes <c>error_logger</c> event
-      handlers for formatting SASL error and crash reports.</p>
-
+    <p>The <c>SASL</c> application also includes <c>error_logger</c> event
+      handlers for formatting <c>SASL</c> error and crash reports.</p>
     <note>
-       <p>The SASL application in OTP has nothing to do with
+       <p>The <c>SASL</c> application in OTP has nothing to do with
           "Simple Authentication and Security Layer" (RFC 4422).</p>
     </note>
-
   </description>
 
   <section>
     <title>Error Logger Event Handlers</title>
     <p>The following error logger event handlers are used by
-      the SASL application.</p>
+      the <c>SASL</c> application.</p>
     <taglist>
       <tag><c>sasl_report_tty_h</c></tag>
       <item>
-        <p>Formats and writes <em>supervisor reports</em>, <em>crash reports</em> and <em>progress reports</em> to <c>stdio</c>.
-	This error logger event handler will use
+        <p>Formats and writes <em>supervisor reports</em>, <em>crash
+        reports</em>, and <em>progress reports</em> to <c>stdio</c>.
+        This error logger event handler uses
 	<seealso marker="kernel:kernel_app#error_logger_format_depth">error_logger_format_depth</seealso>
-	in the Kernel application to limit how much detail are printed to
-	for crash and supervisor reports.</p>
+	in the <c>Kernel</c> application to limit how much detail is
+        printed in crash and supervisor reports.</p>
       </item>
       <tag><c>sasl_report_file_h</c></tag>
       <item>
-        <p>Formats and writes <em>supervisor reports</em>, <em>crash report</em> and <em>progress report</em> to a single file.
-	This error logger event handler will use
+        <p>Formats and writes <em>supervisor reports</em>, <em>crash
+        report</em>, and <em>progress report</em> to a single file.
+        This error logger event handler uses
 	<seealso marker="kernel:kernel_app#error_logger_format_depth">error_logger_format_depth</seealso>
-	in the Kernel application to limit how much detail are printed to
-	for crash and supervisor reports.</p>
+	in the <c>Kernel</c> application to limit the details
+        printed in crash and supervisor reports.</p>
       </item>
       <tag><c>log_mf_h</c></tag>
       <item>
-        <p>This error logger writes <em>all</em> events sent to
-          the error logger to disk.</p>
-        <p>To activate this event handler, the following three sasl
-          configuration parameters must be set:
-          <c>error_logger_mf_dir</c>, <c>error_logger_mf_maxbytes</c>
-          and <c>error_logger_mf_maxfiles</c>. See below for more
-          information about the configuration parameters.</p>
+        <p>This error logger writes <em>all</em> events sent to the
+          error logger to disk. Multiple files and log rotation are
+          used. For efficiency reasons, each event is written as a
+          binary. For more information about this handler,
+          see <seealso marker="stdlib:log_mf_h">the <c>STDLIB</c> Reference
+          Manual</seealso>.</p>
+        <p>To activate this event handler, three <c>SASL</c>
+          configuration parameters must be set,
+          <c>error_logger_mf_dir</c>, <c>error_logger_mf_maxbytes</c>,
+          and <c>error_logger_mf_maxfiles</c>. The next section provides
+          more information about the configuration parameters.</p>
       </item>
     </taglist>
   </section>
 
   <section>
     <title>Configuration</title>
-    <p>The following configuration parameters are defined for the SASL
-      application. See <c>app(4)</c> for more information about
-      configuration parameters:</p>
+    <p>The following configuration parameters are defined for the <c>SASL</c>
+      application. For more information about configuration parameters, see
+      <seealso marker="kernel:app"><c>app(4)</c></seealso> in <c>Kernel</c>.</p>
+    <p>All configuration parameters are optional.</p>
     <taglist>
-      <tag><c><![CDATA[sasl_error_logger = Value <optional>]]></c></tag>
+      <tag><c><![CDATA[sasl_error_logger = Value ]]></c></tag>
       <item>
-        <p><c>Value</c> is one of:</p>
+        <p><c>Value</c> is one of the following:</p>
         <taglist>
           <tag><c>tty</c></tag>
-          <item>Installs <c>sasl_report_tty_h</c> in the error logger.
-           This is the default option.</item>
+          <item><p>Installs <c>sasl_report_tty_h</c> in the error logger.
+            This is the default option.</p></item>
           <tag><c>{file,FileName}</c></tag>
-          <item>Installs <c>sasl_report_file_h</c> in the error logger.
-           This makes all reports go to the file <c>FileName</c>.
-          <c>FileName</c> is a string.</item>
+          <item><p>Installs <c>sasl_report_file_h</c> in the error logger.
+            All reports go to file <c>FileName</c>, which is a
+            string.</p></item>
           <tag><c>{file,FileName,Modes}</c></tag>
-          <item>Same as <c>{file,FileName}</c> except that the <c>Modes</c>
-           allows to specify the modes used for opening the <c>FileName</c>
-           given to the <seealso marker="kernel:file#open/2">file:open/2</seealso>
-           call. When not specified, the <c>Modes</c> defaults to <c>[write]</c>.
-           Use <c>[append]</c> for having the <c>FileName</c> open in append mode.
-          <c>FileName</c> is a string.</item>
+          <item><p>Same as <c>{file,FileName}</c>, except that <c>Modes</c>
+            allows you to specify the modes used for opening the <c>FileName</c>
+            given to the <seealso marker="kernel:file#open/2">file:open/2</seealso>
+            call. When not specified, <c>Modes</c> defaults to <c>[write]</c>.
+            Use <c>[append]</c> to have the <c>FileName</c> open in append mode.
+            <c>FileName</c> is a string.</p></item>
           <tag><c>false</c></tag>
-          <item>
-            <p>No SASL error logger handler is installed.</p>
-          </item>
+          <item><p>No <c>SASL</c> error logger handler is installed.</p></item>
         </taglist>
       </item>
-      <tag><c><![CDATA[errlog_type = error | progress | all <optional>]]></c></tag>
+      <tag><c><![CDATA[errlog_type = error | progress | all ]]></c></tag>
       <item>
         <p>Restricts the error logging performed by the specified
-          <c>sasl_error_logger</c> to error reports, progress reports,
+          <c>sasl_error_logger</c> to error reports or progress reports,
           or both. Default is <c>all</c>.</p>
       </item>
-      <tag><c><![CDATA[error_logger_mf_dir = string() | false<optional>]]></c></tag>
+      <tag><c><![CDATA[error_logger_mf_dir = string() | false ]]></c></tag>
       <item>
-        <p>Specifies in which directory the files are stored. If this
-          parameter is undefined or <c>false</c>,
+        <p>Specifies in which directory <c>log_mf_h</c> is to store
+          its files. If this parameter is undefined or <c>false</c>,
           the <c>log_mf_h</c> handler is not installed.</p>
       </item>
-      <tag><c><![CDATA[error_logger_mf_maxbytes = integer() <optional>]]></c></tag>
+      <tag><c><![CDATA[error_logger_mf_maxbytes = integer() ]]></c></tag>
       <item>
-        <p>Specifies how large each individual file can be. If this
-          parameter is undefined, the <c>log_mf_h</c> handler is not
-          installed.</p>
+        <p>Specifies the maximum size of each individual file written
+          by <c>log_mf_h</c>. If this parameter is undefined,
+          the <c>log_mf_h</c> handler is not installed.</p>
       </item>
-      <tag><c><![CDATA[error_logger_mf_maxfiles = 0<integer()<256 <optional>]]></c></tag>
+      <tag><c><![CDATA[error_logger_mf_maxfiles = 0<integer()<256 ]]></c></tag>
       <item>
-        <p>Specifies how many files are used. If this parameter is
-          undefined, the <c>log_mf_h</c> handler is not installed.</p>
+        <p>Specifies the number of files used by <c>log_mf_h</c>. If
+          this parameter is undefined, the <c>log_mf_h</c> handler is
+          not installed.</p>
       </item>
-      <tag><c><![CDATA[overload_max_intensity = float() > 0 <optional>]]></c></tag>
+      <tag><c><![CDATA[overload_max_intensity = float() > 0 ]]></c></tag>
       <item>
-        <p>Specifies the maximum intensity for <c>overload</c>. Default
+        <p>Specifies the maximum intensity
+          for <seealso marker="overload"><c>overload</c></seealso>. Default
           is <c>0.8</c>.</p>
       </item>
-      <tag><c><![CDATA[overload_weight = float() > 0 <optional>]]></c></tag>
+      <tag><c><![CDATA[overload_weight = float() > 0 ]]></c></tag>
       <item>
-        <p>Specifies the <c>overload</c> weight. Default is <c>0.1</c>.</p>
+        <p>Specifies the <seealso marker="overload"><c>overload</c></seealso>
+        weight. Default is <c>0.1</c>.</p>
       </item>
-      <tag><c><![CDATA[start_prg = string() <optional>]]></c></tag>
+      <tag><c><![CDATA[start_prg = string() ]]></c></tag>
       <item>
-        <p>Specifies which program should be used when restarting
-          the system. Default is <c>$OTP_ROOT/bin/start</c>.</p>
+        <p>Specifies the program to be used when restarting the system
+          during release installation. Default is
+          <c>$OTP_ROOT/bin/start</c>.</p>
       </item>
-      <tag><c><![CDATA[masters = [atom()] <optional>]]></c></tag>
+      <tag><c><![CDATA[masters = [atom()] ]]></c></tag>
       <item>
-        <p>Specifies which nodes this node uses to read/write release
-          information. This parameter is ignored if
-          the <c>client_directory</c> parameter is not set.</p>
+        <p>Specifies the nodes used by this node to read/write release
+          information. This parameter is ignored if parameter
+          <c>client_directory</c> is not set.</p>
       </item>
-      <tag><c><![CDATA[client_directory = string() <optional>]]></c></tag>
+      <tag><c><![CDATA[client_directory = string() ]]></c></tag>
       <item>
         <p>This parameter specifies the client directory at the master
-          nodes. Refer to Release Handling in <em>OTP Design Principles</em> for more information.  This parameter is
-          ignored if the <c>masters</c> parameter is not set.</p>
+          nodes. For details, see
+          <seealso marker="doc/design_principles:release_handling">Release Handling</seealso>
+          in <em>OTP Design Principles</em>. This parameter is
+          ignored if parameter <c>masters</c> is not set.</p>
       </item>
-      <tag><c><![CDATA[static_emulator = true | false <optional>]]></c></tag>
+      <tag><c><![CDATA[static_emulator = true | false ]]></c></tag>
       <item>
         <p>Indicates if the Erlang emulator is statically installed. A
           node with a static emulator cannot switch dynamically to a
-          new emulator as the executable files are written into memory
-          statically.  This parameter is ignored if the <c>masters</c>
-          and <c>client_directory</c> parameters are not set.</p>
+          new emulator, as the executable files are written into memory
+          statically. This parameter is ignored if parameters <c>masters</c>
+          and <c>client_directory</c> are not set.</p>
       </item>
-      <tag><c><![CDATA[releases_dir = string() <optional>]]></c></tag>
+      <tag><c><![CDATA[releases_dir = string() ]]></c></tag>
       <item>
         <p>Indicates where the <c>releases</c> directory is located.
           The release handler writes all its files to this directory.
@@ -179,7 +187,7 @@
           <c>RELDIR</c> is used. By default, this is
           <c>$OTP_ROOT/releases</c>.</p>
       </item>
-      <tag><c><![CDATA[utc_log = true | false <optional>]]></c></tag>
+      <tag><c><![CDATA[utc_log = true | false ]]></c></tag>
       <item>
         <p>If set to <c>true</c>, all dates in textual log outputs are
           displayed in Universal Coordinated Time with the string
@@ -190,13 +198,13 @@
 
   <section>
     <title>See Also</title>
-    <p><seealso marker="alarm_handler">alarm_handler(3)</seealso>,
-      error_logger(3),
-      log_mf_h(3),
-      <seealso marker="overload">overload(3)</seealso>,
-      <seealso marker="rb">rb(3)</seealso>,
-      <seealso marker="release_handler">release_handler(3)</seealso>,
-      <seealso marker="systools">systools(3)</seealso></p>
+    <p><seealso marker="alarm_handler"><c>alarm_handler(3)</c></seealso>,
+      <seealso marker="kernel:error_logger"><c>error_logger(3)</c></seealso>,
+      <seealso marker="stdlib:log_mf_h"><c>log_mf_h(3)</c></seealso>,
+      <seealso marker="overload"><c>overload(3)</c></seealso>,
+      <seealso marker="rb"><c>rb(3)</c></seealso>,
+      <seealso marker="release_handler"><c>release_handler(3)</c></seealso>,
+      <seealso marker="systools"><c>systools(3)</c></seealso></p>
   </section>
 </appref>