[project @ 2000-06-12 11:41:00 by simonmar]

Update docs on mkdependHS: it isn't a separate utility, so document it
under "Using GHC".

Also update section on Happy.

diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml
index 4819a99..e3f63e9 100644 (file)
--- a/ghc/docs/users_guide/using.sgml
+++ b/ghc/docs/users_guide/using.sgml
@@ -1147,65 +1147,200 @@ a rule to do so; one of the preceding suffix rules does the job
 nicely.
 </Para>
 
-<Para>
-Putting inter-dependencies of the form <Literal>Foo.o : Bar.hi</Literal> into your
-<Filename>Makefile</Filename> by hand is rather error-prone.  Don't worry&mdash;never fear,
-<Command>mkdependHS</Command> is here! (and is distributed as part of GHC) Add the
-following to your <Filename>Makefile</Filename>:
-</Para>
+    </sect2>
 
-<Para>
+    <sect2><title>Dependency generation</title>
+      <indexterm><primary>dependencies in Makefiles</primary></indexterm>
+      <indexterm><primary>Makefile dependencies</primary></indexterm>
+
+      <para>Putting inter-dependencies of the form <Literal>Foo.o :
+      Bar.hi</Literal> into your <Filename>Makefile</Filename> by hand
+      is rather error-prone.  Don't worry, GHC has support for
+      automatically generating the required dependencies.  Add the
+      following to your <Filename>Makefile</Filename>:</para>
 
 <ProgramListing>
 depend :
-        mkdependHS -- $(HC_OPTS) -- $(SRCS)
+        ghc -M $(HC_OPTS) $(SRCS)
 </ProgramListing>
 
