Merge branch 'maint'

1 files changed, 191 insertions, 207 deletions

diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml
index f12f76890c..602b88f6ed 100644
--- a/erts/doc/src/escript.xml
+++ b/erts/doc/src/escript.xml
@@ -33,17 +33,18 @@
   <comsummary>Erlang scripting support</comsummary>
   <description>
     <p><c>escript</c> provides support for running short Erlang programs
-      without having to compile them first and an easy way to retrieve the
-      command line arguments.</p>
+      without having to compile them first, and an easy way to retrieve the
+      command-line arguments.</p>
   </description>
+
   <funcs>
     <func>
       <name>script-name script-arg1 script-arg2...</name>
       <name>escript escript-flags script-name script-arg1 script-arg2...</name>
-      <fsummary>Run a script written in Erlang</fsummary>
+      <fsummary>Run a script written in Erlang.</fsummary>
       <desc>
         <p><c>escript</c> runs a script written in Erlang.</p>
-        <p>Here follows an example.</p>
+        <p>Example:</p>
         <pre>
 $ <input>chmod u+x factorial</input>
 $ <input>cat factorial</input>
@@ -73,195 +74,183 @@ factorial 5 = 120
 $ <input>./factorial</input>
 usage: factorial integer
 $ <input>./factorial five</input>
-usage: factorial integer
-        </pre>
+usage: factorial integer</pre>
         <p>The header of the Erlang script in the example differs from
-        a normal Erlang module.  The first line is intended to be the
-        interpreter line, which invokes <c>escript</c>. However if you
-        invoke the <c>escript</c> like this</p>
+          a normal Erlang module. The first line is intended to be the
+          interpreter line, which invokes <c>escript</c>.</p>
+        <p>However, if you invoke the <c>escript</c> as follows,
+          the contents of the first line does not matter, but it
+          cannot contain Erlang code as it will be ignored:</p>
         <pre>
-$ <input>escript factorial 5</input>        </pre>
-        <p>the contents of the first line does not matter, but it
-        cannot contain Erlang code as it will be ignored.</p>
-        <p>The second line in the example, contains an optional
-          directive to the <c>Emacs</c> editor which causes it to
+$ <input>escript factorial 5</input></pre>
+        <p>The second line in the example contains an optional
+          directive to the <c>Emacs</c> editor, which causes it to
           enter the major mode for editing Erlang source files. If the
-          directive is present it must be located on the second
+          directive is present, it must be located on the second
           line.</p>
-
-        <p>If there is a comment selecting the <seealso
-          marker="stdlib:epp#encoding">encoding</seealso> it can be
+        <p>If a comment selecting the <seealso
+          marker="stdlib:epp#encoding">encoding</seealso> exists, it can be
           located on the second line.</p>
-
-        <note><p>
-          The encoding specified by the above mentioned comment
-          applies to the script itself. The encoding of the
-          I/O-server, however, has to be set explicitly like this:</p>
-<code>io:setopts([{encoding, unicode}])</code>
+        <note>
+          <p>The encoding specified by the above mentioned comment
+            applies to the script itself. The encoding of the
+            I/O-server, however, must be set explicitly as follows:</p>
+          <code>
+io:setopts([{encoding, unicode}])</code>
           <p>The default encoding of the I/O-server for <c>standard_io</c>
-          is <c>latin1</c>
-          since the script runs in a non-interactive terminal
-          (see <seealso marker="stdlib:unicode_usage#unicode_options_summary">
-          Using Unicode in Erlang</seealso>).
-        </p></note>
-
-	<p>On the third line (or second line depending on the presence
-          of the Emacs directive), it is possible to give arguments to
-          the emulator, such as </p>
+            is <c>latin1</c>, as the script runs in a non-interactive terminal
+            (see section
+            <seealso marker="stdlib:unicode_usage#unicode_options_summary">
+            Summary of Options</seealso>) in the <c>STDLIB</c> User's Guide.</p>
+        </note>
+        <p>On the third line (or second line depending on the presence
+          of the Emacs directive), arguments can be specified to
+          the emulator, for example:</p>
         <pre>
 %%! -smp enable -sname factorial -mnesia debug verbose</pre>
         <p>Such an argument line must start with <c>%%!</c> and the
