From e1a833412aa72cdabf4bd04dcde52a0aca0e1274 Mon Sep 17 00:00:00 2001
From: simonm <unknown>
Date: Tue, 16 Mar 1999 17:07:23 +0000
Subject: [PATCH] [project @ 1999-03-16 17:07:21 by simonm] - Document the
 pragmas we support - Fix some lies in the vs. Haskell
 section.

---
 ghc/docs/users_guide/glasgow_exts.vsgml |  154 ++++++++++++++++++++++++++++++-
 ghc/docs/users_guide/gone_wrong.vsgml   |    2 +-
 ghc/docs/users_guide/sooner.vsgml       |   97 ++-----------------
 ghc/docs/users_guide/vs_haskell.vsgml   |   38 ++------
 4 files changed, 166 insertions(+), 125 deletions(-)

diff --git a/ghc/docs/users_guide/glasgow_exts.vsgml b/ghc/docs/users_guide/glasgow_exts.vsgml
index bcc7166..f5cdbd2 100644
--- a/ghc/docs/users_guide/glasgow_exts.vsgml
+++ b/ghc/docs/users_guide/glasgow_exts.vsgml
@@ -1,5 +1,5 @@
 % 
-% $Id: glasgow_exts.vsgml,v 1.5 1999/02/22 10:22:35 sof Exp $
+% $Id: glasgow_exts.vsgml,v 1.6 1999/03/16 17:07:21 simonm Exp $
 %
 % GHC Language Extensions.
 %
@@ -60,6 +60,12 @@ Just what it sounds like.  We provide <em>lots</em> of rope that you
 can dangle around your neck.  Please see Section <ref name="Calling~C
 directly from Haskell" id="glasgow-ccalls">.
 
