Update STDLIB documentation

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

1 files changed, 314 insertions, 294 deletions

diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml
index 1f4a43f622..24e7b64b9e 100644
--- a/lib/stdlib/doc/src/erl_tar.xml
+++ b/lib/stdlib/doc/src/erl_tar.xml
@@ -28,117 +28,146 @@
     <docno>1</docno>
     <approved>Kenneth Lundin</approved>
     <checked></checked>
-    <date>03-01-21</date>
+    <date>2003-01-21</date>
     <rev>A</rev>
-    <file>erl_tar.sgml</file>
+    <file>erl_tar.xml</file>
   </header>
   <module>erl_tar</module>
-  <modulesummary>Unix 'tar' utility for reading and writing tar archives</modulesummary>
+  <modulesummary>Unix 'tar' utility for reading and writing tar archives.
+  </modulesummary>
   <description>
-    <p>The <c>erl_tar</c> module archives and extract files to and from
-      a tar file. <c>erl_tar</c> supports the <c>ustar</c> format
+    <p>This module archives and extract files to and from
+      a tar file. This module supports the <c>ustar</c> format
       (IEEE Std 1003.1 and ISO/IEC&nbsp;9945-1). All modern <c>tar</c>
       programs (including GNU tar) can read this format. To ensure that
       that GNU tar produces a tar file that <c>erl_tar</c> can read,
-      give the <c>--format=ustar</c> option to GNU tar.</p>
-    <p>By convention, the name of a tar file should end in "<c>.tar</c>".
-      To abide to the convention, you'll need to add "<c>.tar</c>" yourself
-      to the name.</p>
-    <p>Tar files can be created in one operation using the
-      <seealso marker="#create_2">create/2</seealso> or
-      <seealso marker="#create_3">create/3</seealso> function.</p>
-    <p>Alternatively, for more control, the
-      <seealso marker="#open">open</seealso>,
-      <seealso marker="#add">add/3,4</seealso>, and 
-      <seealso marker="#close">close/1</seealso> functions can be used.</p>
-    <p>To extract all files from a tar file, use the 
-      <seealso marker="#extract_1">extract/1</seealso> function.
+      specify option <c>--format=ustar</c> to GNU tar.</p>
+
+    <p>By convention, the name of a tar file is to end in "<c>.tar</c>".
+      To abide to the convention, add "<c>.tar</c>" to the name.</p>
+
+    <p>Tar files can be created in one operation using function
+      <seealso marker="#create/2"><c>create/2</c></seealso> or
+      <seealso marker="#create/3"><c>create/3</c></seealso>.</p>
+
+    <p>Alternatively, for more control, use functions
+      <seealso marker="#open/2"><c>open/2</c></seealso>,
+      <seealso marker="#add/3"><c>add/3,4</c></seealso>, and
+      <seealso marker="#close/1"><c>close/1</c></seealso>.</p>
+
+    <p>To extract all files from a tar file, use function
+      <seealso marker="#extract/1"><c>extract/1</c></seealso>.
       To extract only some files or to be able to specify some more options,
-      use the <seealso marker="#extract_2">extract/2</seealso> function.</p>
+      use function <seealso marker="#extract/2"><c>extract/2</c></seealso>.</p>
+
     <p>To return a list of the files in a tar file,
-      use either the <seealso marker="#table_1">table/1</seealso> or
-      <seealso marker="#table_2">table/2</seealso> function.
+      use function <seealso marker="#table/1"><c>table/1</c></seealso> or
+      <seealso marker="#table/2"><c>table/2</c></seealso>.
       To print a list of files to the Erlang shell,
-      use either the <seealso marker="#t_1">t/1</seealso> or
-      <seealso marker="#tt_1">tt/1</seealso> function.</p>
+      use function <seealso marker="#t/1"><c>t/1</c></seealso> or
+      <seealso marker="#tt/1"><c>tt/1</c></seealso>.</p>
+
     <p>To convert an error term returned from one of the functions
-      above to a readable message, use the
-      <seealso marker="#format_error_1">format_error/1</seealso> function.</p>
+      above to a readable message, use function
+      <seealso marker="#format_error/1"><c>format_error/1</c></seealso>.</p>
   </description>
 
   <section>
-    <title>UNICODE SUPPORT</title>
-    <p>If <seealso
-    marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>
-    returns <c>utf8</c>, path names will be encoded in UTF-8 when
-    creating tar files and path names will be assumed to be encoded in
-    UTF-8 when extracting tar files.</p>
+    <title>Unicode Support</title>
+    <p>If <seealso marker="kernel:file#native_name_encoding/0">
+      <c>file:native_name_encoding/0</c></seealso>
+      returns <c>utf8</c>, path names are encoded in UTF-8 when
+      creating tar files, and path names are assumed to be encoded in
+      UTF-8 when extracting tar files.</p>
 