-          rest of the line will interpreted as arguments to the emulator.</p>
+          remaining line is interpreted as arguments to the emulator.</p>
         <p>If you know the location of the <c>escript</c> executable, the first
-          line can directly give the path to <c>escript</c>. For instance:</p>
+          line can directly give the path to <c>escript</c>, for example:</p>
         <pre>
-#!/usr/local/bin/escript        </pre>
-        <p>As any other kind of scripts, Erlang scripts will not work on
+#!/usr/local/bin/escript</pre>
+        <p>As any other type of scripts, Erlang scripts do not work on
           Unix platforms if the execution bit for the script file is not set.
-          (Use <c>chmod +x script-name</c> to turn on the execution bit.)
-          </p>
-
-        <p>The rest of the Erlang script file may either contain
-        Erlang <c>source code</c>, an <c>inlined beam file</c> or an
-        <c>inlined archive file</c>.</p>
-
-        <p>An Erlang script file must always contain the function
-        <em>main/1</em>.  When the script is run, the
-        <c>main/1</c> function will be called with a list
-        of strings representing the arguments given to the script (not
-        changed or interpreted in any way).</p>
-
+          (To turn on the execution bit, use <c>chmod +x script-name</c>.)</p>
+        <p>The remaining Erlang script file can either contain
+          Erlang <em>source code</em>, an <em>inlined beam file</em>, or an
+          <em>inlined archive file</em>.</p>
+        <p>An Erlang script file must always contain the <c>main/1</c>
+          function. When the script is run, the
+          <c>main/1</c> function is called with a list
+          of strings representing the arguments specified to the script (not
+          changed or interpreted in any way).</p>
         <p>If the <c>main/1</c> function in the script returns successfully,
-          the exit status for the script will be 0. If an exception is generated
-          during execution, a short message will be printed and the script terminated
-          with exit status 127.</p>
-
-        <p>To return your own non-zero exit code, call <c>halt(ExitCode)</c>;
-          for instance:</p>
+          the exit status for the script is <c>0</c>. If an exception is
+          generated during execution, a short message is printed and the script
+          terminates with exit status <c>127</c>.</p>
+        <p>To return your own non-zero exit code, call <c>halt(ExitCode)</c>,
+          for example:</p>
         <pre>
 halt(1).</pre>
-
-        <p>Call <seealso marker="#script_name_0">escript:script_name()</seealso>
-	from your to script to retrieve the pathname of the script
-	(the pathname is usually, but not always, absolute).</p>
-
+        <p>To retrieve the pathname of the script, call
+          <seealso marker="#script_name_0">
+          <c>escript:script_name()</c></seealso> from your script
+	  (the pathname is usually, but not always, absolute).</p>
         <p>If the file contains source code (as in the example above),
-          it will be processed by the preprocessor <c>epp</c>. This
-          means that you for example may use pre-defined macros (such as
-          <c>?MODULE</c>) as well as include directives like
-          the <c>-include_lib</c> directive. For instance, use</p>
+          it is processed by the
+          <seealso marker="stdlib:epp"><c>epp</c></seealso> preprocessor.
+          This means that you, for example, can use predefined macros
+          (such as <c>?MODULE</c>) and include directives like
+          the <c>-include_lib</c> directive. For example, use</p>
         <pre>
 -include_lib("kernel/include/file.hrl").</pre>
-        <p>to include the record definitions for the records used by the
-          <c>file:read_link_info/1</c> function. You can also select
-          encoding by including a encoding comment here, but if there
-          is a valid encoding comment on the second line it takes
+        <p>to include the record definitions for the records used by function
+          <seealso marker="kernel:file#read_link_info/1">
+          <c>file:read_link_info/1</c></seealso>. You can also select
+          encoding by including an encoding comment here, but if
+          a valid encoding comment exists on the second line, it takes
           precedence.</p>
-
-        <p>The script will be checked for syntactic and semantic
-          correctness before being run. If there are warnings (such as
-          unused variables), they will be printed and the script will
-          still be run. If there are errors, they will be printed and
-          the script will not be run and its exit status will be
-          127.</p>
-
+        <p>The script is checked for syntactic and semantic
+          correctness before it is run. If there are warnings (such as
+          unused variables), they are printed and the script will
+          still be run. If there are errors, they are printed and
+          the script will not be run and its exit status is
+          <c>127</c>.</p>
         <p>Both the module declaration and the export declaration of
           the <c>main/1</c> function are optional.</p>