-</Para>
-
-<Para>
-Now, before you start compiling, and any time you change the <Literal>imports</Literal>
-in your program, do <Command>make depend</Command> before you do <Command>make cool&lowbar;pgm</Command>.
-<Command>mkdependHS</Command> will append the needed dependencies to your <Filename>Makefile</Filename>.
-<Command>mkdependHS</Command> is fully described in <XRef LinkEnd="mkdependHS">.
-</Para>
-
-<Para>
-A few caveats about this simple scheme:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- You may need to compile some modules explicitly to create their
-interfaces in the first place (e.g., <Command>make Bar.o</Command> to create <Filename>Bar.hi</Filename>).
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- You may have to type <Command>make</Command> more than once for the dependencies
-to have full effect.  However, a <Command>make</Command> run that does nothing
-<Emphasis>does</Emphasis> mean &ldquo;everything's up-to-date.&rdquo;
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- This scheme will work with mutually-recursive modules but,
-again, it may take multiple iterations to &ldquo;settle.&rdquo;
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
+      <para>Now, before you start compiling, and any time you change
+      the <Literal>imports</Literal> in your program, do <Command>make
+      depend</Command> before you do <Command>make
+      cool&lowbar;pgm</Command>.  <Command>GHC</Command> will append
+      the needed dependencies to your
+      <Filename>Makefile</Filename>.</Para>
+
+      <para>In general, if module <Literal>A</Literal> contains the
+      line
+
+<programlisting>
+import B ...blah...
+</programlisting>
+
+       then <command>mkdependHS</command> will generate a dependency
+       line of the form:
+
+<programlisting>
+A.o : B.hi
+</programlisting>
+
+       If module <literal>A</literal> contains the line 
+
+<programlisting>
+import {-# SOURCE #-} B ...blah...
+</programlisting>
+
+       then <command>mkdependHS</command> will generate a dependency
+       line of the form:
+
+<programlisting>
+A.o : B.hi-boot
+</programlisting>
+
+       (See <xref linkend="hi-files"> for details of interface files.)
+       If <literal>A</literal> imports multiple modules, then there
+       will be multiple lines with <filename>A.o</filename> as the
+       target.</para>
+
+      <para>By default, <Command>GHC</Command> generates all the
+      dependencies, and then concatenates them onto the end of
+      <Filename>makefile</Filename> (or <Filename>Makefile</Filename>
+      if <Filename>makefile</Filename> doesn't exist) bracketed by the
+      lines "<Literal>&num; DO NOT DELETE: Beginning of Haskell
+      dependencies</Literal>" and "<Literal>&num; DO NOT DELETE: End
+      of Haskell dependencies</Literal>".  If these lines already
+      exist in the <Filename>makefile</Filename>, then the old
+      dependencies are deleted first.</para>
+
+      <para>Internally, GHC uses a script to generate the
+      dependencies, called <command>mkdependHS</command>.  This script
+      has some options of its own, which you might find useful.
+      Options can be passed directly to <command>mkdependHS</command>
+      with GHC's <literal>-optdep</literal> option.  For example, to
+      generate the dependencies into a file called
+      <literal>.depend</literal> instead of
+      <literal>Makefile</literal>:</para>
+
+<screen>
+ghc -M -optdep-f optdep.depend ...
+</screen>
+      
+      <para>The full list of options accepted by
+      <command>mkdependHS</command> is:</para>
+
+      <variablelist>
+
+       <varlistentry>
+         <term><option>-w</option></term>
+         <listitem>
+           <para>Turn off warnings about interface file shadowing.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>-f blah</option></term>
+         <listitem>
+           <para>Use <Filename>blah</Filename> as the makefile,
+            rather than <Filename>makefile</Filename> or
+            <Filename>Makefile</Filename>.  If
+            <Filename>blah</Filename> doesn't exist,
+            <Command>mkdependHS</Command> creates it.  We often use
+            <Option>-f .depend</Option> to put the dependencies in
+            <Filename>.depend</Filename> and then
+            <Command>include</Command> the file
+            <Filename>.depend</Filename> into
+            <Filename>Makefile</Filename>.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>-o &lt;osuf&gt;</option></term>
+         <listitem>
+           <para>Use <Filename>.&lt;osuf&gt;</Filename> as the
+            "target file" suffix ( default: <Literal>o</Literal>).
+            Multiple <Option>-o</Option> flags are permitted (GHC2.05
+            onwards).  Thus "<Option>-o hc -o o</Option>" will
+            generate dependencies for <Filename>.hc</Filename> and
+            <Filename>.o</Filename> files.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>-s &lt;suf&gt;</option></term>
+         <listitem>
+           <para>Make extra dependencies that declare that files with
+            suffix
+            <Filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</Filename>
+            depend on interface files with suffix
+            <Filename>.&lt;suf&gt;&lowbar;hi</Filename>, or (for
+            <Literal>&lcub;-&num; SOURCE &num;-&rcub;</Literal>
+            imports) on <Filename>.hi-boot</Filename>.  Multiple
+            <Option>-s</Option> flags are permitted.  For example,
+            <Option>-o hc -s a -s b</Option> will make dependencies
+            for <Filename>.hc</Filename> on <Filename>.hi</Filename>,
+            <Filename>.a&lowbar;hc</Filename> on
+            <Filename>.a&lowbar;hi</Filename>, and
+            <Filename>.b&lowbar;hc</Filename> on
+            <Filename>.b&lowbar;hi</Filename>.  (Useful in conjunction
+            with NoFib "ways".)</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>--exclude-module=&lt;file&gt;</option></term>
+         <listitem>
+           <para>Regard <Filename>&lt;file&gt;</Filename> as
+            "stable"; i.e., exclude it from having dependencies on
+            it.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>-x</option></term>
+         <listitem>
+           <para>same as <option>--exclude-module</option></para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>--exclude-directory=&lt;dirs&gt;</option></term>
+         <listitem>
+           <para>Regard the colon-separated list of directories
+            <Filename>&lt;dirs&gt;</Filename> as containing stable,
+            don't generate any dependencies on modules therein.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>-xdirs</option></term>
+         <listitem>
+           <para>same as <Option>--exclude-directory</Option>.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>--include-module=&lt;file&gt;</option></term>
+         <listitem>
+           <para>Regard <Filename>&lt;file&gt;</Filename> as not
+            "stable"; i.e., generate dependencies on it (if any). This
+            option is normally used in conjunction with the
+            <Option>--exclude-directory</Option> option.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><option>--include-prelude</option></term>
+         <listitem>
+           <para>Regard prelude libraries as unstable, i.e., generate
+            dependencies on the prelude modules used (including
+            <Literal>Prelude</Literal>).  This option is normally only
+            used by the various system libraries. If a
+            <Option>-syslib</Option> option is used, dependencies will
+            also be generated on the library's interfaces.</para>
+         </listitem>
+       </varlistentry>
+      </variablelist>
 
 </Sect2>
 

diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml
index 4bd99a1..67547c3 100644 (file)
--- a/ghc/docs/users_guide/utils.sgml
+++ b/ghc/docs/users_guide/utils.sgml
@@ -9,252 +9,6 @@ This section describes other program(s) which we distribute, that help
 with the Great Haskell Programming Task.
 </Para>
 
-<Sect1 id="mkdependHS">
-<Title>Makefile dependencies in Haskell: using <Command>mkdependHS</Command>
-</Title>
-
-<Para>
-<IndexTerm><Primary>mkdependHS</Primary></IndexTerm>
-<IndexTerm><Primary>Makefile dependencies</Primary></IndexTerm>
-<IndexTerm><Primary>dependencies in Makefiles</Primary></IndexTerm>
-</Para>
-
-<Para>
-You run <Command>mkdependHS</Command> like this:
-
-<Screen>
-mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
-</Screen>
-
-or
-
-<Screen>
-ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
-</Screen>
-
-To see <Command>mkdependHS</Command>'s command-line flags, give it a duff flag,
-e.g., <Command>mkdependHS -help</Command>.
-</Para>
-
-<Para>
-In general, if module <Literal>A</Literal> contains the line
-
-<ProgramListing>
-import B ...blah...
-</ProgramListing>
-
-then <Command>mkdependHS</Command> will generate a dependency line of the form:
-
-<ProgramListing>
-A.o : B.hi
-</ProgramListing>
-
-If module <Literal>A</Literal> contains the line 
-
-<ProgramListing>
-import {-# SOURCE #-} B ...blah...
-</ProgramListing>
-
-then <Command>mkdependHS</Command> will generate a dependency line of the form:
-
-<ProgramListing>
-A.o : B.hi-boot
-</ProgramListing>
-
-(See <XRef LinkEnd="hi-files"> for details of interface files.)
-If <Literal>A</Literal> imports multiple modules, then there will be multiple lines with <Filename>A.o</Filename> as the
-target.
-</Para>
-
-<Para>
-By default, <Command>mkdependHS</Command> generates all the dependencies, and then
-concatenates them onto the end of
-<Filename>makefile</Filename> (or <Filename>Makefile</Filename> if <Filename>makefile</Filename> doesn't exist) bracketed by
-the lines "<Literal>&num; DO NOT DELETE: Beginning of Haskell dependencies</Literal>" and
-"<Literal>&num; DO NOT DELETE: End of Haskell dependencies</Literal>".  If these lines
-already exist in the <Filename>makefile</Filename>, <Command>mkdependHS</Command> deletes the old
-dependencies first.
-</Para>
-
-<Para>
-<Command>mkdependHS</Command> takes GHC options between <Literal>--</Literal> brackets.
-It understands the following ones. Any options between <Literal>--</Literal> brackets
-that it doesn't understand are simply ignored; this way you can feed your
-Makefile's standard GHC options to <Command>mkdependHS</Command> un-filtered.
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-cpp</Option></Term>
-<ListItem>
-<Para>
-Run the C pre-processor over the input files. The
-default is not to.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-D&lt;blah&gt;</Option></Term>
-<ListItem>
-<Para>
-A cpp <Option>&num;define</Option>; usual meaning.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-i&lt;dirs&gt;</Option></Term>
-<ListItem>
-<Para>
-Add <Filename>&lt;dirs&gt;</Filename> (colon-separated) to list of directories
-to search for "import"ed modules.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-I&lt;dir&gt;</Option></Term>
-<ListItem>
-<Para>
-Add <Filename>&lt;dir&gt;</Filename> to list of directories to search for
-.h files (i.e., usual meaning).
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-syslib &lt;blah&gt;</Option></Term>
-<ListItem>
-<Para>
-This program uses this GHC system library; take
-appropriate action (e.g., recognise when they are
-"import"ing a module from that library).
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-<Para>
-Here are the <Command>mkdependHS</Command>-specific options (not between <Literal>--</Literal>'s):
-<VariableList>
-
-<VarListEntry>
-<Term><Option>-v</Option></Term>
-<ListItem>
-<Para>
-Be verbose.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-v -v</Option></Term>
-<ListItem>
-<Para>
-Be very verbose.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-w</Option></Term>
-<ListItem>
-<Para>
-Turn off warnings about interface file shadowing.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-f blah</Option></Term>
-<ListItem>
-<Para>
-Use <Filename>blah</Filename> as the makefile, rather than <Filename>makefile</Filename>
-or <Filename>Makefile</Filename>.  If <Filename>blah</Filename> doesn't exist, <Command>mkdependHS</Command> creates it.
-We often use <Option>-f .depend</Option> to put the dependencies in <Filename>.depend</Filename> and
-then <Command>include</Command> the file <Filename>.depend</Filename> into <Filename>Makefile</Filename>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-o &lt;osuf&gt;</Option></Term>
-<ListItem>
-<Para>
-Use <Filename>.&lt;osuf&gt;</Filename> as the "target file" suffix ( default: <Literal>o</Literal>).
-Multiple <Option>-o</Option> flags are permitted (GHC2.05 onwards).  Thus "<Option>-o hc -o o</Option>"
-will generate dependencies for <Filename>.hc</Filename> and <Filename>.o</Filename> files.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-s &lt;suf&gt;</Option></Term>
-<ListItem>
-<Para>
-Make extra dependencies that declare that files with
-suffix <Filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</Filename> depend on interface files with suffix <Filename>.&lt;suf&gt;&lowbar;hi</Filename>, or
-(for <Literal>&lcub;-&num; SOURCE &num;-&rcub;</Literal> imports) on <Filename>.hi-boot</Filename>.
-Multiple <Option>-s</Option> flags are permitted.
-For example, <Option>-o hc -s a -s b</Option> will
-make dependencies for <Filename>.hc</Filename> on <Filename>.hi</Filename>, <Filename>.a&lowbar;hc</Filename> on <Filename>.a&lowbar;hi</Filename>, and <Filename>.b&lowbar;hc</Filename> on <Filename>.b&lowbar;hi</Filename>.
-(Useful in conjunction with NoFib "ways".)  
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>--exclude-module=&lt;file&gt;</Option></Term>
-<ListItem>
-<Para>
-Regard <Filename>&lt;file&gt;</Filename> as "stable"; i.e., exclude it from having
-dependencies on it.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-x</Option></Term>
-<ListItem>
-<Para>
-same as <Option>--exclude-module</Option>
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>--exclude-directory=&lt;dirs&gt;</Option></Term>
-<ListItem>
-<Para>
-Regard the colon-separated list of directories <Filename>&lt;dirs&gt;</Filename> as containing stable,
-don't generate any dependencies on modules therein.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>-Xdirs</Option></Term>
-<ListItem>
-<Para>
-same as <Option>--exclude-directory</Option>.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>--include-module=&lt;file&gt;</Option></Term>
-<ListItem>
-<Para>
-Regard <Filename>&lt;file&gt;</Filename> as not "stable"; i.e., generate dependencies
-on it (if any). This option is normally used in conjunction 
-with the <Option>--exclude-directory</Option> option.
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term><Option>--include-prelude</Option></Term>
-<ListItem>
-<Para>
-Regard prelude libraries as unstable, i.e., generate dependencies
-on the prelude modules used (including <Literal>Prelude</Literal>).
-This option is normally only used by the various system libraries. If
-a <Option>-syslib</Option> option is used, dependencies will also be
-generated on the library's interfaces. 
-</Para>
-</ListItem>
-</VarListEntry>
-</VariableList>
-</Para>
-
-</Sect1>
-
 <Sect1 id="hstags">
 <Title>Emacs `TAGS' for Haskell: <Command>hstags</Command>
 </Title>
@@ -332,8 +86,8 @@ is to Haskell what <Command>Yacc</Command> is to C.
 </Para>
 
 <Para>
-You can get <Command>happy</Command> by FTP from <Literal>ftp.dcs.gla.ac.uk</Literal> in
-<Filename>pub/haskell/happy</Filename>, the file <Filename>happy-1.5-src.tar.gz</Filename>.
+You can get <Command>happy</Command> from <ulink
+url="http://www.haskell.org/happy/">the Happy Homepage</ulink>.
 </Para>
 
 <Para>