-    <p>If <seealso
-    marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>
-    returns <c>latin1</c>, no translation of path names will be
-    done.</p>
+    <p>If <seealso marker="kernel:file#native_name_encoding/0">
+      <c>file:native_name_encoding/0</c></seealso>
+      returns <c>latin1</c>, no translation of path names is done.</p>
   </section>
 
   <section>
-    <title>OTHER STORAGE MEDIA</title>
-    <p>The <c>erl_ftp</c> module normally accesses the tar-file on disk using the <seealso marker="kernel:file">file module</seealso>.  When other needs arise, there is a way to define your own low-level Erlang functions to perform the writing and reading on the storage media. See <seealso marker="#init/3">init/3</seealso> for usage.</p>
-    <p>An example of this is the sftp support in <seealso marker="ssh:ssh_sftp#open_tar/3">ssh_sftp:open_tar/3</seealso>. That function opens a tar file on a remote machine using an sftp channel.</p>
+    <title>Other Storage Media</title>
+    <p>The <seealso marker="inets:ftp"><c>ftp</c></seealso>
+      module (Inets) normally accesses the tar file on disk using
+      the <seealso marker="kernel:file"><c>file</c></seealso> module.
+      When other needs arise, you can define your own low-level Erlang
+      functions to perform the writing and reading on the storage media;
+      use function <seealso marker="#init/3"><c>init/3</c></seealso>.</p>
+
+    <p>An example of this is the SFTP support in
+      <seealso marker="ssh:ssh_sftp#open_tar/3">
+      <c>ssh_sftp:open_tar/3</c></seealso>. This function opens a tar file
+      on a remote machine using an SFTP channel.</p>
   </section>
 
   <section>
-    <title>LIMITATIONS</title>
-    <p>For maximum compatibility, it is safe to archive files with names
-      up to 100 characters in length. Such tar files can generally be
-      extracted by any <c>tar</c> program.</p>
-    <p>If filenames exceed 100 characters in length, the resulting tar
-      file can only be correctly extracted by a POSIX-compatible <c>tar</c>
-      program (such as Solaris <c>tar</c>), not by GNU tar.</p>
-    <p>File have longer names than 256 bytes cannot be stored at all.</p>
-    <p>The filename of the file a symbolic link points is always limited
-      to 100 characters.</p>
+    <title>Limitations</title>
+    <list type="bulleted">
+      <item>
+        <p>For maximum compatibility, it is safe to archive files with names
+          up to 100 characters in length. Such tar files can generally be
+          extracted by any <c>tar</c> program.</p>
+      </item>
+      <item>
+        <p>For filenames exceeding 100 characters in length, the resulting tar
+          file can only be correctly extracted by a POSIX-compatible <c>tar</c>
+          program (such as Solaris <c>tar</c> or a modern GNU <c>tar</c>).</p>
+      </item>
+      <item>
+        <p>Files with longer names than 256 bytes cannot be stored.</p>
+      </item>
+      <item>
+        <p>The file name a symbolic link points is always limited
+          to 100 characters.</p>
+      </item>
+    </list>
   </section>
+
   <funcs>
     <func>
       <name>add(TarDescriptor, Filename, Options) -> RetValue</name>
-      <fsummary>Add a file to an open tar file</fsummary>
+      <fsummary>Add a file to an open tar file.</fsummary>
       <type>
         <v>TarDescriptor = term()</v>
         <v>Filename = filename()</v>
         <v>Options = [Option]</v>
         <v>Option = dereference|verbose|{chunks,ChunkSize}</v>
-	<v>ChunkSize = positive_integer()</v>
+        <v>ChunkSize = positive_integer()</v>
         <v>RetValue = ok|{error,{Filename,Reason}}</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <marker id="add"></marker><c>add/3</c> function adds
-           a file to a tar file that has been opened for writing by
-          <seealso marker="#open">open/1</seealso>.</p>
+        <p>Adds a file to a tar file that has been opened for writing by
+          <seealso marker="#open/2"><c>open/1</c></seealso>.</p>
+        <p>Options:</p>
         <taglist>
           <tag><c>dereference</c></tag>
           <item>
-            <p>By default, symbolic links will be stored as symbolic links
-              in the tar file. Use the <c>dereference</c> option to override the
-              default and store the file that the symbolic link points to into
-              the tar file.</p>
+            <p>By default, symbolic links are stored as symbolic links
+              in the tar file. To override the default and store the file
+              that the symbolic link points to into the tar file, use
+              option <c>dereference</c>.</p>
           </item>
           <tag><c>verbose</c></tag>
           <item>