-
         <p>By default, the script will be interpreted. You can force
           it to be compiled by including the following line somewhere
-          in the script file:</p><pre>
+          in the script file:</p>
+        <pre>
 -mode(compile).</pre>
-
         <p>Execution of interpreted code is slower than compiled code.
-          If much of the execution takes place in interpreted code it
-          may be worthwhile to compile it, even though the compilation
-          itself will take a little while. It is also possible to supply
-	  <c>native</c> instead of <c>compile</c>, this will compile the script
-	  using the native flag, again depending on the characteristics 
-	  of the escript this could or could not be worth while.</p>
-
-        <p>As mentioned earlier, it is possible to have a script which
+          If much of the execution takes place in interpreted code, it
+          can be worthwhile to compile it, although the compilation
+          itself takes a little while. Also, <c>native</c> can be supplied
+          instead of <c>compile</c>. This compiles the script
+          using the native flag and may or may not be worthwhile
+          depending on the escript characteristics.</p>
+        <p>As mentioned earlier, a script can
           contains precompiled <c>beam</c> code. In a precompiled
-          script, the interpretation of the script header is exactly
-          the same as in a script containing source code. That means
+          script, the interpretation of the script header is
+          the same as in a script containing source code. This means
           that you can make a <c>beam</c> file executable by
           prepending the file with the lines starting with <c>#!</c>
           and <c>%%!</c> mentioned above. In a precompiled script, the
-          function
-          <c>main/1</c> must be exported.</p>
-
-        <p>As yet another option it is possible to have an entire
-          Erlang archive in the script. In a archive script, the
-          interpretation of the script header is exactly the same as
-          in a script containing source code. That means that you can
+          <c>main/1</c> function must be exported.</p>
+        <p>Another option is to have an entire
+          Erlang archive in the script. In an archive script, the
+          interpretation of the script header is the same as
+          in a script containing source code. This means that you can
           make an archive file executable by prepending the file with
           the lines starting with <c>#!</c> and <c>%%!</c> mentioned
-          above. In an archive script, the function <c>main/1</c> must
+          above. In an archive script, the <c>main/1</c> function must
           be exported. By default the <c>main/1</c> function in the
           module with the same name as the basename of the
-          <c>escript</c> file will be invoked. This behavior can be
-          overridden by setting the flag <c>-escript main Module</c>
-          as one of the emulator flags. The <c>Module</c> must be the
-          name of a module which has an exported <c>main/1</c>
-          function. See <seealso marker="kernel:code">code(3)</seealso>
-          for more information about archives and code loading.</p>
-
-	  <p>In many cases it is very convenient to have a header in
-	  the escript, especially on Unix platforms. But the header is
-	  in fact optional. This means that you directly can "execute"
-	  an Erlang module, beam file or archive file without adding
-	  any header to them. But then you have to invoke the script
-	  like this:</p>
-	  <pre>
+          <c>escript</c> file is invoked. This behavior can be
+          overridden by setting flag <c>-escript main Module</c>
+          as one of the emulator flags. <c>Module</c> must be the
+          name of a module that has an exported <c>main/1</c>
+          function. For more information about archives and code loading, see
+          <seealso marker="kernel:code"><c>kernel:code(3)</c></seealso>.</p>
+        <p>It is often very convenient to have a header in
+          the escript, especially on Unix platforms. However, the header
+          is optional, so you directly can "execute"
+          an Erlang module, Beam file, or archive file without adding
+          any header to them. But then you have to invoke the script
+          as follows:</p>
+        <pre>
 $ <input>escript factorial.erl 5</input>
 factorial 5 = 120
 $ <input>escript factorial.beam 5</input>
 factorial 5 = 120
 $ <input>escript factorial.zip 5</input>
-factorial 5 = 120
-</pre>
+factorial 5 = 120</pre>
       </desc>
     </func>
+
     <func>
