From: rrt Date: Mon, 24 Jan 2000 16:47:26 +0000 (+0000) Subject: [project @ 2000-01-24 16:47:24 by rrt] X-Git-Tag: Approximately_9120_patches~5229 X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=7db602a0d8f840362c455650cbddc1ecc04ec43d;p=ghc-hetmet.git [project @ 2000-01-24 16:47:24 by rrt] Changed double quotes to “ and ”. Improvements to Windows installation instructions. --- diff --git a/ghc/docs/users_guide/4-04-notes.sgml b/ghc/docs/users_guide/4-04-notes.sgml index 69ac428..a17baa1 100644 --- a/ghc/docs/users_guide/4-04-notes.sgml +++ b/ghc/docs/users_guide/4-04-notes.sgml @@ -13,7 +13,7 @@ -``Finalise'' is now spelt ``finalize'' in all function names. +“Finalise” is now spelt “finalize” in all function names. diff --git a/ghc/docs/users_guide/debugging.sgml b/ghc/docs/users_guide/debugging.sgml index 20cf599..e203081 100644 --- a/ghc/docs/users_guide/debugging.sgml +++ b/ghc/docs/users_guide/debugging.sgml @@ -390,10 +390,10 @@ when even doesn't cut it. -dppr-user option -dppr-debug option -Debugging output is in one of several ``styles.'' Take the printing -of types, for example. In the ``user'' style, the compiler's internal +Debugging output is in one of several “styles.” Take the printing +of types, for example. In the “user” style, the compiler's internal ideas about types are presented in Haskell source-level syntax, -insofar as possible. In the ``debug'' style (which is the default for +insofar as possible. In the “debug” style (which is the default for debugging output), the types are printed in with explicit foralls, and variables have their unique-id attached (so you can check for things that look the same but aren't). @@ -415,7 +415,7 @@ of transformation too place. If you add you get mo -ddump-raw-asm option -Dump out the assembly-language stuff, before the ``mangler'' gets it. +Dump out the assembly-language stuff, before the “mangler” gets it. @@ -522,16 +522,16 @@ skip2 m = m : skip2 (m+2) Before we jump in, a word about names of things. Within GHC, variables, type constructors, etc., are identified by their -``Uniques.'' These are of the form `letter' plus `number' (both +“Uniques.” These are of the form `letter' plus `number' (both loosely interpreted). The `letter' gives some idea of where the -Unique came from; e.g., _ means ``built-in type variable''; -t means ``from the typechecker''; s means ``from the -simplifier''; and so on. The `number' is printed fairly compactly in +Unique came from; e.g., _ means “built-in type variable”; +t means “from the typechecker”; s means “from the +simplifier”; and so on. The `number' is printed fairly compactly in a `base-62' format, which everyone hates except me (WDP). -Remember, everything has a ``Unique'' and it is usually printed out +Remember, everything has a “Unique” and it is usually printed out when debugging, in some form or another. So here we go… @@ -610,7 +610,7 @@ Main.skip2{-r1L6-} = -(``It's just a simple functional language'' is an unregisterised +(“It's just a simple functional language” is an unregisterised trademark of Peyton Jones Enterprises, plc.) diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index 6f2737e..f14d9f2 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -10,9 +10,9 @@ the language. To use them, you'll need to give a @@ -29,7 +29,7 @@ Executive summary of our extensions: You can get right down to the raw machine types and operations; -included in this are ``primitive arrays'' (direct access to Big Wads +included in this are “primitive arrays” (direct access to Big Wads of Bytes). Please see and following. @@ -113,8 +113,8 @@ Details in . Before you get too carried away working at the lowest level (e.g., sloshing MutableByteArray#s around your program), you may wish to -check if there are system libraries that provide a ``Haskellised -veneer'' over the features you want. See . +check if there are system libraries that provide a “Haskellised +veneer” over the features you want. See . @@ -126,7 +126,7 @@ veneer'' over the features you want. See . -These types correspond to the ``raw machine'' types you would use in +These types correspond to the “raw machine” types you would use in C: Int# (long int), Double# (double), Addr# (void *), etc. The primitive operations (PrimOps) on these types are what you might expect; e.g., (+#) is addition on Int#s, and is the @@ -149,7 +149,7 @@ results. Even worse, the unboxed value might be larger than a pointer Nevertheless, A numerically-intensive program using unboxed types can -go a lot faster than its ``standard'' counterpart—we saw a +go a lot faster than its “standard” counterpart—we saw a threefold speedup on one example. @@ -171,7 +171,7 @@ operations on them. This monad underlies our implementation of arrays, mutable and -immutable, and our implementation of I/O, including ``C calls''. +immutable, and our implementation of I/O, including “C calls”. @@ -211,7 +211,7 @@ Second, it distinguishes between… Immutable: -Arrays that do not change (as with ``standard'' Haskell arrays); you +Arrays that do not change (as with “standard” Haskell arrays); you can only read from them. Obviously, they do not need the care and attention of the state-transformer monad. @@ -221,29 +221,29 @@ attention of the state-transformer monad. Mutable: -Arrays that may be changed or ``mutated.'' All the operations on them +Arrays that may be changed or “mutated.” All the operations on them live within the state-transformer monad and the updates happen in-place. -``Static'' (in C land): +“Static” (in C land): A C routine may pass an Addr# pointer back into Haskell land. There are then primitive operations with which you may merrily grab values -over in C land, by indexing off the ``static'' pointer. +over in C land, by indexing off the “static” pointer. -``Stable'' pointers: +“Stable” pointers: If, for some reason, you wish to hand a Haskell pointer (i.e., not an unboxed value) to a C routine, you first make the -pointer ``stable,'' so that the garbage collector won't forget that it +pointer “stable,” so that the garbage collector won't forget that it exists. That is, GHC provides a safe way to pass Haskell pointers to C. @@ -254,14 +254,14 @@ Please see for more details. -``Foreign objects'': +“Foreign objects”: -A ``foreign object'' is a safe way to pass an external object (a +A “foreign object” is a safe way to pass an external object (a C-allocated pointer, say) to Haskell and have Haskell do the Right Thing when it no longer references the object. So, for example, C -could pass a large bitmap over to Haskell and say ``please free this -memory when you're done with it.'' +could pass a large bitmap over to Haskell and say “please free this +memory when you're done with it.” @@ -273,8 +273,8 @@ Please see for more details. -The libraries section gives more details on all these ``primitive -array'' types and the operations on them, . Some of these extensions +The libraries section gives more details on all these “primitive +array” types and the operations on them, . Some of these extensions are also supported by Hugs, and the supporting libraries are described in the fooH :: Char -> Int -> Double -> Word -> IO Double -fooH c i d w = _ccall_ fooC (``stdin''::Addr) c i d w +fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w @@ -350,7 +350,7 @@ import Addr import CString oldGetEnv name - = _casm_ ``%r = getenv((char *) %0);'' name >>= \ litstring -> + = _casm_ “%r = getenv((char *) %0);” name >>= \ litstring -> return ( if (litstring == nullAddr) then Left ("Fail:oldGetEnv:"++name) @@ -363,7 +363,7 @@ oldGetEnv name The first literal-literal argument to a _casm_ is like a printf -format: %r is replaced with the ``result,'' %0–%n-1 are +format: %r is replaced with the “result,” %0–%n-1 are replaced with the 1st–nth arguments. As you can see above, it is an easy way to do simple C casting. Everything said about _ccall_ goes for _casm_ as well. @@ -409,7 +409,7 @@ from the _casm_ construct itself. Indeed, we' fooH :: Char -> Int -> Double -> Word -> IO Double -fooH c i d w = _ccall_ fooC (``stdin''::Addr) c i d w +fooH c i d w = _ccall_ fooC (“stdin”::Addr) c i d w @@ -562,7 +562,7 @@ solid code. You're crazy not to do it. -Subverting automatic unboxing with ``stable pointers'' +<Title>Subverting automatic unboxing with “stable pointers” @@ -601,8 +601,8 @@ to boxed objects are not stable. -It is possible to subvert the unboxing process by creating a ``stable -pointer'' to a value and passing the stable pointer instead. For +It is possible to subvert the unboxing process by creating a “stable +pointer” to a value and passing the stable pointer instead. For example, to pass/return an integer lazily to C functions storeC and fetchC might write: @@ -769,7 +769,7 @@ atan2d y x = unsafePerformIO (_ccall_ atan2d y x) sincosd :: Double -> (Double, Double) sincosd x = unsafePerformIO $ do da <- newDoubleArray (0, 1) - _casm_ ``sincosd( %0, &((double *)%1[0]), &((double *)%1[1]) );'' x da + _casm_ “sincosd( %0, &((double *)%1[0]), &((double *)%1[1]) );” x da s <- readDoubleArray da 0 c <- readDoubleArray da 1 return (s, c) @@ -825,7 +825,7 @@ trace string expr ((_ccall_ PostTraceHook sTDERR{-msg-}):: IO ()) >> return expr ) where - sTDERR = (``stderr'' :: Addr) + sTDERR = (“stderr” :: Addr) @@ -841,7 +841,7 @@ useful in debugging code.) -C-calling ``gotchas'' checklist +<Title>C-calling “gotchas” checklist @@ -2851,7 +2851,7 @@ also OK to say: -To avoid ambiguity, the type after the ``::'' in a result +To avoid ambiguity, the type after the “::” in a result pattern signature on a lambda or case must be atomic (i.e. a single token or a parenthesised type of some sort). To see why, consider how one would parse this: @@ -2972,8 +2972,8 @@ but they might affect the efficiency of the generated code. pragma, INLINE -GHC (with , as always) tries to inline (or ``unfold'') -functions/values that are ``small enough,'' thus avoiding the call +GHC (with , 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. @@ -2983,7 +2983,7 @@ interface files. -Normally, if GHC decides a function is ``too expensive'' to inline, it +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. @@ -3006,7 +3006,7 @@ to stick the code through HBC—it doesn't like INLINE pr 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 +“cost” to be very low. The normal unfolding machinery will then be very keen to inline it. @@ -3719,7 +3719,7 @@ If you add you get a more detailed listing. Notice the INLINE! That prevents (:) from being inlined when compiling -PrelBase, so that an importing module will ``see'' the (:), and can +PrelBase, so that an importing module will “see” the (:), and can match it on the LHS of a rule. INLINE prevents any inlining happening in the RHS of the INLINE thing. I regret the delicacy of this. diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml index 094125c..b5910c9 100644 --- a/ghc/docs/users_guide/gone_wrong.sgml +++ b/ghc/docs/users_guide/gone_wrong.sgml @@ -20,7 +20,7 @@ be of interest.) -When the compiler ``does the wrong thing'' +<Title>When the compiler “does the wrong thing” @@ -32,7 +32,7 @@ be of interest.) -``Help! The compiler crashed (or `panic'd)!'' +“Help! The compiler crashed (or `panic'd)!” These events are always bugs in the GHC system—please report them. @@ -40,7 +40,7 @@ These events are always bugs in the GHC system—please -``The compiler ran out of heap (or stack) when compiling itself!'' +“The compiler ran out of heap (or stack) when compiling itself!” It happens. We try to supply reasonable flags for @@ -61,15 +61,15 @@ heap. -``The compiler died with a pattern-matching error.'' +“The compiler died with a pattern-matching error.” -This is a bug just as surely as a ``panic.'' Please report it. +This is a bug just as surely as a “panic.” Please report it. -``This is a terrible error message.'' +“This is a terrible error message.” If you think that GHC could have produced a better error message, @@ -78,7 +78,7 @@ please report it as a bug. -``What about these `trace' messages from GHC?'' +“What about these `trace' messages from GHC?” Almost surely not a problem. About some specific cases… @@ -96,7 +96,7 @@ turning on the -If the simplifier definitely seems to be ``looping,'' please report +If the simplifier definitely seems to be “looping,” please report it. @@ -106,10 +106,10 @@ it. -``What about this warning from the C compiler?'' +“What about this warning from the C compiler?” -For example: ``…warning: `Foo' declared `static' but never defined.'' +For example: “…warning: `Foo' declared `static' but never defined.” Unsightly, but shouldn't be a problem. @@ -132,11 +132,11 @@ running programs compiled using unstable interfaces. -``I think GHC is producing incorrect code'': +“I think GHC is producing incorrect code”: Unlikely :-) A useful be-more-paranoid option to give to GHC is --dcore-lint option; this causes a ``lint'' +-dcore-lint option; this causes a “lint” pass to check for errors (notably type errors) after each Core-to-Core transformation pass. We run with on all the time; it costs about 5% in compile time. @@ -144,7 +144,7 @@ costs about 5% in compile time. -``Why did I get a link error?'' +“Why did I get a link error?” If the linker complains about not finding _<something>_fast, then @@ -154,7 +154,7 @@ proper dependency order. -``What's a `consistency error'?'' +“What's a `consistency error'?” (These are reported just after linking your program.) @@ -176,11 +176,11 @@ tags/strings in your object files. They must all be the same! -``Is this line number right?'' +“Is this line number right?” On this score, GHC usually does pretty well, especially -if you ``allow'' it to be off by one or two. In the case of an +if you “allow” it to be off by one or two. In the case of an instance or class declaration, the line number may only point you to the declaration, not to a specific method. @@ -196,7 +196,7 @@ Please report line-number errors that you find particularly unhelpful. -When your program ``does the wrong thing'' +<Title>When your program “does the wrong thing” @@ -212,7 +212,7 @@ please see ). -``Help! My program crashed!'' +“Help! My program crashed!” (e.g., a `segmentation fault' or `core dumped') @@ -231,7 +231,7 @@ case these must be correct with respect to the module sourc For example, if an interface is lying about the type of an imported value then GHC may well generate duff code for the importing module. This applies to pragmas inside interfaces too! If the pragma is -lying (e.g., about the ``arity'' of a value), then duff code may result. +lying (e.g., about the “arity” of a value), then duff code may result. Furthermore, arities may change even if types do not. @@ -281,7 +281,7 @@ GHC-compiled program, please see . -``My program entered an `absent' argument.'' +“My program entered an `absent' argument.” This is definitely caused by a bug in GHC. Please report it. @@ -289,7 +289,7 @@ This is definitely caused by a bug in GHC. Please report it. -``What's with this `arithmetic (or `floating') exception' ''? +“What's with this `arithmetic (or `floating') exception' ”? Int, Float, and Double arithmetic is unchecked. @@ -322,7 +322,7 @@ not-really-a problem.) The name of the bug-reporting game is: facts, facts, facts. -Don't omit them because ``Oh, they won't be interested…'' +Don't omit them because “Oh, they won't be interested…” @@ -348,7 +348,7 @@ version of the operating system are you using? (uname -a or < Run the sequence of compiles/runs that caused the offending -behaviour, capturing all the input/output in a ``script'' (a UNIX +behaviour, capturing all the input/output in a “script” (a UNIX command) or in an Emacs shell window. We'd prefer to see the whole thing. diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml index 7a72e78..d668f21 100644 --- a/ghc/docs/users_guide/installing.sgml +++ b/ghc/docs/users_guide/installing.sgml @@ -6,7 +6,7 @@ Installing from binary distributions is easiest, and recommended! (Why binaries? Because GHC is a Haskell compiler written in Haskell, -so you've got to ``bootstrap'' it, somehow. We provide +so you've got to “bootstrap” it, somehow. We provide machine-generated C-files-from-Haskell for this purpose, but it's really quite a pain to use them. If you must build GHC from its sources, using a binary-distributed GHC to do so is a sensible way to @@ -27,7 +27,7 @@ so binary distributions allow you to install them without having a Haskell compi -Binary distributions come in ``bundles,'' one bundle per file called +Binary distributions come in “bundles,” one bundle per file called <bundle>-<platform>.tar.gz. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus: @@ -35,8 +35,7 @@ Binary distributions come in ``bundles,'' one bundle per file called % cd /your/scratch/space -% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - - +% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - @@ -209,8 +208,7 @@ moment % cd /your/scratch/space % gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf - -% gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf - - +% gunzip < happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf - @@ -239,9 +237,6 @@ directory to fptools and typing ./configure installing in-place in-place installation - - - You can now either start using the tools in-situ without going through any installation process, just type make in-place to set the tools up for this. You'll also want to add the path which make will @@ -357,7 +352,7 @@ stuff in your bin directory. - Once done, test your ``installation'' as suggested in + Once done, test your “installation” as suggested in . Be sure to use a -v option, so you can see exactly what pathnames it's using. @@ -376,7 +371,7 @@ When installing the user-invokable binaries, this installation procedure will install GHC as ghc-x.xx where x.xx is the version number of GHC. It will also make a link (in the binary installation directory) from ghc to ghc-x.xx. If you install multiple versions -of GHC then the last one ``wins'', and ``ghc'' will invoke the last +of GHC then the last one “wins”, and “ghc” will invoke the last one installed. You can change this manually if you want. But regardless, ghc-x.xx should always invoke GHC version x.xx. @@ -389,7 +384,7 @@ regardless, ghc-x.xx should always invoke GHC version bundles, binary -There are plenty of ``non-basic'' GHC bundles. The files for them are +There are plenty of “non-basic” GHC bundles. The files for them are called ghc-x.xx-<bundle>-<platform>.tar.gz, where the <platform> is as above, and <bundle> is one of these: @@ -421,7 +416,7 @@ You'll want this if you're into that kind of thing. gran: -The ``GranSim'' parallel-Haskell simulator +The “GranSim” parallel-Haskell simulator (hmm… mainly for implementors). bundles, gransim gransim bundles @@ -431,8 +426,8 @@ The ``GranSim'' parallel-Haskell simulator ticky: -``Ticky-ticky'' profiling; very detailed -information about ``what happened when I ran this program''—really +“Ticky-ticky” profiling; very detailed +information about “what happened when I ran this program”—really for implementors. bundles, ticky-ticky ticky-ticky bundles @@ -475,8 +470,7 @@ Compile the program, using the -v (verbose) flag to verify th libraries, etc., are being found properly: -% ghc -v -o hello Main.hs - +% ghc -v -o hello Main.hs @@ -485,8 +479,7 @@ Now run it: % ./hello -Hello, world! - +Hello, world! @@ -499,7 +492,7 @@ distributed in ghc/misc/examples/nfib/ in a source distributi -For more information on how to ``drive'' GHC, either do ghc -help or +For more information on how to “drive” GHC, either do ghc -help or consult the User's Guide (distributed in several pre-compiled formats with a binary distribution, or in source form in ghc/docs/users_guide in a source distribution). @@ -559,8 +552,8 @@ do the following: -Some environment variables are ``user variables'' and -some are ``system variables''. I'm not sure of the difference +Some environment variables are “user variables” and +some are “system variables”. I'm not sure of the difference but both are changed though the same dialogue. @@ -658,12 +651,6 @@ Create the following directories (if they aren't already there): -Add the two bin directories to your PATH. - - - - - Copy bash.exe from the bin directory of the cygwin tree (cygwin-b20/H-i586-cygwin32/bin/bash.exe) to @@ -677,71 +664,92 @@ directory, but (a) some UNIX utils have got -Add C:\cygnus\cygwin-b20\H-i586-cygwin32\bin to your PATH. -bash needs this, and when it is invoked from /bin it can't -find it. +If you're an Emacs user and want to be able to run bash +from within a shell buffer, see the NT Emacs home page for +instructions on how to set this up. - + + -Set your SHELL user environment variable to c:/bin/sh. +The following environment variables must be set: - - -Set your HOME user environment variable to point to your -home directory. This is where, for example, + + + + + + + +PATH +System + +Add C:\cygnus\cygwin-b20\H-i586-cygwin32\bin. +bash needs this, and when it is invoked from /bin it can't +find it. c:/bin and c:/usr/local/bin should also be added. + + + + +SHELL +User + +c:/bin/sh. + + + + +HOME +User + +Set to point to your home directory. This is where, for example, bash will look for your .bashrc file. - - - - - -Set your MAKE_MODE user environment variable to UNIX. If you don't do + + + + +MAKE_MODE +User + +Set to UNIX. If you don't do this you get very weird messages when you type `make', such as: - - - -/c: /c: No such file or directory - - - - - -Set the TMPDIR user environment variable to -c:/tmp. For some reason, Win2k invisibly sets + +/c: /c: No such file or directory + + + +TMPDIR +User + +Set to c:/tmp. For some reason, Win2k invisibly sets this variable to point to a temporary directory in your profile, that contains embedded spaces. If GHC sees the TMPDIR variable set, it tries to use it for temporary files, but Cygwin doesn't grok filenames with spaces, so disaster results. - - + Furthermore, it seems that TMPDIR must be set to a directory in the same file system in which you invoke GHC. Otherwise you get very werid messages when you invoke GHC, such as: - does not exist - Action: openFile - Reason: file does not exist /tmp/ghc11068.cpp - +does not exist +Action: openFile +Reason: file does not exist /tmp/ghc11068.cpp We think this is due to a bug in Cygwin. - - + + + - - -If you're an Emacs user and want to be able to run bash -from within a shell buffer, see the NT Emacs home page for -instructions on how to set this up. + + - - + Perl5 @@ -847,8 +855,7 @@ bash$ /path/to/the/ghc/bin/directory/ghc-4.05 -o main main.hs .. bash$ ./main Hello, world! -bash$ - +bash$ OK, assuming that worked, you're all set. Go forth and write useful @@ -903,8 +910,7 @@ When compiling up the Hello World example, the following happ bash$ /ghc/ghc-4.05/bin/ghc-4.05 main.hs <stdin>:0:25: Character literal '{-# LINE 1 "main.hs" -}' too long <stdin>:0:25: on input: "'" -bash$ - +bash$ or @@ -913,8 +919,7 @@ or bash$ /ghc/ghc-4.05/bin/ghc-4.05 main.hs Program too big fit into memory under NT -bash$ - +bash$ @@ -944,8 +949,7 @@ files within the directory tree that the installer created: bin/ghc-4.xx -- where xx is the minor release number bin/stat2resid bin/hstags -lib/mkdependHS - +lib/mkdependHS For each of these files, you need to edit the first line from instead @@ -965,7 +969,7 @@ of perl instead, a cygwin port -System.getArgs always return the empty list, i.e. the following program always prints "[]": +System.getArgs always return the empty list, i.e. the following program always prints “[]”: diff --git a/ghc/docs/users_guide/intro.sgml b/ghc/docs/users_guide/intro.sgml index f7a33fd..fb8e9e7 100644 --- a/ghc/docs/users_guide/intro.sgml +++ b/ghc/docs/users_guide/intro.sgml @@ -7,7 +7,7 @@ This is a guide to using the Glasgow Haskell compilation (GHC) system. It is a batch compiler for the Haskell 98 language, with support for various Glasgow-only extensions. In this document, we assume that GHC has been installed at your site as ghc. A separate document, -``Building and Installing the Glasgow Functional Programming Tools Suite'', +“Building and Installing the Glasgow Functional Programming Tools Suite”, describes how to install ghc. @@ -46,7 +46,7 @@ compilation systems, has several interacting parts: A driverdriver program ghcghc—which -you usually think of as ``the compiler''—is a program that merely +you usually think of as “the compiler”—is a program that merely invokes/glues-together the other pieces of the system (listed below), passing the right options to each, slurping in the right libraries, etc. @@ -70,7 +70,7 @@ The Haskellised C pre-processor C pre-processor, Haskellised pre-processor, Haskellised C hscpp,hscpp only needed by people requiring conditional -compilation, probably for large systems. The ``Haskellised'' part +compilation, probably for large systems. The “Haskellised” part just means that #line directives in the output have been converted into proper Haskell {-# LINE ... -} pragmas. You must give an explicit -cpp option -cpp option for the C pre-processor to be invoked. @@ -143,13 +143,13 @@ Parts of other installed libraries that you have at your si -What really happens when I ``compile'' a Haskell program? +<Title>What really happens when I “compile” a Haskell program? You invoke the Glasgow Haskell compilation system through the driver program ghc.ghc For example, if you had typed a -literate ``Hello, world!'' program into hello.lhs, and you then +literate “Hello, world!” program into hello.lhs, and you then invoked: @@ -181,7 +181,7 @@ input for -The assembler (or that ubiquitous ``high-level assembler,'' a C +The assembler (or that ubiquitous “high-level assembler,” a C compiler), which produces an object file and passes it to @@ -201,8 +201,8 @@ the default output file named a.out. You have considerable control over the compilation process. You feed -command-line arguments (call them ``options,'' for short) to the -driver, ghc; the ``types'' of the input files (as encoded in +command-line arguments (call them “options,” for short) to the +driver, ghc; the “types” of the input files (as encoded in their names' suffixes) also matter. diff --git a/ghc/docs/users_guide/libraries.sgml b/ghc/docs/users_guide/libraries.sgml index 1463301..ab91f33 100644 --- a/ghc/docs/users_guide/libraries.sgml +++ b/ghc/docs/users_guide/libraries.sgml @@ -552,7 +552,7 @@ data Integer = S# Int# -- small integers Integer type -The primitive ops to support large Integers use the ``pieces'' of the +The primitive ops to support large Integers use the “pieces” of the representation, and are as follows: @@ -681,7 +681,7 @@ type checker happy. Operations for indexing off of C pointers (Addr#s) to snatch values -are listed under ``arrays''. +are listed under “arrays”. @@ -784,9 +784,9 @@ primitive ops compile to one machine instruction or thereabouts. -We use the terms ``reading'' and ``writing'' to refer to accessing +We use the terms “reading” and “writing” to refer to accessing mutable arrays (see ), and -``indexing'' to refer to reading a value from an immutable +“indexing” to refer to reading a value from an immutable array. @@ -861,7 +861,7 @@ serves to keep states from distinct threads distinct from one another. But the only effect of this parameterisation is in the type system: all values of type State# are represented in the same way. Indeed, they are all represented by nothing at all! The code -generator ``knows'' to generate no code, and allocate no registers +generator “knows” to generate no code, and allocate no registers etc, for primitive states. @@ -875,7 +875,7 @@ type State# s The type GHC.RealWorld is truly opaque: there are no values defined -of this type, and no operations over it. It is ``primitive'' in that +of this type, and no operations over it. It is “primitive” in that sense - but it is not unlifted! Its only role in life is to be the type which distinguishes the IO state transformer. @@ -946,7 +946,7 @@ type MutableByteArray# s Mutable arrays can be allocated. Only pointer-arrays are initialised; -arrays of non-pointers are filled in by ``user code'' rather than by +arrays of non-pointers are filled in by “user code” rather than by the array-allocation primitive. Reason: only the pointer case has to worry about GC striking with a partly-initialised array. @@ -1026,7 +1026,7 @@ writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State -One can take ``equality'' of mutable arrays. What is compared is the +One can take “equality” of mutable arrays. What is compared is the name or reference to the mutable array, not its contents. diff --git a/ghc/docs/users_guide/parallel.sgml b/ghc/docs/users_guide/parallel.sgml index f04ec81..4970b09 100644 --- a/ghc/docs/users_guide/parallel.sgml +++ b/ghc/docs/users_guide/parallel.sgml @@ -44,13 +44,13 @@ multiple processors, under a PVM (Parallel Virtual Machine) framework. -Parallel Haskell is still relatively new; it is more about ``research -fun'' than about ``speed.'' That will change. +Parallel Haskell is still relatively new; it is more about “research +fun” than about “speed.” That will change. Again, check Simon's Web page for publications about Parallel Haskell -(including ``GUM'', the key bits of the runtime system). +(including “GUM”, the key bits of the runtime system). diff --git a/ghc/docs/users_guide/profiling.sgml b/ghc/docs/users_guide/profiling.sgml index 613a8bc..6e53999 100644 --- a/ghc/docs/users_guide/profiling.sgml +++ b/ghc/docs/users_guide/profiling.sgml @@ -12,7 +12,7 @@ execution behaviour, so you can improve it. Any comments, suggestions and/or improvements you have are welcome. -Recommended ``profiling tricks'' would be especially cool! +Recommended “profiling tricks” would be especially cool! @@ -21,7 +21,7 @@ Recommended ``profiling tricks'' would be especially cool! The GHC approach to profiling is very simple: annotate the expressions -you consider ``interesting'' with cost centre labels (strings); +you consider “interesting” with cost centre labels (strings); so, for example, you might have: @@ -40,8 +40,8 @@ f x y The costs of the evaluating the expressions bound to output1, -output2 and output3 will be attributed to the ``cost -centres'' Pass1, Pass2 and Pass3, respectively. +output2 and output3 will be attributed to the “cost +centres” Pass1, Pass2 and Pass3, respectively. @@ -52,8 +52,8 @@ will be inherited by the scope which referenced the function f You can put in cost-centres via _scc_ constructs by hand, as in the example above. Perfectly cool. That's probably what you -would do if your program divided into obvious ``passes'' or -``phases'', or whatever. +would do if your program divided into obvious “passes” or +“phases”, or whatever. @@ -71,7 +71,7 @@ your own. To use profiling, you must compile and run with special -options. (We usually forget the ``run'' magic!—Do as we say, not as +options. (We usually forget the “run” magic!—Do as we say, not as we do…) Details follow. @@ -139,8 +139,8 @@ all top-level, exported functions. -caf-all option The costs of all CAFs in a module are usually attributed to one -``big'' CAF cost-centre. With this option, all CAFs get their own cost-centre. -An ``if all else fails'' option… +“big” CAF cost-centre. With this option, all CAFs get their own cost-centre. +An “if all else fails” option… @@ -447,8 +447,8 @@ centre) is selected by the option (or the option is not specified). When you run your profiled program with the RTS option -p -RTS option, you get the following information about your ``cost -centres'': +RTS option, you get the following information about your “cost +centres”: @@ -477,7 +477,7 @@ different modules. How many times this cost-centre was entered; think -of it as ``I got to the _scc_ construct this many times…'' +of it as “I got to the _scc_ construct this many times…” @@ -485,7 +485,7 @@ of it as ``I got to the _scc_ construct this %time: -What part of the time was spent in this cost-centre (see also ``ticks,'' +What part of the time was spent in this cost-centre (see also “ticks,” below). @@ -495,7 +495,7 @@ below). What part of the memory allocation was done in this cost-centre -(see also ``bytes,'' below). +(see also “bytes,” below). @@ -503,10 +503,10 @@ What part of the memory allocation was done in this cost-centre inner: -How many times this cost-centre ``passed control'' to an inner +How many times this cost-centre “passed control” to an inner cost-centre; for example, scc=4 plus subscc=8 means -``This _scc_ was entered four times, but went out to -other _scc_s eight times.'' +“This _scc_ was entered four times, but went out to +other _scc_s eight times.” @@ -539,7 +539,7 @@ In addition you can use the RTS option < ticks: -The raw number of time ``ticks'' which were +The raw number of time “ticks” which were attributed to this cost-centre; from this, we get the %time figure mentioned above. @@ -571,7 +571,7 @@ produce the following information: closures, profiling How many heap objects were allocated; these objects may be of varying size. If you divide the number of bytes (mentioned below) by this -number of ``closures'', then you will get the average object size. +number of “closures”, then you will get the average object size. (Not too interesting, but still…) @@ -855,7 +855,7 @@ distribution. -Using ``ticky-ticky'' profiling (for implementors) +<Title>Using “ticky-ticky” profiling (for implementors) @@ -870,21 +870,21 @@ distribution. It is possible to compile Glasgow Haskell programs so that they will count lots and lots of interesting things, e.g., number of updates, number of data constructors entered, etc., etc. We call this -``ticky-ticky'' profiling,ticky-ticky profiling +“ticky-ticky” profiling,ticky-ticky profiling profiling, ticky-ticky because that's the sound a Sun4 makes when it is running up all those counters (slowly). Ticky-ticky profiling is mainly intended for implementors; it is quite -separate from the main ``cost-centre'' profiling system, intended for +separate from the main “cost-centre” profiling system, intended for all users everywhere. To be able to use ticky-ticky profiling, you will need to have built appropriate libraries and things when you made the system. See -``Customising what libraries to build,'' in the installation guide. +“Customising what libraries to build,” in the installation guide. diff --git a/ghc/docs/users_guide/runtime_control.sgml b/ghc/docs/users_guide/runtime_control.sgml index e4f02d6..43a832f 100644 --- a/ghc/docs/users_guide/runtime_control.sgml +++ b/ghc/docs/users_guide/runtime_control.sgml @@ -315,7 +315,7 @@ The RTS options related to profiling are described in . @@ -378,7 +378,7 @@ bits are set in <num>. Only works if the RTS was compi -Z RTS option -Turn off ``update-frame squeezing'' at garbage-collection +Turn off “update-frame squeezing” at garbage-collection time. (There's no particularly good reason to turn it off, except to ensure the accuracy of certain data collected regarding thunk entry counts.) @@ -391,7 +391,7 @@ counts.) -``Hooks'' to change RTS behaviour +<Title>“Hooks” to change RTS behaviour @@ -402,7 +402,7 @@ counts.) GHC lets you exercise rudimentary control over the RTS settings for -any given program, by compiling in a ``hook'' that is called by the +any given program, by compiling in a “hook” that is called by the run-time system. The RTS contains stub definitions for all these hooks, but by writing your own version and linking it on the GHC command line, you can override the defaults. @@ -436,7 +436,7 @@ defined in ghc/rts/RtsFlags.h the the GHC source tree. You can also change the messages printed when the runtime system -``blows up,'' e.g., on stack overflow. The hooks for these are as +“blows up,” e.g., on stack overflow. The hooks for these are as follows: @@ -511,7 +511,7 @@ What's printed out after a trace message. -For example, here is the ``hooks'' code used by GHC itself: +For example, here is the “hooks” code used by GHC itself: #include <stdio.h> diff --git a/ghc/docs/users_guide/sooner.sgml b/ghc/docs/users_guide/sooner.sgml index e183562..dd38339 100644 --- a/ghc/docs/users_guide/sooner.sgml +++ b/ghc/docs/users_guide/sooner.sgml @@ -3,7 +3,7 @@ -Please advise us of other ``helpful hints'' that should go here! +Please advise us of other “helpful hints” that should go here! @@ -67,9 +67,9 @@ bug. Don't use too much memory! -As soon as GHC plus its ``fellow citizens'' (other processes on your +As soon as GHC plus its “fellow citizens” (other processes on your machine) start using more than the real memory on your -machine, and the machine starts ``thrashing,'' the party is +machine, and the machine starts “thrashing,” the party is over. Compile times will be worse than terrible! Use something like the csh-builtin time command to get a report on how many page faults you're getting. @@ -203,8 +203,8 @@ Augustsson.) Please report any overly-slow GHC-compiled programs. The current -definition of ``overly-slow'' is ``the HBC-compiled version ran -faster''… +definition of “overly-slow” is “the HBC-compiled version ran +faster”… @@ -284,7 +284,7 @@ Specialize the overloading on key functions in your program. See -``But how do I know where overloading is creeping in?'': +“But how do I know where overloading is creeping in?”: A low-tech way: grep (search) your interface files for overloaded @@ -309,7 +309,7 @@ and, among other things, lazy pattern-matching is your enemy. -(If you don't know what a ``strict function'' is, please consult a +(If you don't know what a “strict function” is, please consult a functional-programming textbook. A sentence or two of explanation here probably would not do much good.) @@ -368,7 +368,7 @@ will be optimised away in most cases. -``How do I find out a function's strictness?'' +“How do I find out a function's strictness?” Don't guess—look it up. @@ -378,17 +378,17 @@ Don't guess—look it up. Look for your function in the interface file, then for the third field in the pragma; it should say _S_ <string>. The <string> gives the strictness of the function's arguments. L is lazy -(bad), S and E are strict (good), P is ``primitive'' (good), +(bad), S and E are strict (good), P is “primitive” (good), U(...) is strict and -``unpackable'' (very good), and A is absent (very good). +“unpackable” (very good), and A is absent (very good). -For an ``unpackable'' U(...) argument, the info inside +For an “unpackable” U(...) argument, the info inside tells the strictness of its components. So, if the argument is a -pair, and it says U(AU(LSS)), that means ``the first component of the +pair, and it says U(AU(LSS)), that means “the first component of the pair isn't used; the second component is itself unpackable, with three -components (lazy in the first, strict in the second \& third).'' +components (lazy in the first, strict in the second \& third).” @@ -448,7 +448,7 @@ operations (e.g., eqInt#) are good,… When you are really desperate for speed, and you want to get -right down to the ``raw bits.'' Please see for some information about using unboxed +right down to the “raw bits.” Please see for some information about using unboxed types. @@ -519,11 +519,11 @@ indicate that it's doing lots of garbage-collection (say, more than -Decrease the ``go-for-it'' threshold for unfolding smallish +Decrease the “go-for-it” threshold for unfolding smallish expressions. Give a -funfolding-use-threshold0 -option option for the extreme case. (``Only unfoldings with -zero cost should proceed.'') Warning: except in certain specialiised +option option for the extreme case. (“Only unfoldings with +zero cost should proceed.”) Warning: except in certain specialiised cases (like Happy parsers) this is likely to actually increase the size of your program, because unfolding generally enables extra simplifying optimisations to be performed. @@ -550,7 +550,7 @@ Use strip on your executables. -``I think I have a space leak…'' Re-run your program with +“I think I have a space leak…” Re-run your program with ,-Sstderr RTS option and remove all doubt! (You'll see the heap usage get bigger and bigger…) [Hmmm…this might be even easier with the -F2s RTS option RTS diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index f83a3fb..2a9dc56 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -61,8 +61,8 @@ want. (Usually, the last one applies.) -File names with ``meaningful'' suffixes (e.g., .lhs or .o) -cause the ``right thing'' to happen to those files. +File names with “meaningful” suffixes (e.g., .lhs or .o) +cause the “right thing” to happen to those files. @@ -73,7 +73,7 @@ cause the ``right thing'' to happen to those files. lhs suffix -A ``literate Haskell'' module. +A “literate Haskell” module. @@ -202,8 +202,8 @@ then go all the way through linking. This table summarises: Phase of the compilation system -Suffix saying ``start here'' -Flag saying ``stop after'' +Suffix saying “start here” +Flag saying “stop after” (suffix of) output file @@ -307,7 +307,7 @@ phase to file foo. -Note: this ``feature'' can be counterintuitive: +Note: this “feature” can be counterintuitive: ghc -C -o foo.o foo.hs will put the intermediate C code in the file foo.o, name notwithstanding! @@ -318,7 +318,7 @@ EXOTICA: But the option isn't of much use if you have normally put in the same directory as their corresponding input file came from. You may specify that they be put in another directory using the -odir <dir> option (the -``Oh, dear'' option). For example: +“Oh, dear” option). For example: @@ -428,7 +428,7 @@ compilation. By default, you get a standard set of warnings which are generally likely to indicate bugs in your program. These are: , , and . The following flags are simple ways to -select standard ``packages'' of warnings: +select standard “packages” of warnings: @@ -799,8 +799,8 @@ it looks. -i<dirs> optionThis flag -prepends a colon-separated list of dirs to the ``import -directories'' list. +prepends a colon-separated list of dirs to the “import +directories” list. See also for the significance of using relative and absolute pathnames in the list. @@ -811,7 +811,7 @@ relative and absolute pathnames in the list. -resets the ``import directories'' list back to nothing. +resets the “import directories” list back to nothing. @@ -888,7 +888,7 @@ record the difference in the interface file itself, the -The .hi files from GHC contain ``usage'' information which changes +The .hi files from GHC contain “usage” information which changes often and uninterestingly. If you really want to see these changes reported, you need to use the -hi-diffs-with-usages option @@ -956,13 +956,13 @@ file was last compiled), GHC will be clever. It compares the version numbers on the things it needs this time with the version numbers on the things it needed last time (gleaned from the interface file of the module being compiled); if they are all the same it stops compiling -rather early in the process saying ``Compilation IS NOT required''. +rather early in the process saying “Compilation IS NOT required”. What a beautiful sight! -GHC only keeps detailed dependency information for ``user'' modules, -not for ``library'' modules. It distinguishes the two by a hack: a module +GHC only keeps detailed dependency information for “user” modules, +not for “library” modules. It distinguishes the two by a hack: a module whose .hi file has an absolute path name is considered a library module, while a relative path name indicates a user module. So if you have a multi-directory application, use relative path names in your @@ -972,8 +972,8 @@ library modules. -A path is considered ``absolute'' if it starts with ``/'', or -``A:/'', or ``A:\'' (or ``B:/'', ``B:\'' etc). +A path is considered “absolute” if it starts with “/”, or +“A:/”, or “A:\” (or “B:/”, “B:\” etc). @@ -1118,7 +1118,7 @@ interfaces in the first place (e.g., make Bar.o to create You may have to type make more than once for the dependencies to have full effect. However, a make run that does nothing -does mean ``everything's up-to-date.'' +does mean “everything's up-to-date.” @@ -1126,7 +1126,7 @@ to have full effect. However, a make run that does nothing This scheme will work with mutually-recursive modules but, -again, it may take multiple iterations to ``settle.'' +again, it may take multiple iterations to “settle.” @@ -1231,15 +1231,15 @@ Notice that we only put the declaration for the newtype TA in -The number ``1'' after ``__interface A'' gives the version number of module A; -it is incremented whenever anything in A's interface file changes. The ``404'' is +The number “1” after “__interface A” gives the version number of module A; +it is incremented whenever anything in A's interface file changes. The “404” is the version number of the interface file syntax; we change it when we change the syntax of interface files so that you get a better error message when you try to read an old-format file with a new-format compiler. -The number ``1'' at the beginning of a declaration is the version +The number “1” at the beginning of a declaration is the version number of that declaration: for the purposes of .hi-boot files these can all be set to 1. All names must be fully qualified with the original module that an object comes from: for example, the @@ -1287,7 +1287,7 @@ construction of interface files, is (allegedly) in the works. -The options specify convenient ``packages'' of optimisation +The options specify convenient “packages” of optimisation flags; the options described later on specify individual optimisations to be turned on/off; the options specify machine-specific optimisations to be turned @@ -1295,7 +1295,7 @@ on/off. -<Option>-O*</Option>: convenient ``packages'' of optimisation flags. +<Title><Option>-O*</Option>: convenient “packages” of optimisation flags. @@ -1305,13 +1305,13 @@ on/off. There are many options that affect the quality of code produced by GHC. Most people only have a general goal, something like -``Compile quickly'' or ``Make my program run like greased lightning.'' -The following ``packages'' of optimisations (or lack thereof) should +“Compile quickly” or “Make my program run like greased lightning.” +The following “packages” of optimisations (or lack thereof) should suffice. -Once you choose a ``package,'' stick with it—don't chop and +Once you choose a “package,” stick with it—don't chop and change. Modules' interfaces will change with a shift to a new option, and you may have to recompile a large chunk of all importing modules before your program can again be run @@ -1326,8 +1326,8 @@ safely (see ). -O* not specified -This is taken to mean: ``Please compile quickly; I'm not over-bothered -about compiled-code quality.'' So, for example: ghc -c Foo.hs +This is taken to mean: “Please compile quickly; I'm not over-bothered +about compiled-code quality.” So, for example: ghc -c Foo.hs @@ -1338,7 +1338,7 @@ about compiled-code quality.'' So, for example: ghc -c Foo.hs-O option -O1 option optimise normally -Means: ``Generate good-quality code without taking too long about it.'' +Means: “Generate good-quality code without taking too long about it.” Thus, for example: ghc -c -O Main.lhs @@ -1349,12 +1349,12 @@ Thus, for example: ghc -c -O Main.lhs -O2 option optimise aggressively -Means: ``Apply every non-dangerous optimisation, even if it means -significantly longer compile times.'' +Means: “Apply every non-dangerous optimisation, even if it means +significantly longer compile times.” -The avoided ``dangerous'' optimisations are those that can make +The avoided “dangerous” optimisations are those that can make runtime or space worse if you're unlucky. They are normally turned on or off individually. @@ -1389,7 +1389,7 @@ generator and bypass GCC altogether! -This option will make GHC ``forget'' any ish options it has seen so +This option will make GHC “forget” any ish options it has seen so far. Sometimes useful; for example: make all EXTRA_HC_OPTS=-Onot. @@ -1429,7 +1429,7 @@ something. When we want to go for broke, we tend to use -``Yacc for Haskell'': <Command>happy</Command> +<Title>“Yacc for Haskell”: <Command>happy</Command> diff --git a/ghc/docs/users_guide/vs_haskell.sgml b/ghc/docs/users_guide/vs_haskell.sgml index 167fbd6..2b6bb34 100644 --- a/ghc/docs/users_guide/vs_haskell.sgml +++ b/ghc/docs/users_guide/vs_haskell.sgml @@ -9,7 +9,7 @@ This section lists Glasgow Haskell infelicities in its implementation -of Haskell 98. See also the ``when things go wrong'' section +of Haskell 98. See also the “when things go wrong” section () for information about crashes, space leaks, and other undesirable phenomena. @@ -30,7 +30,7 @@ The limitations here are listed in Haskell-Report order (roughly). Very long String constants: -May not go through. If you add a ``string gap'' every +May not go through. If you add a “string gap” every few thousand characters, then the strings can be as long as you like. @@ -45,7 +45,7 @@ option don't mix very well (see ). Very long literal lists: -These may tickle a ``yacc stack overflow'' error in the parser. +These may tickle a “yacc stack overflow” error in the parser. (It depends on the Yacc used to build your parser.)