-            <p>Print an informational message about the file being added.</p>
+            <p>Prints an informational message about the added file.</p>
+          </item>
+          <tag><c>{chunks,ChunkSize}</c></tag>
+          <item>
+            <p>Reads data in parts from the file. This is intended for
+              memory-limited machines that, for example, builds a tar file
+              on a remote machine over SFTP, see
+              <seealso marker="ssh:ssh_sftp#open_tar/3">
+              <c>ssh_sftp:open_tar/3</c></seealso>.</p>
           </item>
-	  <tag><c>{chunks,ChunkSize}</c></tag>
-	  <item>
-	    <p>Read data in parts from the file. This is intended for memory-limited
-	    machines that for example builds a tar file on a remote machine over
-	    <seealso marker="ssh:ssh_sftp#open_tar/3">sftp</seealso>.</p>
-	  </item>
         </taglist>
       </desc>
     </func>
+
     <func>
-      <name>add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue </name>
-      <fsummary>Add a file to an open tar file</fsummary>
+      <name>add(TarDescriptor, FilenameOrBin, NameInArchive, Options) ->
+        RetValue </name>
+      <fsummary>Add a file to an open tar file.</fsummary>
       <type>
         <v>TarDescriptor = term()</v>
         <v>FilenameOrBin = filename()|binary()</v>
@@ -150,53 +179,55 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <c>add/4</c> function adds a file to a tar file
-          that has been opened for writing by
-          <seealso marker="#open">open/1</seealso>. It accepts the same
-          options as <seealso marker="#add">add/3</seealso>.</p>
-        <p><c>NameInArchive</c> is the name under which the file will
-          be stored in the tar file. That is the name that the file will
-          get when it will be extracted from the tar file.</p>
+        <p>Adds a file to a tar file that has been opened for writing by
+          <seealso marker="#open/2"><c>open/2</c></seealso>. This function
+          accepts the same options as
+          <seealso marker="#add/3"><c>add/3</c></seealso>.</p>
+        <p><c>NameInArchive</c> is the name under which the file becomes
+          stored in the tar file. The file gets this name when it is
+          extracted from the tar file.</p>
       </desc>
     </func>
+
     <func>
       <name>close(TarDescriptor)</name>
-      <fsummary>Close an open tar file</fsummary>
+      <fsummary>Close an open tar file.</fsummary>
       <type>
         <v>TarDescriptor = term()</v>
       </type>
       <desc>
-        <p>The <marker id="close"></marker><c>close/1</c> function
-          closes a tar file
-          opened by <seealso marker="#open">open/1</seealso>.</p>
+        <p>Closes a tar file
+          opened by <seealso marker="#open/2"><c>open/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
       <name>create(Name, FileList) ->RetValue </name>
-      <fsummary>Create a tar archive</fsummary>
+      <fsummary>Create a tar archive.</fsummary>
       <type>
         <v>Name = filename()</v>
-        <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]</v>
+        <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive,
+          Filename}]</v>
         <v>Filename = filename()</v>
         <v>NameInArchive = filename()</v>
         <v>RetValue = ok|{error,{Name,Reason}}</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <marker id="create_2"></marker><c>create/2</c> function
-          creates a tar file and
-          archives the files whose names are given in <c>FileList</c> into it.
-          The files may either be read from disk or given as
-          binaries.</p>
+        <p>Creates a tar file and archives the files whose names are specified
+          in <c>FileList</c> into it. The files can either be read from disk
+          or be specified as binaries.</p>
       </desc>
     </func>
+
     <func>
       <name>create(Name, FileList, OptionList)</name>
-      <fsummary>Create a tar archive with options</fsummary>
+      <fsummary>Create a tar archive with options.</fsummary>
       <type>
         <v>Name = filename()</v>
-	<v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]</v>
-	<v>Filename = filename()</v>
+        <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive,
+          Filename}]</v>
+        <v>Filename = filename()</v>
         <v>NameInArchive = filename()</v>
         <v>OptionList = [Option]</v>
         <v>Option = compressed|cooked|dereference|verbose</v>
@@ -204,68 +235,66 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <marker id="create_3"></marker><c>create/3</c> function
-          creates a tar file and archives the files whose names are given
-          in <c>FileList</c> into it. The files may either be read from
-          disk or given as binaries.</p>
-        <p>The options in <c>OptionList</c> modify the defaults as follows.
-          </p>
+        <p>Creates a tar file and archives the files whose names are specified
+          in <c>FileList</c> into it. The files can either be read from disk
+          or be specified as binaries.</p>
+        <p>The options in <c>OptionList</c> modify the defaults as follows:</p>
         <taglist>
           <tag><c>compressed</c></tag>
           <item>