-      <name>escript:create(FileOrBin, Sections) -> ok | {ok, binary()} | {error, term()}</name>
-      <fsummary>Create an escript</fsummary>
+      <name>escript:create(FileOrBin, Sections) -> ok | {ok, binary()} |
+        {error, term()}</name>
+      <fsummary>Create an escript.</fsummary>
       <type>
         <v>FileOrBin = filename() | 'binary'</v>
         <v>Sections = [Header] Body | Body</v>
         <v>Header = shebang | {shebang, Shebang}
-                    | comment | {comment, Comment}
-                    | {emu_args, EmuArgs}</v>
+        &nbsp;&nbsp;&nbsp;| comment | {comment, Comment}
+        &nbsp;&nbsp;&nbsp;| {emu_args, EmuArgs}</v>
         <v>Shebang = string() | 'default' | 'undefined'</v>
         <v>Comment = string() | 'default' | 'undefined'</v>
         <v>EmuArgs = string() | 'undefined'</v>
-        <v>Body = {source, SourceCode}
-                | {beam, BeamCode}
-                | {archive, ZipArchive}
-                | {archive, ZipFiles, ZipOptions}</v>
+        <v>Body = {source, SourceCode} | {beam, BeamCode}
+        &nbsp;&nbsp;&nbsp;| {archive, ZipArchive}
+        &nbsp;&nbsp;&nbsp;| {archive, ZipFiles, ZipOptions}</v>
         <v>SourceCode = BeamCode = file:filename() | binary()</v>
-        <v>ZipArchive = <seealso marker="stdlib:zip#type-filename">zip:filename()</seealso> | binary()</v>
+        <v>ZipArchive = <seealso marker="stdlib:zip#type-filename">
+          zip:filename()</seealso> | binary()</v>
         <v>ZipFiles = [ZipFile]</v>
-        <v>ZipFile = file:filename() | {file:filename(), binary()} | {file:filename(), binary(), file:file_info()}</v>
-        <v>ZipOptions = [<seealso marker="stdlib:zip#type-create_option">zip:create_option()</seealso>]</v>
+        <v>ZipFile = file:filename()
+        &nbsp;&nbsp;&nbsp;| {file:filename(), binary()}
+        &nbsp;&nbsp;&nbsp;| {file:filename(), binary(), file:file_info()}</v>
+        <v>ZipOptions = [<seealso marker="stdlib:zip#type-create_option">
+          zip:create_option()</seealso>]</v>
       </type>
       <desc>
-        <p>The <marker id="create_2"></marker> <c>create/2</c>
-        function creates an escript from a list of sections. The
-        sections can be given in any order. An escript begins with an
-        optional <c>Header</c> followed by a mandatory <c>Body</c>. If
-        the header is present, it does always begin with a
-        <c>shebang</c>, possibly followed by a <c>comment</c> and
-        <c>emu_args</c>. The <c>shebang</c> defaults to
-        <c>"/usr/bin/env escript"</c>. The comment defaults to
-        <c>"This is an -*- erlang -*- file"</c>. The created escript
-        can either be returned as a binary or written to file.</p>
-
-	<p>As an example of how the function can be used, we create an
-	interpreted escript which uses <c>emu_args</c> to set some emulator
-	flag. In this case it happens to disable the smp_support. We
-	do also extract the different sections from the newly created
-	script:</p>
+        <p><marker id="create_2"></marker>
+          Creates an escript from a list of sections. The
+          sections can be specified in any order. An escript begins with an
+          optional <c>Header</c> followed by a mandatory <c>Body</c>. If
+          the header is present, it does always begin with a
+          <c>shebang</c>, possibly followed by a <c>comment</c> and
+          <c>emu_args</c>. The <c>shebang</c> defaults to
+          <c>"/usr/bin/env escript"</c>. The <c>comment</c> defaults to
+          <c>"This is an -*- erlang -*- file"</c>. The created escript
+          can either be returned as a binary or written to file.</p>
+        <p>As an example of how the function can be used, we create an
+          interpreted escript that uses <c>emu_args</c> to set some emulator
+          flag. In this case, it happens to disable the <c>smp_support</c>. We
+          also extract the different sections from the newly created script:</p>
         <pre>
 &gt; <input>Source = "%% Demo\nmain(_Args) ->\n    io:format(erlang:system_info(smp_support)).\n".</input>
 "%% Demo\nmain(_Args) ->\n    io:format(erlang:system_info(smp_support)).\n"
