[project @ 2002-06-27 12:17:47 by simonmar]

Improve the documentation for hierarchical libraries.

ghc/docs/users_guide/glasgow_exts.sgml

@@ -2385,38 +2385,38 @@ Assertion failures can be caught, see the documentation for the
       it extends the normally flat Haskell module namespace into a
       more flexible hierarchy of modules.</para>
 
-      <para>A module name in the extended syntax consists of a
-      sequence of components, each separated by a dot.  When searching
-      for an interface file (or a source file, in the case of GHCi or
-      when using <option>--make</option>) for an imported module, GHC
-      interprets the dot as a path separator.  So for example, if a
-      module <literal>A.B.C</literal> is imported, then for each
-      directory <literal>D</literal> on the search path (see the
-      <option>-i</option> option, <xref
-      linkend="options-finding-imports">), GHC will look in the
-      directory <literal>D/A/B</literal><footnote><para>On Windows,
-      this would be <literal>D\A\B</literal>.</para></footnote> for an
-      interface file called <filename>C.hi</filename> or a source file
-      <filename>C.hs</filename> or <filename>C.lhs</filename>.</para>
-
-      <para>Note that as far as the compiler is concerned, module
-      names are always fully qualified; the hierarchy only has a
-      special meaning when searching for interface files and source
-      files in the filesystem.  In particular, this means that the
-      full module name must be given after the
+      <para>This extension has very little impact on the language
+      itself; modules names are <emphasis>always</emphasis> fully
+      qualified, so you can just think of the fully qualified module
+      name as <quote>the module name</quote>.  In particular, this
+      means that the full module name must be given after the
       <literal>module</literal> keyword at the beginning of the
       module; for example, the module <literal>A.B.C</literal> must
       begin</para>
 
 <programlisting>module A.B.C</programlisting>
 
+
+      <para>It is a common strategy to use the <literal>as</literal>
+      keyword to save some typing when using qualified names with
+      hierarchical modules.  For example:</para>
+
+<programlisting>
+import qualified Control.Monad.ST.Strict as ST
+</programlisting>
+
+      <para>Hierarchical modules have an impact on the way that GHC
+      searches for files.  For a description, see <xref
+      linkend="finding-hierarchical-modules">.</para>
+
       <para>GHC comes with a large collection of libraries arranged
       hierarchically; see the accompanying library documentation.
       There is an ongoing project to create and maintain a stable set
       of <quote>core</quote> libraries used by several Haskell
       compilers, and the libraries that GHC comes with represent the
       current status of that project.  For more details, see <ulink
-      url="http://www.haskell.org/~simonmar/libraries/libraries.html">.</ulink></para>
+      url="http://www.haskell.org/~simonmar/libraries/libraries.html">Haskell
+      Libraries</ulink>.</para>
 
     </sect2>
 

ghc/docs/users_guide/separate_compilation.sgml

@@ -120,6 +120,43 @@
 
     </sect2>
 
+    <sect2 id="finding-hierarchical-modules">
+      <title>Finding interfaces for hierarchical modules</title>
+
+      <para>GHC supports a hierarchical module namespace as an
+      extension to Haskell 98 (see <xref
+      linkend="hierarchical-modules">).</para>
+
+      <para>A module name in general consists of a sequence of
+      components separated by dots
+      (&lsquo;<literal>.</literal>&rsquo;).  When looking for
+      interface files for a hierarchical module, the compiler turns
+      the dots into path separators, so for example a module
+      <literal>A.B.C</literal> becomes <literal>A/B/C</literal> (or
+      <literal>A\B\C</literal> under Windows).  Then each component of
+      the import directories list is tested in turn; so for example if
+      the list contains directories
+      <literal>D<subscript>1</subscript></literal> to
+      <literal>D<subscript>n</subscript></literal>, then the compiler
+      will look for the interface in
+      <literal>D<subscript>1</subscript>/A/B/C.hi</literal> first,
+      then <literal>D<subscript>2</subscript>/A/B/C.hi</literal> and
+      so on.</para>
+
+      <para>Note that it's perfectly reasonable to have a module which
+      is both a leaf and a branch of the tree.  For example, if we
+      have modules <literal>A.B</literal> and
+      <literal>A.B.C</literal>, then <literal>A.B</literal>'s
+      interface file will be in <literal>A/B.hi</literal> and
+      <literal>A.B.C</literal>'s interface file will be in
+      <literal>A/B/C.hi</literal>.</para>
+
+      <para>For GHCi and <option>--make</option>, the search strategy
+      for source files is exactly the same, just replace the
+      <literal>.hi</literal> suffix in the above description with
+      <literal>.hs</literal> or <literal>.lhs</literal>.</para>
+    </sect2>
+
     <Sect2 id="hi-options">
       <title>Other options related to interface files</title>
       <indexterm><primary>interface files, options</primary></indexterm>

ghc/docs/users_guide/using.sgml

@@ -443,6 +443,12 @@ ghc ––make Main.hs
     interface file for the module, then GHC will complain.  The
     exception to this rule is for package modules, which may or may
     not have source files.</para>
+
+    <para>The source files for the program don't all need to be in the
+    same directory; the <option>-i</option> option can be used to add
+    directories to the search path (see <xref
+    linkend="options-finding-imports">).</para>
+
   </sect1>
   
   <Sect1 id="options-order">