-            <p>The entire tar file will be compressed, as if it has
+            <p>The entire tar file is compressed, as if it has
               been run through the <c>gzip</c> program. To abide to the
-              convention that a compressed tar file should end in "<c>.tar.gz</c>" or
-              "<c>.tgz</c>", you'll need to add the appropriate extension yourself.</p>
+              convention that a compressed tar file is to end in
+              "<c>.tar.gz</c>" or "<c>.tgz</c>", add the appropriate
+              extension.</p>
           </item>
           <tag><c>cooked</c></tag>
           <item>
-            <p>By default, the <c>open/2</c> function will open the tar file
-              in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
-              file server to be used. Adding <c>cooked</c> to the mode list will 
-              override the default and open the tar file without the <c>raw</c>
-              option.</p>
+            <p>By default, function <c>open/2</c> opens the tar file in
+              <c>raw</c> mode, which is faster but does not allow a remote
+              (Erlang) file server to be used. Adding <c>cooked</c> to the
+              mode list overrides the default and opens the tar file without
+              option <c>raw</c>.</p>
           </item>
           <tag><c>dereference</c></tag>
           <item>
-            <p>By default, symbolic links will be stored as symbolic links
-              in the tar file. Use the <c>dereference</c> option to override the
-              default and store the file that the symbolic link points to into
-              the tar file.</p>
+            <p>By default, symbolic links are stored as symbolic links in
+              the tar file. To override the default and store the file that
+              the symbolic link points to into the tar file, use
+              option <c>dereference</c>.</p>
           </item>
           <tag><c>verbose</c></tag>
           <item>
-            <p>Print an informational message about each file being added.</p>
+            <p>Prints an informational message about each added file.</p>
           </item>
         </taglist>
       </desc>
     </func>
+
     <func>
       <name>extract(Name) -> RetValue</name>
-      <fsummary>Extract all files from a tar file</fsummary>
+      <fsummary>Extract all files from a tar file.</fsummary>
       <type>
         <v>Name = filename()</v>
         <v>RetValue = ok|{error,{Name,Reason}}</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <marker id="extract_1"></marker><c>extract/1</c> function
-          extracts all files from a tar archive.</p>
-        <p>If the <c>Name</c> argument is given as "<c>{binary,Binary}</c>",
-          the contents of the binary is assumed to be a tar archive.
-          </p>
-        <p>If the <c>Name</c> argument is given as "<c>{file,Fd}</c>",
-          <c>Fd</c> is assumed to be a file descriptor returned from
-          the <c>file:open/2</c> function.
-          </p>
-        <p>Otherwise, <c>Name</c> should be a filename.</p>
+        <p>Extracts all files from a tar archive.</p>
+        <p>If argument <c>Name</c> is specified as <c>{binary,Binary}</c>,
+          the contents of the binary is assumed to be a tar archive.</p>
+        <p>If argument <c>Name</c> is specified as <c>{file,Fd}</c>,
+          <c>Fd</c> is assumed to be a file descriptor returned from function
+          <c>file:open/2</c>.</p>
+        <p>Otherwise, <c>Name</c> is to be a filename.</p>
       </desc>
     </func>
+
     <func>
       <name>extract(Name, OptionList)</name>
-      <fsummary>Extract files from a tar file</fsummary>
+      <fsummary>Extract files from a tar file.</fsummary>
       <type>
-        <v>Name = filename() | {binary,Binary} | {file,Fd}  </v>
+        <v>Name = filename() | {binary,Binary} | {file,Fd}</v>
         <v>Binary = binary()</v>
         <v>Fd = file_descriptor()</v>
         <v>OptionList = [Option]</v>
@@ -278,272 +307,263 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <marker id="extract_2"></marker><c>extract/2</c> function
-          extracts files from a tar archive.</p>
-        <p>If the <c>Name</c> argument is given as "<c>{binary,Binary}</c>",
-          the contents of the binary is assumed to be a tar archive.
-          </p>
-        <p>If the <c>Name</c> argument is given as "<c>{file,Fd}</c>",
-          <c>Fd</c> is assumed to be a file descriptor returned from
-          the <c>file:open/2</c> function.
-          </p>
-        <p>Otherwise, <c>Name</c> should be a filename.
-          </p>
+        <p>Extracts files from a tar archive.</p>
+        <p>If argument <c>Name</c> is specified as <c>{binary,Binary}</c>,
+          the contents of the binary is assumed to be a tar archive.</p>
+        <p>If argument <c>Name</c> is specified as <c>{file,Fd}</c>,
+          <c>Fd</c> is assumed to be a file descriptor returned from function
+          <c>file:open/2</c>.</p>
+        <p>Otherwise, <c>Name</c> is to be a filename.</p>
         <p>The following options modify the defaults for the extraction as
