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, 159 insertions, 119 deletions

diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml
index f284a7596c..2a413835d0 100644
--- a/lib/stdlib/doc/src/filename.xml
+++ b/lib/stdlib/doc/src/filename.xml
@@ -25,27 +25,37 @@
     <title>filename</title>
     <prepared>Kenneth Lundin</prepared>
     <docno>1</docno>
-    <date>97-11-13</date>
+    <date>1997-11-13</date>
     <rev>B</rev>
   </header>
   <module>filename</module>
-  <modulesummary>Filename Manipulation Functions</modulesummary>
+  <modulesummary>Filename manipulation functions.</modulesummary>
   <description>
-    <p>The module <c>filename</c> provides a number of useful functions
-      for analyzing and manipulating file names. These functions are
+    <p>This module provides functions
+      for analyzing and manipulating filenames. These functions are
       designed so that the Erlang code can work on many different
-      platforms with different formats for file names. With file name
-      is meant all strings that can be used to denote a file. They can
-      be short relative names like <c>foo.erl</c>, very long absolute
-      name which include a drive designator and directory names like
+      platforms with different filename formats. With filename
+      is meant all strings that can be used to denote a file. The filename
+      can be a short relative name like <c>foo.erl</c>, a long absolute
+      name including a drive designator, a directory name like
       <c>D:\usr/local\bin\erl/lib\tools\foo.erl</c>, or any variations
       in between.</p>
-    <p>In Windows, all functions return file names with forward slashes
-      only, even if the arguments contain back slashes. Use
-      <c>join/1</c> to normalize a file name by removing redundant
-      directory separators.</p>
-    <p>The module supports raw file names in the way that if a binary is present, or the file name cannot be interpreted according to the return value of 
-    <seealso marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>, a raw file name will also be returned. For example filename:join/1 provided with a path component being a binary (and also not being possible to interpret under the current native file name encoding) will result in a raw file name being returned (the join operation will have been performed of course). For more information about raw file names, see the <seealso marker="kernel:file">file</seealso> module.</p>
+
+    <p>In Windows, all functions return filenames with forward slashes
+      only, even if the arguments contain backslashes. To normalize a
+      filename by removing redundant directory separators, use
+      <seealso marker="#join/1"><c>join/1</c></seealso>.</p>
+
+    <p>The module supports raw filenames in the way that if a binary is
+      present, or the filename cannot be interpreted according to the return
+      value of <seealso marker="kernel:file#native_name_encoding/0">
+      <c>file:native_name_encoding/0</c></seealso>, a raw filename is also
+      returned. For example, <c>join/1</c> provided with a path component
+      that is a binary (and cannot be interpreted under the current
+      native filename encoding) results in a raw filename that is returned
+      (the join operation is performed of course). For more information
+      about raw filenames, see the
+      <seealso marker="kernel:file"><c>file</c></seealso> module.</p>
   </description>
   <datatypes>
       <datatype>
@@ -56,13 +66,14 @@
   <funcs>
     <func>
       <name name="absname" arity="1"/>
-      <fsummary>Convert a filename to an absolute name, relative the working directory</fsummary>
+      <fsummary>Convert a filename to an absolute name, relative the working
+        directory.</fsummary>
       <desc>
-        <p>Converts a relative <c><anno>Filename</anno></c> and returns an absolute
-          name. No attempt is made to create the shortest absolute name,
-          because this can give incorrect results on file systems which
+        <p>Converts a relative <c><anno>Filename</anno></c> and returns an
+          absolute name. No attempt is made to create the shortest absolute
+          name, as this can give incorrect results on file systems that
           allow links.</p>
-        <p>Unix examples:</p>
+        <p><em>Unix examples:</em></p>
         <pre>
 1> <input>pwd().</input>
 "/usr/local"
@@ -72,7 +83,7 @@
 "/usr/local/../x"
 4> <input>filename:absname("/").</input>
 "/"</pre>
-        <p>Windows examples:</p>
+        <p><em>Windows examples:</em></p>
         <pre>
 1> <input>pwd().</input>
 "D:/usr/local"