@@ -280,11 +269,9 @@ ok
 "false"
 &gt; <input>escript:extract("demo.escript", []).</input>
 {ok,[{shebang,default}, {comment,default}, {emu_args,"-smp disable"},
-     {source,&lt;&lt;"%% Demo\nmain(_Args) ->\n    io:format(erlang:system_info(smp_su"...&gt;&gt;}]}
-	</pre>
-
-	<p>An escript without header can be created like this:</p>
-<pre>
+     {source,&lt;&lt;"%% Demo\nmain(_Args) ->\n    io:format(erlang:system_info(smp_su"...&gt;&gt;}]}</pre>
+        <p>An escript without header can be created as follows:</p>
+        <pre>
 &gt; <input>file:write_file("demo.erl",
                   ["%% demo.erl\n-module(demo).\n-export([main/1]).\n\n", Source]).</input>
 ok
@@ -299,14 +286,12 @@ ok
      {beam,&lt;&lt;70,79,82,49,0,0,3,68,66,69,65,77,65,116,
              111,109,0,0,0,83,0,0,0,9,...&gt;&gt;}]}
 &gt; <input>os:cmd("escript demo.beam").</input>
-"true"
-</pre>
-	<p>Here we create an archive script containing both Erlang
-	code as well as beam code. Then we iterate over all files in
-	the archive and collect their contents and some info about
-	them.
-	</p>
-<pre>
+"true"</pre>
+        <p>Here we create an archive script containing both Erlang
+          code and Beam code, then we iterate over all files in
+          the archive and collect their contents and some information about
+          them:</p>
+        <pre>
 &gt; <input>{ok, SourceCode} = file:read_file("demo.erl").</input>
 {ok,&lt;&lt;"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...&gt;&gt;}
 &gt; <input>escript:create("demo.escript",
@@ -339,43 +324,43 @@ ok
       &lt;&lt;"%% demo.erl\n-module(demo).\n-export([main/1]).\n\n%% Demo\nmain(_Arg"...&gt;&gt;}]}</pre>
       </desc>
     </func>
+
     <func>
-      <name>escript:extract(File, Options) -> {ok, Sections} | {error, term()}</name>
-      <fsummary>Parses an escript and extracts its sections</fsummary>
+      <name>escript:extract(File, Options) -> {ok, Sections} |
+        {error, term()}</name>
+      <fsummary>Parse an escript and extract its sections.</fsummary>
       <type>
         <v>File = filename()</v>
         <v>Options = [] | [compile_source]</v>
         <v>Sections = Headers Body</v>
         <v>Headers =  {shebang, Shebang}
-                      {comment, Comment}
-                      {emu_args, EmuArgs}</v>
+          {comment, Comment}
+          {emu_args, EmuArgs}</v>
         <v>Shebang = string() | 'default' | 'undefined'</v>
         <v>Comment = string() | 'default' | 'undefined'</v>
         <v>EmuArgs = string() | 'undefined'</v>
         <v>Body = {source, SourceCode}
-                | {source, BeamCode}
-                | {beam, BeamCode}
-	        | {archive, ZipArchive}</v>
+        &nbsp;&nbsp;&nbsp;| {source, BeamCode}
+        &nbsp;&nbsp;&nbsp;| {beam, BeamCode}
+        &nbsp;&nbsp;&nbsp;| {archive, ZipArchive}</v>
         <v>SourceCode = BeamCode = ZipArchive = binary()</v>
       </type>
       <desc>