-          follows.</p>
+          follows:</p>
         <taglist>
           <tag><c>{cwd,Cwd}</c></tag>
           <item>
-            <p>Files with relative filenames will by default be extracted
-              to the current working directory.
-              Given the <c>{cwd,Cwd}</c> option, the <c>extract/2</c> function
-              will extract into the directory <c>Cwd</c> instead of to the current
-              working directory.</p>
+            <p>Files with relative filenames are by default extracted
+              to the current working directory. With this option, files are
+              instead extracted into directory <c>Cwd</c>.</p>
           </item>
           <tag><c>{files,FileList}</c></tag>
           <item>
-            <p>By default, all files will be extracted from the tar file.
-              Given the <c>{files,Files}</c> option, the <c>extract/2</c> function
-              will only extract the files whose names are included in <c>FileList</c>.</p>
+            <p>By default, all files are extracted from the tar file. With
+              this option, only those files are extracted whose names are
+              included in <c>FileList</c>.</p>
           </item>
           <tag><c>compressed</c></tag>
           <item>
-            <p>Given the <c>compressed</c> option, the <c>extract/2</c>
-              function will uncompress the file while extracting
-              If the tar file is not actually compressed, the <c>compressed</c>
-              will effectively be ignored.</p>
+            <p>With this option, the file is uncompressed while extracting.
+              If the tar file is not compressed, this option is ignored.</p>
           </item>
           <tag><c>cooked</c></tag>
           <item>
-            <p>By default, the <c>open/2</c> function will open the tar file
-              in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
-              file server to be used. Adding <c>cooked</c> to the mode list will 
-              override the default and open the tar file without the <c>raw</c>
-              option.</p>
+            <p>By default, function <c>open/2</c> function opens the tar file
+              in <c>raw</c> mode, which is faster but does not allow a remote
+              (Erlang) file server to be used. Adding <c>cooked</c> to the mode
+              list overrides the default and opens the tar file without option
+              <c>raw</c>.</p>
           </item>
           <tag><c>memory</c></tag>
           <item>
-            <p>Instead of extracting to a directory, the memory option will
-	      give the result  as  a  list  of  tuples  {Filename, Binary}, where
-	      Binary is a binary containing the extracted data of the file named
-	      Filename in the tar file.</p>
+            <p>Instead of extracting to a directory, this option gives the
+	      result as a list of tuples <c>{Filename, Binary}</c>, where
+	      <c>Binary</c> is a binary containing the extracted data of the
+              file named <c>Filename</c> in the tar file.</p>
           </item>
           <tag><c>keep_old_files</c></tag>
           <item>
-            <p>By default, all existing files with the same name as file in
-              the tar file will be overwritten
-              Given the <c>keep_old_files</c> option, the <c>extract/2</c> function
-              will not overwrite any existing files.</p>
+            <p>By default, all existing files with the same name as files in
+              the tar file are overwritten. With this option, existing
+              files are not overwriten.</p>
           </item>
           <tag><c>verbose</c></tag>
           <item>
-            <p>Print an informational message as each file is being extracted.</p>
+            <p>Prints an informational message for each extracted file.</p>
           </item>
         </taglist>
       </desc>
     </func>
+
     <func>
       <name>format_error(Reason) -> string()</name>
-      <fsummary>Convert error term to a readable string</fsummary>
+      <fsummary>Convert error term to a readable string.</fsummary>
       <type>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <marker id="format_error_1"></marker><c>format_error/1</c>
-          function converts
-          an error reason term to a human-readable error message string.</p>
+        <p>Cconverts an error reason term to a human-readable error message
+          string.</p>
       </desc>
     </func>
+
     <func>
-      <name>open(Name, OpenModeList) -> RetValue</name>
-      <fsummary>Open a tar file for writing.</fsummary>
+      <name>init(UserPrivate, AccessMode, Fun) ->
+        {ok,TarDescriptor} | {error,Reason}</name>
+      <fsummary>Create a <c>TarDescriptor</c> used in subsequent tar operations
+        when defining own low-level storage access functions.</fsummary>
       <type>
