typos never end.

typo

wibbles on mdo-documentation

MonadRec => MonadFix changes

Move mdo section

clarifications on the mdo documentation.

documentation for the mdo-notation.

(I've run this through jade, no syntax errors, but couldn't get
any html output as my docbook installation is a bit weird: couldn't
find style-files etc. it'll be great if someone can run it through
to make sure what I added looks acceptable..)

--------------------------------------
	Make Template Haskell into the HEAD
	--------------------------------------

This massive commit transfers to the HEAD all the stuff that
Simon and Tim have been doing on Template Haskell.  The
meta-haskell-branch is no more!

WARNING: make sure that you

  * Update your links if you are using link trees.
    Some modules have been added, some have gone away.

  * Do 'make clean' in all library trees.
    The interface file format has changed, and you can
    get strange panics (sadly) if GHC tries to read old interface files:
    e.g.  ghc-5.05: panic! (the `impossible' happened, GHC version 5.05):
	  Binary.get(TyClDecl): ForeignType

  * You need to recompile the rts too; Linker.c has changed


However the libraries are almost unaltered; just a tiny change in
Base, and to the exports in Prelude.


NOTE: so far as TH itself is concerned, expression splices work
fine, but declaration splices are not complete.


		---------------
		The main change
		---------------

The main structural change: renaming and typechecking have to be
interleaved, because we can't rename stuff after a declaration splice
until after we've typechecked the stuff before (and the splice
itself).

* Combine the renamer and typecheker monads into one
	(TcRnMonad, TcRnTypes)
  These two replace TcMonad and RnMonad

* Give them a single 'driver' (TcRnDriver).  This driver
  replaces TcModule.lhs and Rename.lhs

* The haskell-src library package has a module
	Language/Haskell/THSyntax
  which defines the Haskell data type seen by the TH programmer.

* New modules:
	hsSyn/Convert.hs 	converts THSyntax -> HsSyn
	deSugar/DsMeta.hs 	converts HsSyn -> THSyntax

* New module typecheck/TcSplice type-checks Template Haskell splices.

		-------------
		Linking stuff
		-------------

* ByteCodeLink has been split into
	ByteCodeLink	(which links)
	ByteCodeAsm	(which assembles)

* New module ghci/ObjLink is the object-code linker.

* compMan/CmLink is removed entirely (was out of place)
  Ditto CmTypes (which was tiny)

* Linker.c initialises the linker when it is first used (no need to call
  initLinker any more).  Template Haskell makes it harder to know when
  and whether to initialise the linker.


	-------------------------------------
	Gathering the LIE in the type checker
	-------------------------------------

* Instead of explicitly gathering constraints in the LIE
	tcExpr :: RenamedExpr -> TcM (TypecheckedExpr, LIE)
  we now dump the constraints into a mutable varabiable carried
  by the monad, so we get
	tcExpr :: RenamedExpr -> TcM TypecheckedExpr

  Much less clutter in the code, and more efficient too.
  (Originally suggested by Mark Shields.)


		-----------------
		Remove "SysNames"
		-----------------

Because the renamer and the type checker were entirely separate,
we had to carry some rather tiresome implicit binders (or "SysNames")
along inside some of the HsDecl data structures.  They were both
tiresome and fragile.

Now that the typechecker and renamer are more intimately coupled,
we can eliminate SysNames (well, mostly... default methods still
carry something similar).

		-------------
		Clean up HsPat
		-------------

One big clean up is this: instead of having two HsPat types (InPat and
OutPat), they are now combined into one.  This is more consistent with
the way that HsExpr etc is handled; there are some 'Out' constructors
for the type checker output.

So:
	HsPat.InPat	--> HsPat.Pat
	HsPat.OutPat	--> HsPat.Pat
	No 'pat' type parameter in HsExpr, HsBinds, etc

	Constructor patterns are nicer now: they use
		HsPat.HsConDetails
	for the three cases of constructor patterns:
		prefix, infix, and record-bindings

	The *same* data type HsConDetails is used in the type
	declaration of the data type (HsDecls.TyData)

Lots of associated clean-up operations here and there.  Less code.
Everything is wonderful.

Add notes about linear implicit parameters

Add link to Mark Jones' paper on functional dependencies, in lieu of
real documentation.

More documentation about hoisting

Add a note about pattern-matching with -fno-implicit-prelude

Reorder sections of type-system extensions

Improve the documentation for hierarchical libraries.

Various hacking on the User's Guide to knock it into shape for the release.

Committers: please take a look at the 5.04 release notes and feel free
to tweak or embelish the description for your favourite new feature.

typo

Documentation for rebindable do-notation

Allow infix type constructors

This commit adds infix type constructors (but not yet class constructors).
The documentation describes what should be the case.  Lots of tiresome
changes, but nothing exciting.

Allows infix type constructors everwhere a type can occur, and in a data
or type synonym decl.  E.g.

	data a :*: b = ....


You can give fixity decls for type constructors, but the fixity decl
applies both to the tycon and the corresponding data con.

* Added the options `-ffi' and `-fffi', which switch on FFI support
  (`-fglasgow-exts' implies `-fffi').

  NB: Strictly speaking `-fffi' is the correct name; however, `-ffi' is
      supported as an alternative spelling.

* `-fglasgow-exts' no longer enables the `with' keyword for implicit
  parameters.  To use `with' as a keyword, the additional option `-fwith' has
  to be supplied.  (Note that SimonM recently enabled the use of `let' instead
  of `with'.)

  NB: This might prompt some makefile tweaks in libraries or regression tests.

* Renamed `Foreign.Marshal.Utils.withObject' to `Foreign.Marshal.Utils.with'
  as required by the FFI Addendum.  (The old name is still available, but
  marked as deprecated.)

* Added `realloc' to `Foreign.Marshal.Alloc' (tracking RC4 of the FFI
  Addendum).

Docu
~~~~
* Added `-ffi', `-fffi', and `-fwith' to the flag reference and the section
  describing options for Glasgow extensions

* Removed most of the FFI section in the User's Guide in favour of a reference
  to the Addendum plus a brief description of additional features supported by
  GHC.

  NB: The old material is still available at fptools/docs/, I merely removed
  the reference in the User's Guide.

More on linear implicit params

Documentation about type system extensions

Documentation for more liberal class-method types

Wibble

Documentation for kinded declarations

Add a bit of documentation on implicit params

Document hoisting and implicit quantification

Typo

Docment newtype deriving stuff

------------------------------
	Add linear implicit parameters
	------------------------------

Linear implicit parameters are an idea developed by Koen Claessen,
Mark Shields, and Simon PJ, last week.  They address the long-standing
problem that monads seem over-kill for certain sorts of problem, notably:

	* distributing a supply of unique names
	* distributing a suppply of random numbers
	* distributing an oracle (as in QuickCheck)


Linear implicit parameters are just like ordinary implicit parameters,
except that they are "linear" -- that is, they cannot be copied, and
must be explicitly "split" instead.  Linear implicit parameters are
written '%x' instead of '?x'.  (The '/' in the '%' suggests the
split!)

For example:

    data NameSupply = ...

    splitNS :: NameSupply -> (NameSupply, NameSupply)
    newName :: NameSupply -> Name

    instance PrelSplit.Splittable NameSupply where
	split = splitNS


    f :: (%ns :: NameSupply) => Env -> Expr -> Expr
    f env (Lam x e) = Lam x' (f env e)
		    where
		      x'   = newName %ns
		      env' = extend env x x'
    ...more equations for f...

Notice that the implicit parameter %ns is consumed
	once by the call to newName
	once by the recursive call to f

So the translation done by the type checker makes
the parameter explicit:

    f :: NameSupply -> Env -> Expr -> Expr
    f ns env (Lam x e) = Lam x' (f ns1 env e)
		       where
	 		 (ns1,ns2) = splitNS ns
			 x' = newName ns2
			 env = extend env x x'

Notice the call to 'split' introduced by the type checker.
How did it know to use 'splitNS'?  Because what it really did
was to introduce a call to the overloaded function 'split',
ndefined by

	class Splittable a where
	  split :: a -> (a,a)

The instance for Splittable NameSupply tells GHC how to implement
split for name supplies.  But we can simply write

	g x = (x, %ns, %ns)

and GHC will infer

	g :: (Splittable a, %ns :: a) => b -> (b,a,a)

The Splittable class is built into GHC.  It's defined in PrelSplit,
and exported by GlaExts.

Other points:

* '?x' and '%x' are entirely distinct implicit parameters: you
  can use them together and they won't intefere with each other.

* You can bind linear implicit parameters in 'with' clauses.

* You cannot have implicit parameters (whether linear or not)
  in the context of a class or instance declaration.


Warnings
~~~~~~~~
The monomorphism restriction is even more important than usual.
Consider the example above:

    f :: (%ns :: NameSupply) => Env -> Expr -> Expr
    f env (Lam x e) = Lam x' (f env e)
		    where
		      x'   = newName %ns
		      env' = extend env x x'

If we replaced the two occurrences of x' by (newName %ns), which is
usually a harmless thing to do, we get:

    f :: (%ns :: NameSupply) => Env -> Expr -> Expr
    f env (Lam x e) = Lam (newName %ns) (f env e)
		    where
		      env' = extend env x (newName %ns)

But now the name supply is consumed in *three* places
(the two calls to newName,and the recursive call to f), so
the result is utterly different.  Urk!  We don't even have
the beta rule.

Well, this is an experimental change.  With implicit
parameters we have already lost beta reduction anyway, and
(as John Launchbury puts it) we can't sensibly reason about
Haskell programs without knowing their typing.

Of course, none of this is throughly tested, either.

Correct docs about SPECIALIZE instance; MERGE TO STABLE

wibble

Document scoped type variables

foldr is a good consumer (but not necessarily a good producer)

Note that support for generics is currently broken.

Fix example code in the generics section.

- Rearrange the FFI documentation: put it all in chapter 8.

- Add a section "Using the FFI with GHC", and add some information about
  the stub files generated by GHC for foreign export dynamic.

- describe NOTINLINE as a synonym for NOINLINE
- describe the general form of a pragma
- mention that case is irrelevant in the first word of a pragma
- mention that unrecognised pragmas are silently ignored

Fix markup bugs; add documentation about deprecations

document data types with no constructors

markup fixes