+<tag>Pragmas</tag>
+
+Pragmas are special instructions to the compiler placed in the source
+file.  The pragmas GHC supports are described in Section <ref
+name="Pragmas" id="pragmas">.
+
 </descrip>
 
 Before you get too carried away working at the lowest level (e.g.,
@@ -1730,3 +1736,149 @@ For example:
 </verb></tscreen>
 
 </itemize>
+
+%-----------------------------------------------------------------------------
+<sect1>Pragmas
+<label id="pragmas">
+<p>
+
+GHC supports several pragmas, or instructions to the compiler placed
+in the source code.  Pragmas don't affect the meaning of the program,
+but they might affect the efficiency of the generated code.
+
+<sect2>INLINE pragma
+<label id="inline-pragma">
+<nidx>INLINE pragma</nidx>
+<nidx>pragma, INLINE</nidx>
+<p>
+
+GHC (with @-O@, as always) tries to inline (or ``unfold'')
+functions/values that are ``small enough,'' thus avoiding the call
+overhead and possibly exposing other more-wonderful optimisations.
+
+You will probably see these unfoldings (in Core syntax) in your
+interface files.
+
+Normally, if GHC decides a function is ``too expensive'' to inline, it
+will not do so, nor will it export that unfolding for other modules to
+use.
+
+The sledgehammer you can bring to bear is the
+@INLINE@<nidx>INLINE pragma</nidx> pragma, used thusly:
+<tscreen><verb>
+key_function :: Int -> String -> (Bool, Double) 
+
+#ifdef __GLASGOW_HASKELL__
+{-# INLINE key_function #-}
+#endif
+</verb></tscreen>
+(You don't need to do the C pre-processor carry-on unless you're going
+to stick the code through HBC---it doesn't like @INLINE@ pragmas.)
+
+The major effect of an @INLINE@ pragma is to declare a function's
+``cost'' to be very low.  The normal unfolding machinery will then be
+very keen to inline it.
+
+An @INLINE@ pragma for a function can be put anywhere its type
+signature could be put.
+
+@INLINE@ pragmas are a particularly good idea for the
+@then@/@return@ (or @bind@/@unit@) functions in a monad.
+For example, in GHC's own @UniqueSupply@ monad code, we have:
+<tscreen><verb>
+#ifdef __GLASGOW_HASKELL__
+{-# INLINE thenUs #-}
+{-# INLINE returnUs #-}
+#endif
+</verb></tscreen>
+
+<sect2>NOINLINE pragma
+<label id="noinline-pragma">
+<p>
+<nidx>NOINLINE pragma</nidx>
+<nidx>pragma, NOINLINE</nidx>
+
+The @NOINLINE@ pragma does exactly what you'd expect: it stops the
+named function from being inlined by the compiler.  You shouldn't ever
+need to do this, unless you're very cautious about code size.
+
+<sect2>SPECIALIZE pragma
+<label id="specialize-pragma">
+<p>
+<nidx>SPECIALIZE pragma</nidx>
+<nidx>pragma, SPECIALIZE</nidx>
+<nidx>overloading, death to</nidx>
+
+(UK spelling also accepted.)  For key overloaded functions, you can
+create extra versions (NB: more code space) specialised to particular
+types.  Thus, if you have an overloaded function:
+
+<tscreen><verb>
+hammeredLookup :: Ord key => [(key, value)] -> key -> value
+</verb></tscreen>
+
+If it is heavily used on lists with @Widget@ keys, you could
+specialise it as follows:
+<tscreen><verb>
+{-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}
+</verb></tscreen>
+
+To get very fancy, you can also specify a named function to use for
+the specialised value, by adding @= blah@, as in:
+<tscreen><verb>
+{-# SPECIALIZE hammeredLookup :: ...as before... = blah #-}
+</verb></tscreen>
+It's <em>Your Responsibility</em> to make sure that @blah@ really
+behaves as a specialised version of @hammeredLookup@!!!
+
+NOTE: the @=blah@ feature isn't implemented in GHC 4.xx.
+
+An example in which the @= blah@ form will Win Big:
+<tscreen><verb>
+toDouble :: Real a => a -> Double
+toDouble = fromRational . toRational
+
+{-# SPECIALIZE toDouble :: Int -> Double = i2d #-}
+i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly
+</verb></tscreen>
+The @i2d@ function is virtually one machine instruction; the
+default conversion---via an intermediate @Rational@---is obscenely
+expensive by comparison.
+
+By using the US spelling, your @SPECIALIZE@ pragma will work with
+HBC, too.  Note that HBC doesn't support the @= blah@ form.
+
+A @SPECIALIZE@ pragma for a function can be put anywhere its type
+signature could be put.
+
+<sect2>SPECIALIZE instance pragma
+<label id="specialize-instance-pragma">
+<p>
+<nidx>SPECIALIZE pragma</nidx>
+<nidx>overloading, death to</nidx>
+Same idea, except for instance declarations.  For example:
+<tscreen><verb>
+instance (Eq a) => Eq (Foo a) where { ... usual stuff ... }
+
+{-# SPECIALIZE instance Eq (Foo [(Int, Bar)] #-}
+</verb></tscreen>
+Compatible with HBC, by the way.
+
+<sect2>LINE pragma
+<label id="line-pragma">
+<p>
+<nidx>LINE pragma</nidx>
+<nidx>pragma, LINE</nidx>
+
+This pragma is similar to C's @#line@ pragma, and is mainly for use in
+automatically generated Haskell code.  It lets you specify the line
+number and filename of the original code; for example
+
+<tscreen><verb>
+{-# LINE 42 "Foo.vhs" #-}
+</verb></tscreen>
+
+if you'd generated the current file from something called @Foo.vhs@
+and this line corresponds to line 42 in the original.  GHC will adjust
+its error messages to refer to the line/file named in the @LINE@
+pragma.
diff --git a/ghc/docs/users_guide/gone_wrong.vsgml b/ghc/docs/users_guide/gone_wrong.vsgml
index 3d9cc57..8bf7670 100644
--- a/ghc/docs/users_guide/gone_wrong.vsgml
+++ b/ghc/docs/users_guide/gone_wrong.vsgml
@@ -13,7 +13,7 @@ name="How to report a bug in the GHC system" id="bug-reports"> for a
 list of things we'd like to know about your bug.  If in doubt, send a
 report---we love mail from irate users :-!
 
-(Section <ref name="Haskell 1.4 vs. Glasgow Haskell 4.00: language
+(Section <ref name="Haskell 98 vs. Glasgow Haskell: language
 non-compliance" id="vs-Haskell-defn">, which describes Glasgow
 Haskell's shortcomings vs.~the Haskell language definition, may also
 be of interest.)
diff --git a/ghc/docs/users_guide/sooner.vsgml b/ghc/docs/users_guide/sooner.vsgml
index ffd9fc5..0957f45 100644
--- a/ghc/docs/users_guide/sooner.vsgml
+++ b/ghc/docs/users_guide/sooner.vsgml
@@ -183,56 +183,10 @@ should take care of overloaded local and/or unexported functions.
 <tag>Use @SPECIALIZE@ pragmas:</tag>
 <nidx>SPECIALIZE pragma</nidx>
 <nidx>overloading, death to</nidx>
-(UK spelling also accepted.)  For key overloaded functions, you can
-create extra versions (NB: more code space) specialised to particular
-types.  Thus, if you have an overloaded function:
 
-<tscreen><verb>
-hammeredLookup :: Ord key => [(key, value)] -> key -> value
-</verb></tscreen>
-
-If it is heavily used on lists with @Widget@ keys, you could
-specialise it as follows:
-<tscreen><verb>
-{-# SPECIALIZE hammeredLookup :: [(Widget, value)] -> Widget -> value #-}
-</verb></tscreen>
-
-To get very fancy, you can also specify a named function to use for
-the specialised value, by adding @= blah@, as in:
-<tscreen><verb>
-{-# SPECIALIZE hammeredLookup :: ...as before... = blah #-}
-</verb></tscreen>
-It's <em>Your Responsibility</em> to make sure that @blah@ really
-behaves as a specialised version of @hammeredLookup@!!!
-
-[NOTE: this feature isn't implemented in GHC 4.00... ]
-
-An example in which the @= blah@ form will Win Big:
-<tscreen><verb>
-toDouble :: Real a => a -> Double
-toDouble = fromRational . toRational
-
-{-# SPECIALIZE toDouble :: Int -> Double = i2d #-}
-i2d (I# i) = D# (int2Double# i) -- uses Glasgow prim-op directly
-</verb></tscreen>
-The @i2d@ function is virtually one machine instruction; the
-default conversion---via an intermediate @Rational@---is obscenely
-expensive by comparison.
-
-By using the US spelling, your @SPECIALIZE@ pragma will work with
-HBC, too.  Note that HBC doesn't support the @= blah@ form.
-
-A @SPECIALIZE@ pragma for a function can be put anywhere its type
-signature could be put.
-
-<tag>Use @SPECIALIZE instance@ pragmas:</tag>
-Same idea, except for instance declarations.  For example:
-<tscreen><verb>
-instance (Eq a) => Eq (Foo a) where { ... usual stuff ... }
-
-{-# SPECIALIZE instance Eq (Foo [(Int, Bar)] #-}
-</verb></tscreen>
-Compatible with HBC, by the way.
+Specialize the overloading on key functions in your program.  See
+Sections <ref name="SPECIALIZE pragmas" id="specialize-pragma"> and
+<ref name="SPECIALIZE instance pragmas" id="specialize-instance-pragma">
 
 % See also: overlapping instances, in Section <ref name="``HBC-ish''
 % extensions implemented by GHC" id="glasgow-hbc-exts">.  They are to
@@ -336,48 +290,9 @@ pragmatic information as would be put in an interface file.
 %----------------------------------------------------------------
 <tag>Force key functions to be @INLINE@d (esp. monads):</tag>
 
-GHC (with @-O@, as always) tries to inline (or ``unfold'')
-functions/values that are ``small enough,'' thus avoiding the call
-overhead and possibly exposing other more-wonderful optimisations.
-
-You will probably see these unfoldings (in Core syntax) in your
-interface files.
-
-Normally, if GHC decides a function is ``too expensive'' to inline, it
-will not do so, nor will it export that unfolding for other modules to
-use.
-
-The sledgehammer you can bring to bear is the
-@INLINE@<nidx>INLINE pragma</nidx> pragma, used thusly:
-<tscreen><verb>
-key_function :: Int -> String -> (Bool, Double) 
-
-#ifdef __GLASGOW_HASKELL__
-{-# INLINE key_function #-}
-#endif
-</verb></tscreen>
-(You don't need to do the C pre-processor carry-on unless you're going
-to stick the code through HBC---it doesn't like @INLINE@ pragmas.)
-
-The major effect of an @INLINE@ pragma is to declare a function's
-``cost'' to be very low.  The normal unfolding machinery will then be
-very keen to inline it.
-
-An @INLINE@ pragma for a function can be put anywhere its type
-signature could be put.
-
-@INLINE@ pragmas are a particularly good idea for the
-@then@/@return@ (or @bind@/@unit@) functions in a monad.
-For example, in GHC's own @UniqueSupply@ monad code, we have:
-<tscreen><verb>
-#ifdef __GLASGOW_HASKELL__
-{-# INLINE thenUs #-}
-{-# INLINE returnUs #-}
-#endif
-</verb></tscreen>
-
-Incedentally, there's also a @NOINLINE@<nidx>NOINLINE pragma</nidx>
-pragma which does the obvious thing.
+Placing @INLINE@ pragmas on certain functions that are used a lot can
+have a dramatic effect.  See Section <ref name="INLINE pragmas"
+id="inline-pragma">.
 
 %----------------------------------------------------------------
 <tag>Explicit @export@ list:</tag>
diff --git a/ghc/docs/users_guide/vs_haskell.vsgml b/ghc/docs/users_guide/vs_haskell.vsgml
index 1bd291a..3d08ae8 100644
--- a/ghc/docs/users_guide/vs_haskell.vsgml
+++ b/ghc/docs/users_guide/vs_haskell.vsgml
@@ -1,15 +1,15 @@
 %************************************************************************
 %*                                                                      *
-<sect1>Haskell~1.4 vs.~Glasgow Haskell~4.00: language non-compliance
+<sect1>Haskell~98 vs.~Glasgow Haskell: language non-compliance
 <label id="vs-Haskell-defn">
 <p>
-<nidx>GHC vs the Haskell 1.4 language</nidx>
-<nidx>Haskell 1.4 language vs GHC</nidx>
+<nidx>GHC vs the Haskell 98 language</nidx>
+<nidx>Haskell 98 language vs GHC</nidx>
 %*                                                                      *
 %************************************************************************
 
 This section lists Glasgow Haskell infelicities in its implementation
-of Haskell~1.4.  See also the ``when things go wrong'' section
+of Haskell~98.  See also the ``when things go wrong'' section
 (Section <ref name="What to do when something goes wrong" id="wrong">)
 for information about crashes, space leaks, and other undesirable
 phenomena.
@@ -56,12 +56,6 @@ It might work, but it's just begging for trouble.
 
 <descrip>
 %-------------------------------------------------------------------
-<tag>Derived instances of @Read@ and @Show@ for infix constructors:</tag>
-All the carry-on about derived @readsPrec@ and @showsPrec@ for infix
-constructors---we don't do it (yet).  We treat them the same way as
-all other constructors.
-
-%-------------------------------------------------------------------
 <tag>Derived instances for records:</tag> Hmmm.
 </descrip>
 
@@ -82,11 +76,6 @@ All of these modules begin with @Prel@, so the rule is: don't use any
 modules beginning with @Prel@ in your program, or you will be
 comprehensively screwed.
 
-% Not true anymore? -- Simon M.
-%-------------------------------------------------------------------
-% <tag>Can't export primitive types (e.g., @Int#@):</tag>
-% Don't even try...
-
 </descrip>
 
 %************************************************************************
@@ -98,19 +87,6 @@ comprehensively screwed.
 %************************************************************************
 
 <descrip>
-% Not true anymore? We use Rationals all the way -- Simon M.
-%-------------------------------------------------------------------
-% <tag>Very large/small fractional constants:</tag>
-% (i.e., with a decimal point somewhere) GHC does not check that these
-% are out of range (e.g., for a @Float@), and bad things will inevitably
-% follow.  (To be corrected?)
-% 
-% This problem does <em>not</em> exist for integral constants.
-% 
-% For very large/small fractional constants near the limits of your
-% floating-point precision, things may go wrong.  (It's better than it
-% used to be.)  Please report any such bugs.
-
 %-------------------------------------------------------------------
 <tag>Unchecked arithmetic:</tag>
 
@@ -143,9 +119,7 @@ main = print (array (1,1) [ 1:=2, 1:=3 ])
 <descrip>
 %-------------------------------------------------------------------
 <tag>Arbitrary-sized tuples:</tag>
-Plain old tuples of arbitrary size <em>do</em> work.  Note that lots of
-overloading can give rise to large tuples ``under the hood'' of your
-program.
+Plain old tuples of arbitrary size <em>do</em> work.
 
 HOWEVER: standard instances for tuples (@Eq@, @Ord@, @Bounded@, @Ix@
 @Read@, and @Show@) are available <em>only</em> up to 5-tuples.
@@ -155,7 +129,7 @@ stuck on them.
 
 %-------------------------------------------------------------------
 <tag>Unicode character set:</tag>
-Haskell 1.4 embraces the Unicode character set, but GHC 4.00 doesn't
+Haskell 98 embraces the Unicode character set, but GHC doesn't
 handle it. Yet.
 
 </descrip>
-- 
1.7.10.4