-        <v>Name = filename()</v>
-        <v>OpenModeList = [OpenMode]</v>
-        <v>Mode = write|compressed|cooked</v>
-        <v>RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}</v>
-	<v>TarDescriptor = term()</v>
+        <v>UserPrivate = term()</v>
+        <v>AccessMode = [write] | [read]</v>
+        <v>Fun when AccessMode is [write] =
+          fun(write, {UserPrivate,DataToWrite})->...;
+          (position,{UserPrivate,Position})->...;
+          (close, UserPrivate)->... end</v>
+        <v>Fun when AccessMode is [read] =
+          fun(read2, {UserPrivate,Size})->...;
+          (position,{UserPrivate,Position})->...;
+          (close,   UserPrivate)->... end</v>
+        <v>TarDescriptor = term()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <marker id="open"></marker><c>open/2</c> function creates
-         a tar file for writing.
-        (Any existing file with the same name will be truncated.)</p>
-        <p>By convention, the name of a tar file should end in "<c>.tar</c>".
-          To abide to the convention, you'll need to add "<c>.tar</c>" yourself
-          to the name.</p>
-        <p>Except for the <c>write</c> atom the following atoms
-	may be added to <c>OpenModeList</c>:</p>
+        <p>The <c>Fun</c> is the definition of what to do when the different
+          storage operations functions are to be called from the higher tar
+          handling functions (such as <c>add/3</c>, <c>add/4</c>, and
+          <c>close/1</c>).</p>
+        <p>The <c>Fun</c> is called when the tar function wants to do a
+          low-level operation, like writing a block to a file. The <c>Fun</c>
+          is called as <c>Fun(Op, {UserPrivate,Parameters...})</c>, where
+          <c>Op</c> is the operation name, <c>UserPrivate</c> is the term
+          passed as the first argument to <c>init/1</c> and
+          <c>Parameters...</c> are the data added by the tar function to be
+          passed down to the storage handling function.</p>
+        <p>Parameter <c>UserPrivate</c> is typically the result of opening a
+          low-level structure like a file descriptor or an SFTP channel id.
+          The different <c>Fun</c> clauses operate on that very term.</p>
+        <p>The following are the fun clauses parameter lists:</p>
         <taglist>
-          <tag><c>compressed</c></tag>
+          <tag><c>(write, {UserPrivate,DataToWrite})</c></tag>
           <item>
-            <p>The entire tar file will be compressed, as if it has
-              been run through the <c>gzip</c> program. To abide to the
-              convention that a compressed tar file should end in "<c>.tar.gz</c>" or
-              "<c>.tgz</c>", you'll need to add the appropriate extension yourself.</p>
+            <p>Writes term <c>DataToWrite</c> using <c>UserPrivate</c>.</p>
           </item>
-          <tag><c>cooked</c></tag>
+          <tag><c>(close, UserPrivate)</c></tag>
+          <item>
+            <p>Closes the access.</p>
+          </item>
+          <tag><c>(read2, {UserPrivate,Size})</c></tag>
           <item>
-            <p>By default, the <c>open/2</c> function will open the tar file
-              in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
-              file server to be used. Adding <c>cooked</c> to the mode list will 
-              override the default and open the tar file without the <c>raw</c>
-              option.</p>
+            <p>Reads using <c>UserPrivate</c> but only <c>Size</c> bytes.
+            Notice that there is only an arity-2 read function, not an arity-1
+            function.</p>
+          </item>
+          <tag><c>(position,{UserPrivate,Position})</c></tag>
+          <item>
+            <p>Sets the position of <c>UserPrivate</c> as defined for files in
+              <seealso marker="kernel:file#position-2">
+              <c>file:position/2</c></seealso></p>
           </item>
         </taglist>
-        <p>Use the <seealso marker="#add">add/3,4</seealso> functions
-          to add one file at the time into an opened tar file. When you are
-          finished adding files, use the <seealso marker="#close">close</seealso>
-          function to close the tar file.</p>
+        <p><em>Example:</em></p>
+        <p>The following is a complete <c>Fun</c> parameter for reading and
+          writing on files using the
+          <seealso marker="kernel:file"><c>file</c></seealso> module:</p>
+        <code type="none">
+ExampleFun = 
+   fun(write, {Fd,Data}) ->  file:write(Fd, Data);
+      (position, {Fd,Pos}) -> file:position(Fd, Pos);
+      (read2, {Fd,Size}) -> file:read(Fd, Size);
+      (close, Fd) -> file:close(Fd)
+   end</code>
+        <p>Here <c>Fd</c> was specified to function <c>init/3</c> as:</p>
+        <code>
+{ok,Fd} = file:open(Name, ...).
+{ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),</code>
+        <p><c>TarDesc</c> is then used:</p>
+        <code>
+erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
+...,
+erl_tar:close(TarDesc)</code>
+        <p>When the <c>erl_tar</c> core wants to, for example, write a piece
+          of <c>Data</c>, it would call
+          <c>ExampleFun(write, {UserPrivate,Data})</c>.</p>
+        <note>
+          <p>This example with the <c>file</c> module operations is
+            not necessary to use directly, as that is what function
+            <seealso marker="#open/2"><c>open/2</c></seealso> in principle
+            does.</p>
+        </note>
         <warning>