@@ -84,28 +95,32 @@
 "D:/"</pre>
       </desc>
     </func>
+
     <func>
       <name name="absname" arity="2"/>
-      <fsummary>Convert a filename to an absolute name, relative a specified directory</fsummary>
+      <fsummary>Convert a filename to an absolute name, relative a specified
+        directory.</fsummary>
       <desc>
-        <p>This function works like <c>absname/1</c>, except that
-          the directory to which the file name should be made relative
-          is given explicitly in the <c><anno>Dir</anno></c> argument.</p>
+        <p>Same as <seealso marker="#absname/1"><c>absname/1</c></seealso>,
+          except that the directory to which the filename is to be made
+          relative is specified in argument <c><anno>Dir</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="absname_join" arity="2"/>
-      <fsummary>Join an absolute directory with a relative filename</fsummary>
+      <fsummary>Join an absolute directory with a relative filename.</fsummary>
       <desc>
-        <p>Joins an absolute directory with a relative filename.
-          Similar to <c>join/2</c>, but on platforms with tight
-          restrictions on raw filename length and no support for
-          symbolic links (read: VxWorks), leading parent directory
-          components in <c><anno>Filename</anno></c> are matched against trailing
-          directory components in <c><anno>Dir</anno></c> so they can be removed
-          from the result - minimizing its length.</p>
+        <p>Joins an absolute directory with a relative filename. Similar to
+          <seealso marker="#join/2"><c>join/2</c></seealso>, but on platforms
+          with tight restrictions on raw filename length and no support for
+          symbolic links (read: VxWorks), leading parent directory components
+          in <c><anno>Filename</anno></c> are matched against trailing
+          directory components in <c><anno>Dir</anno></c> so they can be
+          removed from the result - minimizing its length.</p>
       </desc>
     </func>
