[project @ 2000-01-05 11:20:23 by rrt]
[ghc-hetmet.git] / ghc / docs / users_guide / utils.vsgml
diff --git a/ghc/docs/users_guide/utils.vsgml b/ghc/docs/users_guide/utils.vsgml
deleted file mode 100644 (file)
index 9f0685f..0000000
+++ /dev/null
@@ -1,216 +0,0 @@
-%************************************************************************
-%*                                                                      *
-<sect>Other Haskell utility programs
-<label id="utils">
-<p>
-<nidx>utilities, Haskell</nidx>
-%*                                                                      *
-%************************************************************************
-
-This section describes other program(s) which we distribute, that help
-with the Great Haskell Programming Task.
-
-%************************************************************************
-%*                                                                      *
-<sect1>Makefile dependencies in Haskell: using @mkdependHS@
-<label id="mkdependHS">
-<p>
-<nidx>mkdependHS</nidx>
-<nidx>Makefile dependencies</nidx>
-<nidx>dependencies in Makefiles</nidx>
-%*                                                                      *
-%************************************************************************
-
-You run @mkdependHS@ like this:
-<tscreen><verb>
-  mkdependHS [mkdependHS options] [-- GHC options --] srcfile1 [srcfile2 ...]
-</verb></tscreen>
-or
-<tscreen><verb>
-  ghc -M [mkdependHS options(prefix with -optdep)] [ GHC options ] srcfile1 [srcfile2 ...]
-</verb></tscreen>
-To see @mkdependHS@'s command-line flags, give it a duff flag,
-e.g., @mkdependHS -help@.
-
-In general, if module @A@ contains the line
-<tscreen><verb>
-       import B ...blah...
-</verb></tscreen>
-then @mkdependHS@ will generate a dependency line of the form:
-<tscreen><verb>
-       A.o : B.hi
-</verb></tscreen>
-If module @A@ contains the line 
-<tscreen><verb>
-       import {-# SOURCE #-} B ...blah...
-</verb></tscreen>
-then @mkdependHS@ will generate a dependency line of the form:
-<tscreen><verb>
-       A.o : B.hi-boot
-</verb></tscreen>
-(See Section <ref name="Interface files" id="hi-files"> for details of interface files.)
-If @A@ imports multiple modules, then there will be multiple lines with @A.o@ as the
-target.
-
-By default, @mkdependHS@ generates all the dependencies, and then
-concatenates them onto the end of
-@makefile@ (or @Makefile@ if @makefile@ doesn't exist) bracketed by
-the lines "@# DO NOT DELETE: Beginning of Haskell dependencies@" and
-"@# DO NOT DELETE: End of Haskell dependencies@".  If these lines
-already exist in the @makefile@, @mkdependHS@ deletes the old
-dependencies first.
-
-@mkdependHS@ takes GHC options between @--@ brackets.
-It understands the following ones. Any options between @--@ brackets
-that it doesn't understand are simply ignored; this way you can feed your
-Makefile's standard GHC options to @mkdependHS@ un-filtered.
-<descrip>
-
-<tag>@-cpp@</tag>       Run the C pre-processor over the input files. The
-                       default is not to.
-<tag>@-D<blah>@</tag>  A cpp @#define@; usual meaning.
-
-<tag>@-i<dirs>@</tag>  Add @<dirs>@ (colon-separated) to list of directories
-               to search for "import"ed modules.
-
-<tag>@-I<dir>@</tag>   Add @<dir>@ to list of directories to search for
-               .h files (i.e., usual meaning).
-
-<tag>@-syslib <blah>@</tag> This program uses this GHC system library; take
-               appropriate action (e.g., recognise when they are
-               "import"ing a module from that library).
-</descrip>
-
-Here are the @mkdependHS@-specific options (not between @--@'s):
-<descrip>
-<tag>@-v@</tag>        Be verbose.
-<tag>@-v -v@</tag>     Be very verbose.
-<tag>@-w@</tag>        Turn off warnings about interface file shadowing.
-<tag>@-f blah@</tag>
-       Use @blah@ as the makefile, rather than @makefile@
-       or @Makefile@.  If @blah@ doesn't exist, @mkdependHS@ creates it.
-       We often use @-f .depend@ to put the dependencies in @.depend@ and
-       then @include@ the file @.depend@ into @Makefilpe@.
-
-<tag>@-o <osuf>@</tag> 
-       Use @.<osuf>@ as the "target file" suffix ( default: @o@).
-       Multiple @-o@ flags are permitted (GHC2.05 onwards).  Thus "@-o hc -o o@"
-       will generate dependencies for @.hc@ and @.o@ files.
-
-<tag>@-s <suf>@</tag>  
-               Make extra dependencies that declare that files with
-               suffix @.<suf>_<osuf>@ depend on interface files with suffix @.<suf>_hi@, or
-               (for @{-# SOURCE #-}@ imports) on @.hi-boot@.
-               Multiple @-s@ flags are permitted.
-               For example, "@-o hc -s a -s b@" will
-               make dependencies for @.hc@ on @.hi@, @.a_hc@ on @.a_hi@, and @.b_hc@ on @.b_hi@.
-               (Useful in conjunction with NoFib "ways".)  
-
-<tag>@--exclude-module=<file>@</tag> 
-                Regard @<file>@ as "stable"; i.e., exclude it from having
-               dependencies on it.
-
-<tag>@-x@</tag>      same as @--exclude-module@
-
-<tag>@--exclude-directory=<dirs>@</tag> 
-                Regard the colon-separated list of directories @<dirs>@ as containing stable,
-                don't generate any dependencies on modules therein.
-
-<tag>@-Xdirs@</tag>      same as @--exclude-directory@.
-
-<tag>@--include-module=<file>@</tag>
-                Regard @<file>@ as not "stable"; i.e., generate dependencies
-                on it (if any). This option is normally used in conjunction 
-                with the @--exclude-directory@ option.
-<tag>@--include-prelude@</tag>
-               Regard prelude libraries as unstable, i.e., generate dependencies
-               on the prelude modules used (including @Prelude@).
-               This option is normally only used by the various system libraries. If
-               a @-syslib@ option is used, dependencies will also be
-               generated on the library's interfaces. 
-</descrip>
-
-
-%************************************************************************
-%*                                                                      *
-<sect1>Emacs `TAGS' for Haskell: @hstags@
-<label id="hstags">
-<p>
-<nidx>hstags</nidx>
-<nidx>TAGS for Haskell</nidx>
-%*                                                                      *
-%************************************************************************
-
-`Tags' is a facility for indexing the definitions of
-programming-language things in a multi-file program, and then using
-that index to jump around among these definitions.
-
-Rather than scratch your head, saying ``Now where did we define
-`foo'?'', you just do (in Emacs) @M-. foo RET@, and You're There!
-Some people go wild over this stuff...
-
-GHC comes with a program @hstags@, which build Emacs-able TAGS
-files.  The invocation syntax is:
-<tscreen><verb>
-hstags [GHC-options] file [files...]
-</verb></tscreen>
-
-The best thing is just to feed it your GHC command-line flags.
-A good Makefile entry might be:
-<tscreen><verb>
-tags:
-        $(RM) TAGS
-        hstags $(GHC_FLAGS) *.lhs
-</verb></tscreen>
-
-The only flags of its own are: @-v@ to be verbose; @-a@ to
-**APPEND** to the TAGS file, rather than write to it.
-
-Shortcomings: (1)~Instance declarations don't get into the TAGS file
-(but the definitions inside them do); as instances aren't named, this
-is probably just as well.  (2)~Data-constructor definitions don't get
-in.  Go for the corresponding type constructor instead.
-
-(Actually, GHC also comes with @etags@ [for C], and @perltags@
-[for You Know What].  And---I cannot tell a lie---there is Denis
-Howe's @fptags@ [for Haskell, etc.] in the @ghc/CONTRIB@
-section...)
-
-%************************************************************************
-%*                                                                      *
-<sect1>``Yacc for Haskell'': @happy@
-<label id="happy">
-<p>
-<nidx>happy</nidx>
-<nidx>Yacc for Haskell</nidx>
-<nidx>parser generator for Haskell</nidx>
-%*                                                                      *
-%************************************************************************
-
-Andy Gill and Simon Marlow have written a parser-generator for
-Haskell, called @happy@.<nidx>happy parser generator</nidx> @Happy@
-is to Haskell what @Yacc@ is to C.
-
-You can get @happy@ by FTP from @ftp.dcs.gla.ac.uk@ in
-@pub/haskell/happy@, the file @happy-1.5-src.tar.gz@.
-
-@Happy@ is at its shining best when compiled by GHC.
-
-%************************************************************************
-%*                                                                      *
-<sect1>Pretty-printing Haskell: @pphs@
-<label id="pphs">
-<p>
-<nidx>pphs</nidx>
-<nidx>pretty-printing Haskell code</nidx>
-%*                                                                      *
-%************************************************************************
-
-Andrew Preece has written
-@pphs@,<nidx>pphs</nidx><nidx>pretty-printing Haskell</nidx>
-a utility to pretty-print Haskell code in LaTeX documents.
-Keywords in bolds, variables in italics---that sort of thing.  It is
-good at lining up program clauses and equals signs, things that are
-very tiresome to do by hand.
-
-The code is distributed with GHC in @ghc/CONTRIB/pphs@.