-        <p>The <marker id="extract_2"></marker> <c>extract/2</c>
-        function parses an escript and extracts its sections. This is
-        the reverse of <c>create/2</c>.</p>
-
-	<p>All sections are returned even if they do not exist in the
-	escript. If a particular section happens to have the same
-	value as the default value, the extracted value is set to the
-	atom <c>default</c>. If a section is missing, the extracted
-	value is set to the atom <c>undefined</c>.  </p>
-
-	<p>The <c>compile_source</c> option only affects the result if
-	the escript contains <c>source</c> code. In that case the
-	Erlang code is automatically compiled and <c>{source,
-	BeamCode}</c> is returned instead of <c>{source,
-	SourceCode}</c>.</p>
-
-	<pre>
+        <p><marker id="extract_2"></marker>
+          Parses an escript and extracts its sections. This is the reverse
+          of <seealso marker="#create_2"><c>create/2</c></seealso>.</p>
+        <p>All sections are returned even if they do not exist in the
+          escript. If a particular section happens to have the same
+          value as the default value, the extracted value is set to the
+          atom <c>default</c>. If a section is missing, the extracted
+          value is set to the atom <c>undefined</c>.</p>
+        <p>Option <c>compile_source</c> only affects the result if
+          the escript contains <c>source</c> code. In this case the
+          Erlang code is automatically compiled and <c>{source,
+          BeamCode}</c> is returned instead of <c>{source,
+          SourceCode}</c>.</p>
+        <p>Example:</p>
+        <pre>
 &gt; <input>escript:create("demo.escript",
                  [shebang, {archive, [{"demo.erl", SourceCode},
                                       {"demo.beam", BeamCode}], []}]).</input>
@@ -385,52 +370,51 @@ ok
               escript:extract("demo.escript", []).</input>
 {ok,[{{archive,&lt;&lt;80,75,3,4,20,0,0,0,8,0,118,7,98,60,105,
                 152,61,93,107,0,0,0,118,0,...&gt;&gt;}
-     {emu_args,undefined}]}
-	</pre>
+     {emu_args,undefined}]}</pre>
       </desc>
     </func>
+
     <func>
       <name>escript:script_name() -> File</name>
-      <fsummary>Returns the name of an escript</fsummary>
+      <fsummary>Return the name of an escript.</fsummary>
       <type>
         <v>File = filename()</v>
       </type>
       <desc>
-        <p>The <marker id="script_name_0"></marker>
-        <c>script_name/0</c> function returns the name of the escript
-        being executed. If the function is invoked outside the context
-        of an escript, the behavior is undefined.</p>
+        <p><marker id="script_name_0"></marker>
+          Returns the name of the escript that is executed.
+          If the function is invoked outside the context
+          of an escript, the behavior is undefined.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
-    <title>Options accepted by escript</title>
+    <title>Options Accepted By escript</title>
     <taglist>
-      <tag>-c</tag>
-      <item>Compile the escript regardless of the value of the mode attribute.
+      <tag><c>-c</c></tag>
+      <item>Compiles the escript regardless of the value of the mode attribute.
       </item>
-
-      <tag>-d</tag>
-      <item>Debug the escript. Starts the debugger, loads the module
-      containing the <c>main/1</c> function into the debugger, sets a
-      breakpoint in <c>main/1</c> and invokes <c>main/1</c>. If the
-      module is precompiled, it must be explicitly compiled with the
-      <c>debug_info</c> option.
+      <tag><c>-d</c></tag>
+      <item>Debugs the escript. Starts the debugger, loads the module
+        containing the <c>main/1</c> function into the debugger, sets a
+        breakpoint in <c>main/1</c>, and invokes <c>main/1</c>. If the
+        module is precompiled, it must be explicitly compiled with option
+        <c>debug_info</c>.
       </item>
-
-      <tag>-i</tag>
-      <item>Interpret the escript regardless of the value of the mode attribute.
+      <tag><c>-i</c></tag>
+      <item>Interprets the escript regardless of the value of the mode
+        attribute.
+      </item>
+      <tag><c>-s</c></tag>
+      <item>Performs a syntactic and semantic check of the script file.
+        Warnings and errors (if any) are written to the standard output, but
+        the script will not be run. The exit status is <c>0</c> if any errors
+        are found, otherwise <c>127</c>.
+      </item>
+      <tag><c>-n</c></tag>
+      <item>Compiles the escript using flag <c>+native</c>.
       </item>
-
-      <tag>-s</tag>
-      <item>Only perform a syntactic and semantic check of the script file.
-       Warnings and errors (if any) are written to the standard output, but
-       the script will not be run. The exit status will be 0 if there were
-       no errors, and 127 otherwise.</item>
-
-       <tag>-n</tag>
-      <item>Compile the escript using the +native flag.</item>
     </taglist>
   </section>
 </comref>