+
     <func>
       <name name="basedir" arity="2"/>
       <fsummary>Equivalent to <c>basedir(<anno>Type</anno>,<anno>Application</anno>,#{})</c>.</fsummary>
@@ -121,11 +136,13 @@
       <fsummary></fsummary>
       <desc><marker id="basedir-3"/>
           <p>
-              Returns a suitable path, or paths, for a given type.
-              If <c>os</c> is not set in <c><anno>Opts</anno></c> the function will default to
-              the native option, i.e. <c>'linux'</c>, <c>'darwin'</c> or <c>'windows'</c>, as understood
-              by <c>os:type/0</c>. Anything not recognized as <c>'darwin'</c> or <c>'windows'</c> is
-              interpreted as <c>'linux'</c>.</p>
+              Returns a suitable path, or paths, for a given type.  If
+              <c>os</c> is not set in <c><anno>Opts</anno></c> the
+              function will default to the native option, that is
+              <c>'linux'</c>, <c>'darwin'</c> or <c>'windows'</c>, as
+              understood by <c>os:type/0</c>. Anything not recognized
+              as <c>'darwin'</c> or <c>'windows'</c> is interpreted as
+              <c>'linux'</c>.</p>
           <p>
               The options <c>'author'</c> and <c>'version'</c> are only used with <c>'windows'</c> option mode.
           </p>
@@ -257,11 +274,12 @@ true
     </func>
     <func>
       <name name="basename" arity="1"/>
-      <fsummary>Return the last component of a filename</fsummary>
+      <fsummary>Return the last component of a filename.</fsummary>
       <desc>
         <p>Returns the last component of <c><anno>Filename</anno></c>, or
-          <c><anno>Filename</anno></c> itself if it does not contain any directory
-          separators.</p>
+          <c><anno>Filename</anno></c> itself if it does not contain any
+          directory separators.</p>
+        <p><em>Examples:</em></p>
         <pre>
 5> <input>filename:basename("foo").</input>
 "foo"
@@ -271,15 +289,18 @@ true
 []</pre>
       </desc>
     </func>
+
     <func>
       <name name="basename" arity="2"/>
-      <fsummary>Return the last component of a filename, stripped of the specified extension</fsummary>
+      <fsummary>Return the last component of a filename, stripped of the
+        specified extension.</fsummary>
       <desc>
-        <p>Returns the last component of <c><anno>Filename</anno></c> with the
-          extension <c><anno>Ext</anno></c> stripped. This function should be used
-          to remove a specific extension which might, or might not, be
-          there. Use <c>rootname(basename(Filename))</c> to remove an
-          extension that exists, but you are not sure which one it is.</p>
+        <p>Returns the last component of <c><anno>Filename</anno></c> with
+          extension <c><anno>Ext</anno></c> stripped. This function is to be
+          used to remove a (possible) specific extension. To remove an
+          existing extension when you are unsure which one it is, use
+          <c>rootname(basename(Filename))</c>.</p>
+        <p><em>Examples:</em></p>
         <pre>
 8> <input>filename:basename("~/src/kalle.erl", ".erl").</input>
 "kalle"
@@ -293,27 +314,32 @@ true
 "kalle"</pre>
       </desc>
     </func>
+
     <func>
       <name name="dirname" arity="1"/>
-      <fsummary>Return the directory part of a path name</fsummary>
+      <fsummary>Return the directory part of a path name.</fsummary>
       <desc>
         <p>Returns the directory part of <c><anno>Filename</anno></c>.</p>
+        <p><em>Examples:</em></p>
         <pre>
 13> <input>filename:dirname("/usr/src/kalle.erl").</input>
 "/usr/src"
 14> <input>filename:dirname("kalle.erl").</input>
-"."
-
+"."</pre>
+        <pre>
 5> <input>filename:dirname("\\usr\\src/kalle.erl").</input> % Windows
 "/usr/src"</pre>
       </desc>
     </func>
+
     <func>
       <name name="extension" arity="1"/>
-      <fsummary>Return the file extension</fsummary>
+      <fsummary>Return the file extension.</fsummary>
       <desc>
-        <p>Returns the file extension of <c><anno>Filename</anno></c>, including
-          the period. Returns an empty string if there is no extension.</p>
+        <p>Returns the file extension of <c><anno>Filename</anno></c>,
+          including the period. Returns an empty string if no extension
+          exists.</p>
+        <p><em>Examples:</em></p>
         <pre>
 15> <input>filename:extension("foo.erl").</input>
 ".erl"
@@ -321,69 +347,123 @@ true
 []</pre>
       </desc>
     </func>
+
+    <func>
+      <name name="find_src" arity="1"/>
+      <name name="find_src" arity="2"/>
+      <fsummary>Find the filename and compiler options for a module.</fsummary>
+      <desc>
+        <p>Finds the source filename and compiler options for a module.
+          The result can be fed to <seealso marker="compiler:compile#file/2">
+          <c>compile:file/2</c></seealso> to compile the file again.</p>
+        <warning><p>It is not recommended to use this function. If possible,
+          use the <seealso marker="beam_lib"><c>beam_lib(3)</c></seealso>
+          module to extract the abstract code format from the Beam file and
+          compile that instead.</p></warning>
+        <p>Argument <c><anno>Beam</anno></c>, which can be a string or an atom,
+          specifies either the module name or the path to the source
+          code, with or without extension <c>".erl"</c>. In either
+          case, the module must be known by the code server, that is,
+          <c>code:which(<anno>Module</anno>)</c> must succeed.</p>
+        <p><c><anno>Rules</anno></c> describes how the source directory can be
+          found when the object code directory is known. It is a list of
+          tuples <c>{<anno>BinSuffix</anno>, <anno>SourceSuffix</anno>}</c> and
+          is interpreted as follows: if the end of the directory name where the
+          object is located matches <c><anno>BinSuffix</anno></c>, then the
+          source code directory has the same name, but with
+          <c><anno>BinSuffix</anno></c> replaced by
+          <c><anno>SourceSuffix</anno></c>. <c><anno>Rules</anno></c> defaults
+          to:</p>
+        <code type="none">
+[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]</code>
+        <p>If the source file is found in the resulting directory, the function
+          returns that location together with <c><anno>Options</anno></c>.
+          Otherwise the next rule is tried, and so on.</p>
+        <p>The function returns <c>{<anno>SourceFile</anno>,
+          <anno>Options</anno>}</c> if it succeeds.
+          <c><anno>SourceFile</anno></c> is the absolute path to the source
+          file without extension <c>".erl"</c>. <c><anno>Options</anno></c>
+          includes the options that are necessary to recompile the file with
+          <c>compile:file/2</c>, but excludes options such as <c>report</c>
+          and <c>verbose</c>, which do not change the way code is generated.
+          The paths in options <c>{outdir, <anno>Path</anno>}</c> and
+          <c>{i, Path}</c> are guaranteed to be absolute.</p>
+      </desc>
+    </func>
+
     <func>
       <name name="flatten" arity="1"/>
-      <fsummary>Convert a filename to a flat string</fsummary>
+      <fsummary>Convert a filename to a flat string.</fsummary>
       <desc>
         <p>Converts a possibly deep list filename consisting of
           characters and atoms into the corresponding flat string
           filename.</p>
       </desc>
     </func>
+
     <func>
       <name name="join" arity="1"/>
-      <fsummary>Join a list of filename components with directory separators</fsummary>
+      <fsummary>Join a list of filename components with directory separators.
+      </fsummary>
       <desc>
-        <p>Joins a list of file name <c><anno>Components</anno></c> with directory
-          separators. If one of the elements of <c><anno>Components</anno></c>
-          includes an absolute path, for example <c>"/xxx"</c>,
+        <p>Joins a list of filename <c><anno>Components</anno></c> with
+          directory separators.
+          If one of the elements of <c><anno>Components</anno></c>
+          includes an absolute path, such as <c>"/xxx"</c>,
           the preceding elements, if any, are removed from the result.</p>
         <p>The result is "normalized":</p>
         <list type="bulleted">
           <item>Redundant directory separators are removed.</item>
           <item>In Windows, all directory separators are forward
-           slashes and the drive letter is in lower case.</item>
+            slashes and the drive letter is in lower case.</item>
         </list>
+        <p><em>Examples:</em></p>
         <pre>
 17> <input>filename:join(["/usr", "local", "bin"]).</input>
 "/usr/local/bin"
 18> <input>filename:join(["a/b///c/"]).</input>
-"a/b/c"
-
+"a/b/c"</pre>
+        <pre>
 6> <input>filename:join(["B:a\\b///c/"]).</input> % Windows
 "b:a/b/c"</pre>
       </desc>
     </func>
+
     <func>
       <name name="join" arity="2"/>
-      <fsummary>Join two filename components with directory separators</fsummary>
+      <fsummary>Join two filename components with directory separators.
+      </fsummary>
       <desc>
-        <p>Joins two file name components with directory separators. 
-          Equivalent to <c>join([<anno>Name1</anno>, <anno>Name2</anno>])</c>.</p>
+        <p>Joins two filename components with directory separators.
+          Equivalent to <c>join([<anno>Name1</anno>, <anno>Name2</anno>])</c>.
+        </p>
       </desc>
     </func>
+
     <func>
       <name name="nativename" arity="1"/>
-      <fsummary>Return the native form of a file path</fsummary>
+      <fsummary>Return the native form of a file path.</fsummary>
       <desc>
-        <p>Converts <c><anno>Path</anno></c> to a form accepted by the command shell
-          and native applications on the current platform. On Windows,
+        <p>Converts <c><anno>Path</anno></c> to a form accepted by the command
+          shell and native applications on the current platform. On Windows,
           forward slashes are converted to backward slashes. On all
-          platforms, the name is normalized as done by <c>join/1</c>.</p>
+          platforms, the name is normalized as done by
+          <seealso marker="#join/1"><c>join/1</c></seealso>.</p>
+        <p><em>Examples:</em></p>
         <pre>
 19> <input>filename:nativename("/usr/local/bin/").</input> % Unix
-"/usr/local/bin"
-
+"/usr/local/bin"</pre>
+        <pre>
 7> <input>filename:nativename("/usr/local/bin/").</input> % Windows
 "\\usr\\local\\bin"</pre>
       </desc>
     </func>
+
     <func>
       <name name="pathtype" arity="1"/>
-      <fsummary>Return the type of a path</fsummary>
+      <fsummary>Return the path type.</fsummary>
       <desc>
-        <p>Returns the type of path, one of <c>absolute</c>,
-          <c>relative</c>, or <c>volumerelative</c>.</p>
+        <p>Returns the path type, which is one of the following:</p>
         <taglist>
           <tag><c>absolute</c></tag>
           <item>
@@ -408,14 +488,16 @@ true
         </taglist>
       </desc>
     </func>
+
     <func>
       <name name="rootname" arity="1"/>
       <name name="rootname" arity="2"/>
-      <fsummary>Remove a filename extension</fsummary>
+      <fsummary>Remove a filename extension.</fsummary>
       <desc>
-        <p>Remove a filename extension. <c>rootname/2</c> works as
+        <p>Removes a filename extension. <c>rootname/2</c> works as
           <c>rootname/1</c>, except that the extension is removed only
           if it is <c><anno>Ext</anno></c>.</p>
+        <p><em>Examples:</em></p>
         <pre>
 20> <input>filename:rootname("/beam.src/kalle").</input>
 /beam.src/kalle"
@@ -427,12 +509,14 @@ true
 "/beam.src/foo.beam"</pre>
       </desc>
     </func>
+
     <func>
       <name name="split" arity="1"/>
-      <fsummary>Split a filename into its path components</fsummary>
+      <fsummary>Split a filename into its path components.</fsummary>
       <desc>
         <p>Returns a list whose elements are the path components of
           <c><anno>Filename</anno></c>.</p>
+        <p><em>Examples:</em></p>
         <pre>
 24> <input>filename:split("/usr/local/bin").</input>
 ["/","usr","local","bin"]
@@ -442,50 +526,6 @@ true
 ["a:/","msdev","include"]</pre>
       </desc>
     </func>
-    <func>
-      <name name="find_src" arity="1"/>
-      <name name="find_src" arity="2"/>
-      <fsummary>Find the filename and compiler options for a module</fsummary>
-      <desc>
-        <p>Finds the source filename and compiler options for a module.
-          The result can be fed to <c>compile:file/2</c> in order to
-          compile the file again.</p>
-
-	<warning><p>We don't recommend using this function. If possible,
-	use <seealso marker="beam_lib">beam_lib(3)</seealso> to extract
-	the abstract code format from the BEAM file and compile that
-	instead.</p></warning>
-
-        <p>The <c><anno>Beam</anno></c> argument, which can be a string or an atom,
-          specifies either the module name or the path to the source
-          code, with or without the <c>".erl"</c> extension. In either
-          case, the module must be known by the code server, i.e.
-          <c>code:which(<anno>Module</anno>)</c> must succeed.</p>
-        <p><c><anno>Rules</anno></c> describes how the source directory can be found,
-          when the object code directory is known. It is a list of
-          tuples <c>{<anno>BinSuffix</anno>, <anno>SourceSuffix</anno>}</c> and is interpreted
-          as follows: If the end of the directory name where the object
-          is located matches <c><anno>BinSuffix</anno></c>, then the source code
-          directory has the same name, but with <c><anno>BinSuffix</anno></c>
-          replaced by <c><anno>SourceSuffix</anno></c>. <c><anno>Rules</anno></c> defaults to:</p>
-        <code type="none">
-[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]</code>
-        <p>If the source file is found in the resulting directory, then
-          the function returns that location together with
-          <c><anno>Options</anno></c>. Otherwise, the next rule is tried, and so on.</p>
-
-        <p>The function returns <c>{<anno>SourceFile</anno>, <anno>Options</anno>}</c> if it succeeds.
-          <c><anno>SourceFile</anno></c> is the absolute path to the source file
-          without the <c>".erl"</c> extension. <c><anno>Options</anno></c> include
-          the options which are necessary to recompile the file with
-          <c>compile:file/2</c>, but excludes options such as
-          <c>report</c> or <c>verbose</c> which do not change the way
-          code is generated. The paths in the <c>{outdir, <anno>Path</anno>}</c>
-          and <c>{i, Path}</c> options are guaranteed to be
-          absolute.</p>
-
-      </desc>
-    </func>
   </funcs>
 </erlref>