-          <p>The <c>TarDescriptor</c> term is not a file descriptor.
-            You should not rely on the specific contents of the <c>TarDescriptor</c>
-            term, as it may change in future versions as more features are added
-            to the <c>erl_tar</c> module.</p>
+          <p>The <c>TarDescriptor</c> term is not a file descriptor. You are
+            advised not to rely on the specific contents of this term, as it
+            can change in future Erlang/OTP releases when more features are
+            added to this module.</p>
         </warning>
       </desc>
     </func>
 
     <func>
-      <name>init(UserPrivate, AccessMode, Fun) -> {ok,TarDescriptor} | {error,Reason}
-</name>
-      <fsummary>Creates a TarDescriptor used in subsequent tar operations when
-      defining own low-level storage access functions
-      </fsummary>
+      <name>open(Name, OpenModeList) -> RetValue</name>
+      <fsummary>Open a tar file for writing.</fsummary>
       <type>
-	<v>UserPrivate = term()</v>
-	<v>AccessMode = [write] | [read]</v>
-	<v>Fun when AccessMode is [write] = fun(write,   {UserPrivate,DataToWrite})->...;
-	                                       (position,{UserPrivate,Position})->...;
-	                                       (close,   UserPrivate)->...
-					    end
-        </v>
-	<v>Fun when AccessMode is [read] = fun(read2,   {UserPrivate,Size})->...;
-	                                      (position,{UserPrivate,Position})->...;
-	                                      (close,   UserPrivate)->...
-					    end
-        </v>
-	<v>TarDescriptor = term()</v>
-	<v>Reason = term()</v>
+        <v>Name = filename()</v>
+        <v>OpenModeList = [OpenMode]</v>
+        <v>Mode = write|compressed|cooked</v>
+        <v>RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}</v>
+        <v>TarDescriptor = term()</v>
+        <v>Reason = term()</v>
       </type>
       <desc>
-	<p>The <c>Fun</c> is the definition of what to do when the different
-	storage operations functions are to be called from the higher tar
-	handling functions (<c>add/3</c>, <c>add/4</c>, <c>close/1</c>...).
-	</p>
-	<p>The <c>Fun</c> will be called when the tar function wants to do
-	a low-level operation, like writing a block to a file.  The Fun is called
-	as <c>Fun(Op,{UserPrivate,Parameters...})</c> where <c>Op</c> is the operation name,
-	<c>UserPrivate</c> is the term passed as the first argument to <c>init/1</c> and
-	<c>Parameters...</c> are the data added by the tar function to be passed down to
-	the storage handling function.
-	</p>
-	<p>The parameter <c>UserPrivate</c> is typically the result of opening a low level
-	structure like a file descriptor, a sftp channel id or such.  The different <c>Fun</c>
-	clauses operates on that very term.
-	</p>
-	<p>The fun clauses parameter lists are:</p>
-	<taglist>
-	  <tag><c>(write, {UserPrivate,DataToWrite})</c></tag>
-	  <item>Write the term <c>DataToWrite</c> using <c>UserPrivate</c></item>
-	  <tag><c>(close, UserPrivate)</c></tag>
-	  <item>Close the access.</item>
-	  <tag><c>(read2, {UserPrivate,Size})</c></tag>
-	  <item>Read using <c>UserPrivate</c> but only <c>Size</c> bytes. Note that there is
-	  only an arity-2 read function, not an arity-1
-	  </item>
-	  <tag><c> (position,{UserPrivate,Position})</c></tag>
-	  <item>Sets the position of <c>UserPrivate</c> as defined for files in <seealso marker="kernel:file#position-2">file:position/2</seealso></item>
-	  <tag><c></c></tag>
-	  <item></item>
-	</taglist>
-	<p>A complete <c>Fun</c> parameter for reading and writing on files using the
-	<seealso marker="kernel:file">file module</seealso> could be:
-	</p>
-	<code type="none">
-	  ExampleFun = 
-	     fun(write, {Fd,Data}) ->  file:write(Fd, Data);
-	        (position, {Fd,Pos}) -> file:position(Fd, Pos);
-	        (read2, {Fd,Size}) -> file:read(Fd,Size);
-	        (close, Fd) -> file:close(Fd)
-	     end
-	</code>
-	<p>where <c>Fd</c> was given to the <c>init/3</c> function as:</p>
-	<code>
-	  {ok,Fd} = file:open(Name,...).
-	  {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
-	</code>
-	<p>The <c>TarDesc</c> is then used:</p>
-	<code>
-	  erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
-	  ....,
-	  erl_tar:close(TarDesc)
-	</code>
-	<p>When the erl_tar core wants to e.g. write a piece of Data, it would call
-	<c>ExampleFun(write,{UserPrivate,Data})</c>.
-	</p>
-	<note>
-	  <p>The example above with <c>file</c> module operations is not necessary to
-	  use directly since that is what the <seealso marker="#open">open</seealso> function
-	  in principle does.
-	  </p>
-	</note>
+        <p>Creates a tar file for writing (any existing file with the same
+          name is truncated).</p>
+        <p>By convention, the name of a tar file is to end in "<c>.tar</c>".
+          To abide to the convention, add "<c>.tar</c>" to the name.</p>
+        <p>Except for the <c>write</c> atom, the following atoms
+          can be added to <c>OpenModeList</c>:</p>
+        <taglist>
+          <tag><c>compressed</c></tag>
+          <item>
+            <p>The entire tar file is compressed, as if it has been run
+              through the <c>gzip</c> program. To abide to the convention
+              that a compressed tar file is to end in "<c>.tar.gz</c>" or
+              "<c>.tgz</c>", add the appropriate extension.</p>
+          </item>
+          <tag><c>cooked</c></tag>
+          <item>
+            <p>By default, the tar file is opened in <c>raw</c> mode, which is
+              faster but does not allow a remote (Erlang) file server to be
+              used. Adding <c>cooked</c> to the mode list overrides the
+              default and opens the tar file without option <c>raw</c>.</p>
+          </item>
+        </taglist>
+        <p>To add one file at the time into an opened tar file, use function
+          <seealso marker="#add/3"><c>add/3,4</c></seealso>. When you are
+          finished adding files, use function <seealso marker="#close/1">
+          <c>close/1</c></seealso> to close the tar file.</p>
         <warning>
-          <p>The <c>TarDescriptor</c> term is not a file descriptor.
-            You should not rely on the specific contents of the <c>TarDescriptor</c>
-            term, as it may change in future versions as more features are added
-            to the <c>erl_tar</c> module.</p>
+          <p>The <c>TarDescriptor</c> term is not a file descriptor. You are
+            advised not to rely on the specific contents of this term, as it
+            can change in future Erlang/OTP releases when more features are
+            added to this module..</p>
         </warning>
       </desc>
     </func>
 
     <func>
       <name>table(Name) -> RetValue</name>
-      <fsummary>Retrieve the name of all files in a tar file</fsummary>
+      <fsummary>Retrieve the name of all files in a tar file.</fsummary>
       <type>
         <v>Name = filename()</v>
         <v>RetValue = {ok,[string()]}|{error,{Name,Reason}}</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <marker id="table_1"></marker><c>table/1</c> function
-          retrieves the names of all files in the tar file <c>Name</c>.</p>
+        <p>Retrieves the names of all files in the tar file <c>Name</c>.</p>
       </desc>
     </func>
+
     <func>
       <name>table(Name, Options)</name>
-      <fsummary>Retrieve name and information of all files in a tar file</fsummary>
+      <fsummary>Retrieve name and information of all files in a tar file.
+      </fsummary>
       <type>
         <v>Name = filename()</v>
       </type>
       <desc>
-        <p>The <marker id="table_2"></marker><c>table/2</c> function
-          retrieves the names of all files in the tar file <c>Name</c>.</p>
+        <p>Retrieves the names of all files in the tar file <c>Name</c>.</p>
       </desc>
     </func>
+
     <func>
       <name>t(Name)</name>
-      <fsummary>Print the name of each file in a tar file</fsummary>
+      <fsummary>Print the name of each file in a tar file.</fsummary>
       <type>
         <v>Name = filename()</v>
       </type>
       <desc>
-        <p>The <marker id="t_1"></marker><c>t/1</c> function prints the names
-          of all files in the tar file <c>Name</c> to the Erlang shell.
-          (Similar to "<c>tar&nbsp;t</c>".)</p>
+        <p>Prints the names of all files in the tar file <c>Name</c> to the
+          Erlang shell (similar to "<c>tar&nbsp;t</c>").</p>
       </desc>
     </func>
+
     <func>
       <name>tt(Name)</name>
-      <fsummary>Print name and information for each file in a tar file</fsummary>
+      <fsummary>Print name and information for each file in a tar file.
+      </fsummary>
       <type>
         <v>Name = filename()</v>
       </type>
       <desc>
-        <p>The <marker id="tt_1"></marker><c>tt/1</c> function prints
-          names and
-          information about all files in the tar file <c>Name</c> to
-          the Erlang shell. (Similar to "<c>tar&nbsp;tv</c>".)</p>
+        <p>Prints names and information about all files in the tar file
+          <c>Name</c> to the Erlang shell (similar to "<c>tar&nbsp;tv</c>").</p>
       </desc>
     </func>
   </funcs>