diff options
| author | krasimir <unknown> | 2004-08-08 17:26:47 +0000 |
|---|---|---|
| committer | krasimir <unknown> | 2004-08-08 17:26:47 +0000 |
| commit | 2dfd507259664e6f28df4a9467a8de34d01d70a0 (patch) | |
| tree | 2df23a3e13d00563d07aff62f05ea2b3feb2b6dd | |
| parent | dc801dc275fb8f81d482535b4d6317e234bb10f8 (diff) | |
| download | haskell-2dfd507259664e6f28df4a9467a8de34d01d70a0.tar.gz | |
[project @ 2004-08-08 17:26:26 by krasimir]
xmlize sgml docbooks
26 files changed, 1379 insertions, 1385 deletions
diff --git a/ghc/docs/users_guide/6.0-notes.sgml b/ghc/docs/users_guide/6.0-notes.sgml index 19c558599a..1973bfc431 100644 --- a/ghc/docs/users_guide/6.0-notes.sgml +++ b/ghc/docs/users_guide/6.0-notes.sgml @@ -7,7 +7,7 @@ <listitem> <para>Template Haskell, a new feature for compile-time metaprogramming has been introduced. See <xref - linkend="template-haskell">.</para> + linkend="template-haskell"/>.</para> </listitem> <listitem> <para>INLINE pragmas on methods in class or instance @@ -15,7 +15,7 @@ </listitem> <listitem> <para>Recursive do-notation (aka <literal>mdo</literal>) is - now supported. See <xref linkend="mdo-notation">.</para> + now supported. See <xref linkend="mdo-notation"/>.</para> </listitem> <listitem> <para>There is now a native code generator for PowerPC @@ -24,7 +24,7 @@ <listitem> <para>Profiling: the <option>-xt</option> RTS option enables inclusion of thread stacks in a heap profile. See <xref - linkend="rts-options-heap-prof">.</para> + linkend="rts-options-heap-prof"/>.</para> </listitem> <listitem> <para>Non-blocking I/O is now supported on Windows.</para> @@ -55,7 +55,7 @@ <para>Hierarchical libraries are now available without needing to specify an explicit <option>-package</option> flag. There are some exceptions to this rule (see <xref - linkend="using-packages">), but if you stick to GHCi and + linkend="using-packages"/>), but if you stick to GHCi and <option>--make</option> mode then there will normally be no need to specify <option>-package</option> options at all.</para> diff --git a/ghc/docs/users_guide/bugs.sgml b/ghc/docs/users_guide/bugs.sgml index 311c2eb229..5d7c0bb643 100644 --- a/ghc/docs/users_guide/bugs.sgml +++ b/ghc/docs/users_guide/bugs.sgml @@ -1,4 +1,4 @@ -<Chapter id="bugs-and-infelicities"> +<chapter id="bugs-and-infelicities"> <title>Known bugs and infelicities</title> <sect1 id="vs-Haskell-defn"> @@ -10,7 +10,7 @@ <para>This section lists Glasgow Haskell infelicities in its implementation of Haskell 98. See also the “when things - go wrong” section (<XRef LinkEnd="wrong">) for information + go wrong” section (<xref linkend="wrong"/>) for information about crashes, space leaks, and other undesirable phenomena.</para> <para>The limitations here are listed in Haskell Report order @@ -67,7 +67,7 @@ (let x = 42 in x == 42 == True)</programlisting> The Haskell report is arguably wrong here, but nevertheless - it's a difference between GHC & Haskell 98.</para> + it's a difference between GHC & Haskell 98.</para> </listitem> </itemizedlist> </sect3> @@ -256,7 +256,7 @@ checking for duplicates. The reason for this is efficiency, pure and simple. <itemizedlist> <listitem> <para> GHC can warn about non-exhaustive or overlapping - patterns (see <xref linkend="options-sanity">), and usually + patterns (see <xref linkend="options-sanity"/>), and usually does so correctly. But not always. It gets confused by string patterns, and by guards, and can then emit bogus warnings. The entire overlap-check code needs an overhaul diff --git a/ghc/docs/users_guide/debugging.sgml b/ghc/docs/users_guide/debugging.sgml index 308a5f5d4f..340d7d8251 100644 --- a/ghc/docs/users_guide/debugging.sgml +++ b/ghc/docs/users_guide/debugging.sgml @@ -5,7 +5,7 @@ <para>HACKER TERRITORY. HACKER TERRITORY. (You were warned.)</para> - <Sect2 id="dumping-output"> + <sect2 id="dumping-output"> <title>Dumping out compiler intermediate structures</title> <indexterm><primary>dumping GHC intermediates</primary></indexterm> @@ -246,9 +246,9 @@ STG-to-STG passes, respectively. (<emphasis>Lots</emphasis> of output!) So: when we're really desperate:</para> - <Screen> + <screen> % ghc -noC -O -ddump-simpl -dverbose-simpl -dcore-lint Foo.hs -</Screen> +</screen> </listitem> </varlistentry> @@ -384,9 +384,9 @@ <para>Let's do this by commenting an example. It's from doing <option>-ddump-ds</option> on this code: -<ProgramListing> +<programlisting> skip2 m = m : skip2 (m+2) -</ProgramListing> +</programlisting> Before we jump in, a word about names of things. Within GHC, variables, type constructors, etc., are identified by their @@ -403,7 +403,7 @@ skip2 m = m : skip2 (m+2) usually printed out when debugging, in some form or another. So here we go…</para> -<ProgramListing> +<programlisting> Desugared: Main.skip2{-r1L6-} :: _forall_ a$_4 =>{{Num a$_4}} -> a$_4 -> [a$_4] @@ -473,7 +473,7 @@ Main.skip2{-r1L6-} = {- end CoRec -} } in skip2.t3Ja -</ProgramListing> +</programlisting> <para>(“It's just a simple functional language” is an unregisterised trademark of Peyton Jones Enterprises, plc.)</para> @@ -512,7 +512,7 @@ Main.skip2{-r1L6-} = </variablelist> </sect2> -</Sect1> +</sect1> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/faq.sgml b/ghc/docs/users_guide/faq.sgml index beda1cb7c6..8618deea52 100644 --- a/ghc/docs/users_guide/faq.sgml +++ b/ghc/docs/users_guide/faq.sgml @@ -95,7 +95,7 @@ <listitem> <para>If you're also using CPP, beware of the known pitfall with string gaps mentioned in <xref - linkend="cpp-string-gaps">.</para> + linkend="cpp-string-gaps"/>.</para> </listitem> </varlistentry> @@ -190,7 +190,7 @@ <listitem> <para>You should use the <option>-#include</option> option to bring the correct prototype into scope (see <xref - linkend="options-C-compiler">).</para> + linkend="options-C-compiler"/>).</para> </listitem> </varlistentry> @@ -252,7 +252,7 @@ -auto-all</literal> (make sure you have the profiling libraries installed), and run it with <literal>+RTS -xc -RTS</literal> to get a “stack trace” at the point at which the exception was -raised. See <xref linkend="rts-options-debugging"> for more +raised. See <xref linkend="rts-options-debugging"/> for more details.</para> </listitem> </varlistentry> @@ -261,7 +261,7 @@ details.</para> <term>How do I increase the heap size permanently for a given binary?</term> <listitem> - <para>See <xref linkend="rts-hooks">.</para> + <para>See <xref linkend="rts-hooks"/>.</para> </listitem> </varlistentry> @@ -370,7 +370,7 @@ details.</para> main = do putStr "how are you today? " hFlush stdout - input <- hGetLine + input &- hGetLine ...</programlisting> <para>You'll probably find that the behaviour differs when @@ -426,7 +426,7 @@ details.</para> Include files named by <option>-#include</option> options or in <literal>foreign import</literal> declarations are only used in via-C compilation mode. See <xref - linkend="finding-header-files"> for more details.</para> + linkend="finding-header-files"/> for more details.</para> </listitem> </varlistentry> @@ -442,7 +442,7 @@ details.</para> <screen>ghc --make -prof -o foo-prof -osuf p.o -hisuf p.hi Main</screen> - <para>See <xref linkend="options-output"> for more details on + <para>See <xref linkend="options-output"/> for more details on the <option>-osuf</option> and <option>-hisuf</option> options.</para> </listitem> diff --git a/ghc/docs/users_guide/ffi-chap.sgml b/ghc/docs/users_guide/ffi-chap.sgml index d622179dc7..6c266cdec3 100644 --- a/ghc/docs/users_guide/ffi-chap.sgml +++ b/ghc/docs/users_guide/ffi-chap.sgml @@ -1,11 +1,11 @@ <!-- FFI docs as a chapter --> -<Chapter id="ffi"> -<Title>Foreign function interface (FFI)</Title> +<chapter id="ffi"> +<title>Foreign function interface (FFI)</title> <para>GHC (mostly) conforms to the Haskell 98 Foreign Function Interface - Addendum 1.0, whose definition is available from <ULink - URL="http://haskell.org/"><literal>http://haskell.org/</literal></ULink >. + Addendum 1.0, whose definition is available from <ulink + URL="http://haskell.org/"><literal>http://haskell.org/</literal></ulink >. The FFI support in GHC diverges from the Addendum in the following ways: </para> @@ -18,7 +18,7 @@ <listitem> <para>GHC implements a number of GHC-specific extensions to the FFI Addendum. These extensions are described in <xref - linkend="sec-ffi-ghcexts">, but please note that programs using + linkend="sec-ffi-ghcexts"/>, but please note that programs using these features are not portable. Hence, these features should be avoided where possible.</para> </listitem> @@ -56,16 +56,15 @@ use of the foreign function interface in GHC.</para> <sect2 id="foreign-export-ghc"> - <title>Using <literal>foreign export</literal> and <literal>foreign - import ccall "wrapper"</literal> with GHC</title> + <title>Using <literal>foreign export</literal> and <literal>foreign import ccall "wrapper"</literal> with GHC</title> <indexterm><primary><literal>foreign export </literal></primary><secondary>with GHC</secondary> </indexterm> <para>When GHC compiles a module (say <filename>M.hs</filename>) - which uses <literal>foreign export</literal> or <literal>foreign - import "wrapper"</literal>, it generates two + which uses <literal>foreign export</literal> or + <literal>foreign import "wrapper"</literal>, it generates two additional files, <filename>M_stub.c</filename> and <filename>M_stub.h</filename>. GHC will automatically compile <filename>M_stub.c</filename> to generate @@ -136,7 +135,7 @@ int main(int argc, char *argv[]) hs_add_root(__stginit_Foo); #endif - for (i = 0; i < 5; i++) { + for (i = 0; i < 5; i++) { printf("%d\n", foo(2500)); } @@ -204,8 +203,7 @@ int main(int argc, char *argv[]) </sect3> <sect3 id="foreign-export-dynamic-ghc"> - <title>Using <literal>foreign import ccall "wrapper"</literal> with - GHC</title> + <title>Using <literal>foreign import ccall "wrapper"</literal> with GHC</title> <indexterm><primary><literal>foreign import ccall "wrapper"</literal></primary><secondary>with GHC</secondary> @@ -232,7 +230,7 @@ int main(int argc, char *argv[]) <para>When generating C (using the <option>-fvia-C</option> directive), one can assist the C compiler in detecting type errors by using the <option>-#include</option> directive - (<xref linkend="options-C-compiler">) to provide + (<xref linkend="options-C-compiler"/>) to provide <filename>.h</filename> files containing function headers.</para> @@ -269,7 +267,7 @@ from another package, you won't necessarily know what the appropriate <option>-#include</option> options are; but they should be in the package configuration, which GHC knows about. So if you are building a package, remember to put all those <option>-#include</option> options into the package configuration. -See the <literal>c_includes</literal> field in <xref linkend="package-management">. +See the <literal>c_includes</literal> field in <xref linkend="package-management"/>. </para> <para> @@ -298,7 +296,7 @@ to be inlined across modules, use the command-line and package-configuration are searched for using the C compiler's usual search path. You can add directories to this search path using the <option>-I</option> option (see <xref - linkend="c-pre-processor">).</para> + linkend="c-pre-processor"/>).</para> <para>Note: header files are ignored unless compiling via C. If you had been compiling your code using the native code @@ -391,7 +389,7 @@ to be inlined across modules, use the command-line and package-configuration </variablelist> </sect2> </sect1> -</Chapter> +</chapter> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/flags.sgml b/ghc/docs/users_guide/flags.sgml index 769b64126b..09743501ec 100644 --- a/ghc/docs/users_guide/flags.sgml +++ b/ghc/docs/users_guide/flags.sgml @@ -3,14 +3,14 @@ <para>This section is a quick-reference for GHC's command-line flags. For each flag, we also list its static/dynamic status (see - <xref linkend="static-dynamic-flags">), and the flag's opposite + <xref linkend="static-dynamic-flags"/>), and the flag's opposite (if available).</para> <sect2> - <title>Help and verbosity options (<xref linkend="options-help">)</title> + <title>Help and verbosity options (<xref linkend="options-help"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -74,10 +74,10 @@ </sect2> <sect2> - <title>Which phases to run (<xref linkend="options-order">)</title> + <title>Which phases to run (<xref linkend="options-order"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -117,10 +117,10 @@ </sect2> <sect2> - <title>Redirecting output (<xref linkend="options-output">)</title> + <title>Redirecting output (<xref linkend="options-output"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -178,10 +178,10 @@ </sect2> <sect2> - <title>Keeping intermediate files (<xref linkend="keeping-intermediates">)</title> + <title>Keeping intermediate files (<xref linkend="keeping-intermediates"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -221,10 +221,10 @@ </sect2> <sect2> - <title>Temporary files (<xref linkend="temp-files">)</title> + <title>Temporary files (<xref linkend="temp-files"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -246,10 +246,10 @@ </sect2> <sect2> - <title>Finding imports (<xref linkend="search-path">)</title> + <title>Finding imports (<xref linkend="search-path"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -279,10 +279,10 @@ </sect2> <sect2> - <title>Interface file options (<xref linkend="hi-options">)</title> + <title>Interface file options (<xref linkend="hi-options"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -325,10 +325,10 @@ </sect2> <sect2> - <title>Recompilation checking (<xref linkend="recomp">)</title> + <title>Recompilation checking (<xref linkend="recomp"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -351,10 +351,10 @@ </sect2> <sect2> - <title>Interactive-mode options (<xref linkend="ghci-dot-files">)</title> + <title>Interactive-mode options (<xref linkend="ghci-dot-files"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -382,9 +382,9 @@ </sect2> <sect2> - <title>Packages (<xref linkend="packages">)</title> + <title>Packages (<xref linkend="packages"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -418,10 +418,10 @@ </sect2> <sect2> - <title>Language options (<xref linkend="options-language">)</title> + <title>Language options (<xref linkend="options-language"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -516,10 +516,10 @@ </sect2> <sect2> - <title>Warnings (<xref linkend="options-sanity">)</title> + <title>Warnings (<xref linkend="options-sanity"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -556,7 +556,7 @@ <row> <entry><option>-fwarn-deprecations</option></entry> - <entry>warn about uses of functions & types that are deprecated</entry> + <entry>warn about uses of functions & types that are deprecated</entry> <entry>dynamic</entry> <entry><option>-fno-warn-deprecations</option></entry> </row> @@ -666,10 +666,10 @@ </sect2> <sect2> - <title>Optimisation levels (<xref linkend="options-optimise">)</title> + <title>Optimisation levels (<xref linkend="options-optimise"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -697,10 +697,10 @@ </sect2> <sect2> - <title>Individual optimisations (<xref linkend="options-f">)</title> + <title>Individual optimisations (<xref linkend="options-f"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -893,10 +893,10 @@ </sect2> <sect2> - <title>Profiling options (<xref linkend="profiling">)</title> + <title>Profiling options (<xref linkend="profiling"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -950,10 +950,10 @@ </sect2> <sect2> - <title>Parallelism options (<xref linkend="sec-using-parallel">)</title> + <title>Parallelism options (<xref linkend="sec-using-parallel"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -987,10 +987,10 @@ </sect2> <sect2> - <title>C pre-processor options (<xref linkend="c-pre-processor">)</title> + <title>C pre-processor options (<xref linkend="c-pre-processor"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1031,9 +1031,9 @@ </sect2> <sect2> - <title>C compiler options (<xref linkend="options-C-compiler">)</title> + <title>C compiler options (<xref linkend="options-C-compiler"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1056,10 +1056,10 @@ </sect2> <sect2> - <title>Code generation options (<xref linkend="options-codegen">)</title> + <title>Code generation options (<xref linkend="options-codegen"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1093,10 +1093,10 @@ </sect2> <sect2> - <title>Linking options (<xref linkend="options-linker">)</title> + <title>Linking options (<xref linkend="options-linker"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1194,10 +1194,10 @@ </sect2> <sect2> - <title>Replacing phases (<xref linkend="replacing-phases">)</title> + <title>Replacing phases (<xref linkend="replacing-phases"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1271,10 +1271,10 @@ </sect2> <sect2> - <title>Forcing options to particular phases (<xref linkend="forcing-options-through">)</title> + <title>Forcing options to particular phases (<xref linkend="forcing-options-through"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1340,10 +1340,10 @@ </sect2> <sect2> - <title>Platform-specific options (<xref linkend="options-platform">)</title> + <title>Platform-specific options (<xref linkend="options-platform"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1372,10 +1372,10 @@ <sect2> - <title>External core file options (<xref linkend="ext-core">)</title> + <title>External core file options (<xref linkend="ext-core"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1398,10 +1398,10 @@ <sect2> - <title>Compiler debugging options (<xref linkend="options-debugging">)</title> + <title>Compiler debugging options (<xref linkend="options-debugging"/>)</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> @@ -1660,7 +1660,7 @@ <title>Misc compiler options</title> <informaltable> - <tgroup cols=3 align=left colsep=1 rowsep=1> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> <thead> <row> <entry>Flag</entry> diff --git a/ghc/docs/users_guide/ghci.sgml b/ghc/docs/users_guide/ghci.sgml index 792f68b68f..cd82849f60 100644 --- a/ghc/docs/users_guide/ghci.sgml +++ b/ghc/docs/users_guide/ghci.sgml @@ -146,7 +146,7 @@ Ok, modules loaded: Main. indicate that the current context for expressions typed at the prompt is the <literal>Main</literal> module we just loaded (we'll explain what the <literal>*</literal> means later in <xref - linkend="ghci-scope">). So we can now type expressions involving + linkend="ghci-scope"/>). So we can now type expressions involving the functions from <filename>Main.hs</filename>:</para> <screen> @@ -191,13 +191,13 @@ Ok, modules loaded: Main. <para>or it can be set using the <literal>:set</literal> command from within GHCi (see <xref - linkend="ghci-cmd-line-options">)<footnote><para>Note that in + linkend="ghci-cmd-line-options"/>)<footnote><para>Note that in GHCi, and <option>––make</option> mode, the <option>-i</option> option is used to specify the search path for <emphasis>source</emphasis> files, whereas in standard batch-compilation mode the <option>-i</option> option is used to specify the search path for interface files, see <xref - linkend="search-path">.</para> </footnote></para> + linkend="search-path"/>.</para> </footnote></para> <para>One consequence of the way that GHCi follows dependencies to find modules to load is that every module must have a source @@ -220,7 +220,7 @@ Ok, modules loaded: Main. doing its best to avoid actually recompiling modules if their external dependencies haven't changed. This is the same mechanism we use to avoid re-compiling modules in the batch - compilation setting (see <xref linkend="recomp">).</para> + compilation setting (see <xref linkend="recomp"/>).</para> </sect2> </sect1> @@ -247,7 +247,7 @@ Ok, modules loaded: Main. use one in preference to interpreting the source if possible. For example, suppose we have a 4-module program consisting of modules A, B, C, and D. Modules B and C both import D only, - and A imports both B & C:</para> + and A imports both B & C:</para> <screen> A / \ @@ -522,12 +522,12 @@ Prelude,IO> <para>Here's an example:</para> <screen> -Prelude> x <- return 42 +Prelude> x <- return 42 Prelude> print x 42 Prelude> </screen> - <para>The statement <literal>x <- return 42</literal> means + <para>The statement <literal>x <- return 42</literal> means “execute <literal>return 42</literal> in the <literal>IO</literal> monad, and bind the result to <literal>x</literal>”. We can then use @@ -543,7 +543,7 @@ Prelude> print x Prelude> </screen> <para>An important difference between the two types of binding - is that the monadic bind (<literal>p <- e</literal>) is + is that the monadic bind (<literal>p <- e</literal>) is <emphasis>strict</emphasis> (it evaluates <literal>e</literal>), whereas with the <literal>let</literal> form, the expression isn't evaluated immediately:</para> @@ -629,7 +629,7 @@ Wed Mar 14 12:23:13 GMT 2001 <para>The corresponding translation for an IO-typed <replaceable>e</replaceable> is <screen> - it <- <replaceable>e</replaceable> + it <- <replaceable>e</replaceable> </screen> </para> @@ -678,7 +678,7 @@ Wed Mar 14 12:23:13 GMT 2001 instructs GHCi to load the specified modules or filenames (and all the modules they depend on), just as if you had said <literal>:load <replaceable>modules</replaceable></literal> at the - GHCi prompt (see <xref linkend="ghci-commands">). For example, to + GHCi prompt (see <xref linkend="ghci-commands"/>). For example, to start GHCi and load the program whose topmost module is in the file <literal>Main.hs</literal>, we could say:</para> @@ -687,7 +687,7 @@ $ ghci Main.hs </screen> <para>Most of the command-line options accepted by GHC (see <xref - linkend="using-ghc">) also make sense in interactive mode. The ones + linkend="using-ghc"/>) also make sense in interactive mode. The ones that don't make sense are mostly obvious; for example, GHCi doesn't generate interface files, so options related to interface file generation won't have any effect.</para> @@ -696,7 +696,7 @@ $ ghci Main.hs <title>Packages</title> <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm> - <para>Most packages (see <xref linkend="using-packages">) are + <para>Most packages (see <xref linkend="using-packages"/>) are available without needing to specify any extra flags at all: they will be automatically loaded the first time they are needed.</para> @@ -744,7 +744,7 @@ Prelude> :set -package <replaceable>name</replaceable> the normal <literal>-l<replaceable>lib</replaceable></literal> option. (The term <emphasis>library</emphasis> here refers to libraries of foreign object code; for using libraries of Haskell - source code, see <xref linkend="ghci-modules-filenames">.) For + source code, see <xref linkend="ghci-modules-filenames"/>.) For example, to load the “m” library:</para> <screen> @@ -782,7 +782,7 @@ $ ghci -lm <para>Ordering of <option>-l</option> options matters: a library should be mentioned <emphasis>before</emphasis> the libraries it - depends on (see <xref linkend="options-linker">).</para> + depends on (see <xref linkend="options-linker"/>).</para> </sect2> </sect1> @@ -875,7 +875,7 @@ $ ghci -lm <para>That's all a little confusing, so here's a few examples. To start with, here's a new GHCi command which doesn't take any arguments or produce any results, it just - outputs the current date & time:</para> + outputs the current date & time:</para> <screen> Prelude> let date _ = Time.getClockTime >>= print >> return "" @@ -975,7 +975,7 @@ Prelude> :def make (\_ -> return ":! ghc ––make Main") <indexterm><primary><literal>:module</literal></primary></indexterm> <listitem> <para>Sets or modifies the current context for statements - typed at the prompt. See <xref linkend="ghci-scope"> for + typed at the prompt. See <xref linkend="ghci-scope"/> for more details.</para> </listitem> </varlistentry> @@ -1005,7 +1005,7 @@ Prelude> :def make (\_ -> return ":! ghc ––make Main") <term><literal>:set</literal> <optional><replaceable>option</replaceable>...</optional></term> <indexterm><primary><literal>:set</literal></primary></indexterm> <listitem> - <para>Sets various options. See <xref linkend="ghci-set"> + <para>Sets various options. See <xref linkend="ghci-set"/> for a list of available options. The <literal>:set</literal> command by itself shows which options are currently set.</para> @@ -1088,7 +1088,7 @@ Prelude> :def make (\_ -> return ":! ghc ––make Main") <term><literal>:unset</literal> <replaceable>option</replaceable>...</term> <indexterm><primary><literal>:unset</literal></primary></indexterm> <listitem> - <para>Unsets certain options. See <xref linkend="ghci-set"> + <para>Unsets certain options. See <xref linkend="ghci-set"/> for a list of available options.</para> </listitem> </varlistentry> @@ -1192,7 +1192,7 @@ Prelude> :set -fglasgow-exts <para>Any GHC command-line option that is designated as <firstterm>dynamic</firstterm> (see the table in <xref - linkend="flag-reference">), may be set using + linkend="flag-reference"/>), may be set using <literal>:set</literal>. To unset an option, you can set the reverse option:</para> <indexterm><primary>dynamic</primary><secondary>options</secondary></indexterm> @@ -1201,7 +1201,7 @@ Prelude> :set -fglasgow-exts Prelude> :set -fno-glasgow-exts </screen> - <para><xref linkend="flag-reference"> lists the reverse for each + <para><xref linkend="flag-reference"/> lists the reverse for each option where applicable.</para> <para>Certain static options (<option>-package</option>, diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml index 30de1d2742..1c42f5d1c6 100644 --- a/ghc/docs/users_guide/glasgow_exts.sgml +++ b/ghc/docs/users_guide/glasgow_exts.sgml @@ -77,7 +77,7 @@ documentation</ulink> describes all the libraries that come with GHC. <listitem> <para>This simultaneously enables all of the extensions to Haskell 98 described in <xref - linkend="ghc-language-features">, except where otherwise + linkend="ghc-language-features"/>, except where otherwise noted. </para> <para>New reserved words: <literal>forall</literal> (only in @@ -128,7 +128,7 @@ documentation</ulink> describes all the libraries that come with GHC. <indexterm><primary><option>-fallow-undecidable-instances</option></primary></indexterm> <indexterm><primary><option>-fcontext-stack</option></primary></indexterm> <listitem> - <para> See <xref LinkEnd="instance-decls">. Only relevant + <para> See <xref linkend="instance-decls"/>. Only relevant if you also use <option>-fglasgow-exts</option>.</para> </listitem> </varlistentry> @@ -137,7 +137,7 @@ documentation</ulink> describes all the libraries that come with GHC. <term><option>-finline-phase</option></term> <indexterm><primary><option>-finline-phase</option></primary></indexterm> <listitem> - <para>See <xref LinkEnd="rewrite-rules">. Only relevant if + <para>See <xref linkend="rewrite-rules"/>. Only relevant if you also use <option>-fglasgow-exts</option>.</para> </listitem> </varlistentry> @@ -146,7 +146,7 @@ documentation</ulink> describes all the libraries that come with GHC. <term><option>-farrows</option></term> <indexterm><primary><option>-farrows</option></primary></indexterm> <listitem> - <para>See <xref LinkEnd="arrow-notation">. Independent of + <para>See <xref linkend="arrow-notation"/>. Independent of <option>-fglasgow-exts</option>.</para> <para>New reserved words/symbols: <literal>rec</literal>, @@ -163,7 +163,7 @@ documentation</ulink> describes all the libraries that come with GHC. <term><option>-fgenerics</option></term> <indexterm><primary><option>-fgenerics</option></primary></indexterm> <listitem> - <para>See <xref LinkEnd="generic-classes">. Independent of + <para>See <xref linkend="generic-classes"/>. Independent of <option>-fglasgow-exts</option>.</para> </listitem> </varlistentry> @@ -192,7 +192,7 @@ documentation</ulink> describes all the libraries that come with GHC. <para>However, <option>-fno-implicit-prelude</option> does change the handling of certain built-in syntax: see <xref - LinkEnd="rebindable-syntax">.</para> + linkend="rebindable-syntax"/>.</para> </listitem> </varlistentry> @@ -200,7 +200,7 @@ documentation</ulink> describes all the libraries that come with GHC. <term><option>-fth</option></term> <listitem> <para>Enables Template Haskell (see <xref - linkend="template-haskell">). Currently also implied by + linkend="template-haskell"/>). Currently also implied by <option>-fglasgow-exts</option>.</para> <para>Syntax stolen: <literal>[|</literal>, @@ -215,7 +215,7 @@ documentation</ulink> describes all the libraries that come with GHC. <term><option>-fimplicit-params</option></term> <listitem> <para>Enables implicit parameters (see <xref - linkend="implicit-parameters">). Currently also implied by + linkend="implicit-parameters"/>). Currently also implied by <option>-fglasgow-exts</option>.</para> <para>Syntax stolen: @@ -485,7 +485,7 @@ import qualified Control.Monad.ST.Strict as ST <para>For details on how GHC searches for source and interface files in the presence of hierarchical modules, see <xref - linkend="search-path">.</para> + linkend="search-path"/>.</para> <para>GHC comes with a large collection of libraries arranged hierarchically; see the accompanying library documentation. @@ -505,7 +505,7 @@ import qualified Control.Monad.ST.Strict as ST <para> <indexterm><primary>Pattern guards (Glasgow extension)</primary></indexterm> -The discussion that follows is an abbreviated version of Simon Peyton Jones's original <ULink URL="http://research.microsoft.com/~simonpj/Haskell/guards.html">proposal</ULink>. (Note that the proposal was written before pattern guards were implemented, so refers to them as unimplemented.) +The discussion that follows is an abbreviated version of Simon Peyton Jones's original <ulink URL="http://research.microsoft.com/~simonpj/Haskell/guards.html">proposal</ulink>. (Note that the proposal was written before pattern guards were implemented, so refers to them as unimplemented.) </para> <para> @@ -517,11 +517,11 @@ lookup :: FiniteMap -> Int -> Maybe Int </programlisting> The lookup returns <function>Nothing</function> if the supplied key is not in the domain of the mapping, and <function>(Just v)</function> otherwise, -where <VarName>v</VarName> is the value that the key maps to. Now consider the following definition: +where <varname>v</varname> is the value that the key maps to. Now consider the following definition: </para> <programlisting> -clunky env var1 var2 | ok1 && ok2 = val1 + val2 +clunky env var1 var2 | ok1 && ok2 = val1 + val2 | otherwise = var1 + var2 where m1 = lookup env var1 @@ -547,12 +547,12 @@ expectJust Nothing = error "Unexpected Nothing" </programlisting> <para> -What is <function>clunky</function> doing? The guard <literal>ok1 && +What is <function>clunky</function> doing? The guard <literal>ok1 && ok2</literal> checks that both lookups succeed, using <function>maybeToBool</function> to convert the <function>Maybe</function> types to booleans. The (lazily evaluated) <function>expectJust</function> calls extract the values from the results of the lookups, and binds the -returned values to <VarName>val1</VarName> and <VarName>val2</VarName> +returned values to <varname>val1</varname> and <varname>val2</varname> respectively. If either lookup fails, then clunky takes the <literal>otherwise</literal> case and returns the sum of its arguments. </para> @@ -615,9 +615,9 @@ with among the pattern guards. For example: </para> <programlisting> -f x | [y] <- x +f x | [y] <- x , y > 3 - , Just z <- h y + , Just z <- h y = ... </programlisting> @@ -651,7 +651,7 @@ Here is a simple (yet contrived) example: <programlisting> import Control.Monad.Fix -justOnes = mdo xs <- Just (1:xs) +justOnes = mdo xs <- Just (1:xs) return xs </programlisting> <para> @@ -731,7 +731,7 @@ This name is not supported by GHC. example, the following zips together two lists:</para> <programlisting> - [ (x, y) | x <- xs | y <- ys ] + [ (x, y) | x <- xs | y <- ys ] </programlisting> <para>The behavior of parallel list comprehensions follows that of @@ -744,8 +744,8 @@ This name is not supported by GHC. <para>Given a parallel comprehension of the form: </para> <programlisting> - [ e | p1 <- e11, p2 <- e12, ... - | q1 <- e21, q2 <- e22, ... + [ e | p1 <- e11, p2 <- e12, ... + | q1 <- e21, q2 <- e22, ... ... ] </programlisting> @@ -753,8 +753,8 @@ This name is not supported by GHC. <para>This will be translated to: </para> <programlisting> - [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...] - [(q1,q2) | q1 <- e21, q2 <- e22, ...] + [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...] + [(q1,q2) | q1 <- e21, q2 <- e22, ...] ... ] </programlisting> @@ -860,7 +860,7 @@ a data type with no constructors. For example:</para> <para>Syntactically, the declaration lacks the "= constrs" part. The type can be parameterised over types of any kind, but if the kind is not <literal>*</literal> then an explicit kind annotation must be used -(see <xref linkend="sec-kinding">).</para> +(see <xref linkend="sec-kinding"/>).</para> <para>Such data types have only one value, namely bottom. Nevertheless, they can be useful when defining "phantom types".</para> @@ -1020,7 +1020,7 @@ because GHC does not allow unboxed tuples on the left of a function arrow. The idea of using existential quantification in data type declarations was suggested by Laufer (I believe, thought doubtless someone will correct me), and implemented in Hope+. It's been in Lennart -Augustsson's <Command>hbc</Command> Haskell compiler for several years, and +Augustsson's <command>hbc</command> Haskell compiler for several years, and proved very useful. Here's the idea. Consider the declaration: </para> @@ -1131,7 +1131,7 @@ adding a new existential quantification construct. <title>Type classes</title> <para> -An easy extension (implemented in <Command>hbc</Command>) is to allow +An easy extension (implemented in <command>hbc</command>) is to allow arbitrary contexts before the constructor. For example: </para> @@ -1329,7 +1329,7 @@ instance Eq T where (MkT a) == (MkT b) = ??? </programlisting> -But <VarName>a</VarName> and <VarName>b</VarName> have distinct types, and so can't be compared. +But <varname>a</varname> and <varname>b</varname> have distinct types, and so can't be compared. It's just about possible to imagine examples in which the derived instance would make sense, but it seems altogether simpler simply to prohibit such declarations. Define your own instances! @@ -1352,14 +1352,14 @@ declarations. Define your own instances! <para> This section documents GHC's implementation of multi-parameter type -classes. There's lots of background in the paper <ULink +classes. There's lots of background in the paper <ulink URL="http://research.microsoft.com/~simonpj/multi.ps.gz" >Type -classes: exploring the design space</ULink > (Simon Peyton Jones, Mark +classes: exploring the design space</ulink > (Simon Peyton Jones, Mark Jones, Erik Meijer). </para> <para> There are the following constraints on class declarations: -<OrderedList> +<orderedlist> <listitem> <para> @@ -1423,7 +1423,7 @@ be acyclic</emphasis>. So these class declarations are OK: <para> <emphasis>All of the class type variables must be reachable (in the sense -mentioned in <xref linkend="type-restrictions">) +mentioned in <xref linkend="type-restrictions"/>) from the free varibles of each method type </emphasis>. For example: @@ -1468,7 +1468,7 @@ class like this: </para> </listitem> -</OrderedList> +</orderedlist> </para> <sect3 id="class-method-types"> @@ -1519,12 +1519,12 @@ Consider the type: language omits them; in Haskell 98, all the free type variables of an explicit source-language type signature are universally quantified, except for the class type variables in a class declaration. However, -in GHC, you can give the foralls if you want. See <xref LinkEnd="universal-quantification">). +in GHC, you can give the foralls if you want. See <xref linkend="universal-quantification"/>). </para> <para> -<OrderedList> +<orderedlist> <listitem> <para> @@ -1557,7 +1557,7 @@ Note that the reachability condition is weaker than saying that <literal>a</literal> is functionally dependendent on a type variable free in <literal>type</literal> (see <xref -linkend="functional-dependencies">). The reason for this is there +linkend="functional-dependencies"/>). The reason for this is there might be a "hidden" dependency, in a superclass perhaps. So "reachable" is a conservative approximation to "functionally dependent". For example, consider: @@ -1604,7 +1604,7 @@ territory free in case we need it later. </para> </listitem> -</OrderedList> +</orderedlist> </para> </sect3> @@ -1612,7 +1612,7 @@ territory free in case we need it later. <sect3 id="hoist"> <title>For-all hoisting</title> <para> -It is often convenient to use generalised type synonyms (see <xref linkend="type-synonyms">) at the right hand +It is often convenient to use generalised type synonyms (see <xref linkend="type-synonyms"/>) at the right hand end of an arrow, thus: <programlisting> type Discard a = forall b. a -> b -> a @@ -1844,7 +1844,7 @@ instance C Int b => Foo b where ... is not OK. </para> </listitem> -</OrderedList> +</orderedlist> These restrictions ensure that context reduction terminates: each reduction step removes one type constructor. For example, the following would make the type checker @@ -2029,7 +2029,7 @@ For example, we define the <literal>min</literal> function by binding <literal>cmp</literal>. <programlisting> min :: [a] -> a - min = let ?cmp = (<=) in least + min = let ?cmp = (<=) in least </programlisting> </para> <para> @@ -2278,10 +2278,10 @@ to give the kind explicitly as (machine-checked) documentation, just as it is nice to give a type signature for a function. On some occasions, it is essential to do so. For example, in his paper "Restricted Data Types in Haskell" (Haskell Workshop 1999) John Hughes had to define the data type: -<Screen> +<screen> data Set cxt a = Set [a] | Unused (cxt a -> ()) -</Screen> +</screen> The only use for the <literal>Unused</literal> constructor was to force the correct kind for the type variable <literal>cxt</literal>. </para> @@ -2290,21 +2290,21 @@ GHC now instead allows you to specify the kind of a type variable directly, wher a type variable is explicitly bound. Namely: <itemizedlist> <listitem><para><literal>data</literal> declarations: -<Screen> +<screen> data Set (cxt :: * -> *) a = Set [a] -</Screen></para></listitem> +</screen></para></listitem> <listitem><para><literal>type</literal> declarations: -<Screen> +<screen> type T (f :: * -> *) = f Int -</Screen></para></listitem> +</screen></para></listitem> <listitem><para><literal>class</literal> declarations: -<Screen> +<screen> class (Eq a) => C (f :: * -> *) a where ... -</Screen></para></listitem> +</screen></para></listitem> <listitem><para><literal>forall</literal>'s in type signatures: -<Screen> +<screen> f :: forall (cxt :: * -> *). Set cxt Int -</Screen></para></listitem> +</screen></para></listitem> </itemizedlist> </para> @@ -2318,14 +2318,14 @@ single lexeme in Haskell. <para> As part of the same extension, you can put kind annotations in types as well. Thus: -<Screen> +<screen> f :: (Int :: *) -> Int g :: forall a. a -> (a :: *) -</Screen> +</screen> The syntax is -<Screen> +<screen> atype ::= '(' ctype '::' kind ') -</Screen> +</screen> The parentheses are required. </para> </sect2> @@ -2386,12 +2386,12 @@ In particular, a forall-type (also called a "type scheme"), including an operational type class context, is legal: <itemizedlist> <listitem> <para> On the left of a function arrow </para> </listitem> -<listitem> <para> On the right of a function arrow (see <xref linkend="hoist">) </para> </listitem> +<listitem> <para> On the right of a function arrow (see <xref linkend="hoist"/>) </para> </listitem> <listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid field type signatures.</para> </listitem> <listitem> <para> As the type of an implicit parameter </para> </listitem> -<listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables">) </para> </listitem> +<listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables"/>) </para> </listitem> </itemizedlist> There is one place you cannot put a <literal>forall</literal>: you cannot instantiate a type variable with a forall-type. So you cannot @@ -2557,7 +2557,7 @@ that x's type has no foralls in it</emphasis>. <para> What does it mean to "provide" an explicit type for x? You can do that by giving a type signature for x directly, using a pattern type signature -(<xref linkend="scoped-type-variables">), thus: +(<xref linkend="scoped-type-variables"/>), thus: <programlisting> \ f :: (forall a. a->a) -> (f True, f 'c') </programlisting> @@ -2659,23 +2659,23 @@ f (xs::[a]) = ys ++ ys </para> <para> -The pattern <literal>(xs::[a])</literal> includes a type signature for <VarName>xs</VarName>. +The pattern <literal>(xs::[a])</literal> includes a type signature for <varname>xs</varname>. This brings the type variable <literal>a</literal> into scope; it scopes over all the patterns and right hand sides for this equation for <function>f</function>. -In particular, it is in scope at the type signature for <VarName>y</VarName>. +In particular, it is in scope at the type signature for <varname>y</varname>. </para> <para> Pattern type signatures are completely orthogonal to ordinary, separate type signatures. The two can be used independently or together. -At ordinary type signatures, such as that for <VarName>ys</VarName>, any type variables +At ordinary type signatures, such as that for <varname>ys</varname>, any type variables mentioned in the type signature <emphasis>that are not in scope</emphasis> are implicitly universally quantified. (If there are no type variables in scope, all type variables mentioned in the signature are universally -quantified, which is just as in Haskell 98.) In this case, since <VarName>a</VarName> -is in scope, it is not universally quantified, so the type of <VarName>ys</VarName> is -the same as that of <VarName>xs</VarName>. In Haskell 98 it is not possible to declare -a type for <VarName>ys</VarName>; a major benefit of scoped type variables is that +quantified, which is just as in Haskell 98.) In this case, since <varname>a</varname> +is in scope, it is not universally quantified, so the type of <varname>ys</varname> is +the same as that of <varname>xs</varname>. In Haskell 98 it is not possible to declare +a type for <varname>ys</varname>; a major benefit of scoped type variables is that it becomes possible to do so. </para> @@ -2762,9 +2762,9 @@ The type variable(s) bound by the pattern have the same scope as the term variable(s) bound by the pattern. For example: <programlisting> let - f (x::a) = <...rhs of f...> + f (x::a) = <...rhs of f...> (p::b, q::b) = (1,2) - in <...body of let...> + in <...body of let...> </programlisting> Here, the type variable <literal>a</literal> scopes over the right hand side of <literal>f</literal>, just like <literal>x</literal> does; while the type variable <literal>b</literal> scopes over the @@ -2804,7 +2804,7 @@ into scope (except in the type signature itself!). So this is illegal: f x = x::a </programlisting> -It's illegal because <VarName>a</VarName> is not in scope in the body of <function>f</function>, +It's illegal because <varname>a</varname> is not in scope in the body of <function>f</function>, so the ordinary signature <literal>x::a</literal> is equivalent to <literal>x::forall a.a</literal>; and that is an incorrect typing. @@ -3607,7 +3607,7 @@ arr (\ x -> (x, x)) >>> returnA </screen> Note that variables not used later in the composition are projected out. -After simplification using rewrite rules (see <xref linkEnd="rewrite-rules">) +After simplification using rewrite rules (see <xref linkend="rewrite-rules"/>) defined in the <ulink url="../base/Control.Arrow.html"><literal>Control.Arrow</literal></ulink> module, this reduces to @@ -3847,7 +3847,7 @@ though the results would be somewhat clumsy. For example, we could simulate <literal>do</literal>-notation by defining <programlisting> bind :: Arrow a => a e b -> a (e,b) c -> a e c -u `bind` f = returnA &&& u >>> f +u `bind` f = returnA &&& u >>> f bind_ :: Arrow a => a e b -> a e c -> a e c u `bind_` f = u `bind` (arr fst >>> f) @@ -4142,7 +4142,7 @@ key_function :: Int -> String -> (Bool, Double) </programlisting> <para>See also the <literal>NOINLINE</literal> pragma (<xref - linkend="noinline-pragma">).</para> + linkend="noinline-pragma"/>).</para> </sect3> <sect3 id="noinline-pragma"> @@ -4231,7 +4231,7 @@ key_function :: Int -> String -> (Bool, Double) </itemizedlist> <para>The same phase-numbering control is available for RULES - (<xref LinkEnd="rewrite-rules">).</para> + (<xref linkend="rewrite-rules"/>).</para> </sect3> </sect2> @@ -4265,7 +4265,7 @@ key_function :: Int -> String -> (Bool, Double) <para>The <literal>OPTIONS</literal> pragma is used to specify additional options that are given to the compiler when compiling - this source file. See <xref linkend="source-file-options"> for + this source file. See <xref linkend="source-file-options"/> for details.</para> </sect2> @@ -4273,7 +4273,7 @@ key_function :: Int -> String -> (Bool, Double) <title>RULES pragma</title> <para>The RULES pragma lets you specify rewrite rules. It is - described in <xref LinkEnd="rewrite-rules">.</para> + described in <xref linkend="rewrite-rules"/>.</para> </sect2> <sect2 id="specialize-pragma"> @@ -4305,7 +4305,7 @@ hammeredLookup :: Ord key => [(key, value)] -> key -> value <para>A <literal>SPECIALIZE</literal> has the effect of generating (a) a specialised version of the function and (b) a rewrite rule - (see <xref linkend="rewrite-rules">) that rewrites a call to the + (see <xref linkend="rewrite-rules"/>) that rewrites a call to the un-specialised function into a call to the specialised one.</para> <para>In earlier versions of GHC, it was possible to provide your own @@ -4316,7 +4316,7 @@ hammeredLookup :: Ord key => [(key, value)] -> key -> value </programlisting> This feature has been removed, as it is now subsumed by the - <literal>RULES</literal> pragma (see <xref linkend="rule-spec">).</para> + <literal>RULES</literal> pragma (see <xref linkend="rule-spec"/>).</para> </sect2> @@ -4355,14 +4355,14 @@ of the pragma. the constructor itself, removing a level of indirection. For example:</para> -<ProgramListing> +<programlisting> data T = T {-# UNPACK #-} !Float {-# UNPACK #-} !Float -</ProgramListing> +</programlisting> <para>will create a constructor <literal>T</literal> containing two unboxed floats. This may not always be an optimisation: if - the <Function>T</Function> constructor is scrutinised and the + the <function>T</function> constructor is scrutinised and the floats passed to a non-strict function for example, they will have to be reboxed (this is done automatically by the compiler).</para> @@ -4372,33 +4372,33 @@ data T = T {-# UNPACK #-} !Float unfoldings to the compiler so the reboxing can be removed as often as possible. For example:</para> -<ProgramListing> +<programlisting> f :: T -> Float f (T f1 f2) = f1 + f2 -</ProgramListing> +</programlisting> - <para>The compiler will avoid reboxing <Function>f1</Function> - and <Function>f2</Function> by inlining <Function>+</Function> + <para>The compiler will avoid reboxing <function>f1</function> + and <function>f2</function> by inlining <function>+</function> on floats, but only when <option>-O</option> is on.</para> <para>Any single-constructor data is eligible for unpacking; for example</para> -<ProgramListing> +<programlisting> data T = T {-# UNPACK #-} !(Int,Int) -</ProgramListing> +</programlisting> <para>will store the two <literal>Int</literal>s directly in the - <Function>T</Function> constructor, by flattening the pair. + <function>T</function> constructor, by flattening the pair. Multi-level unpacking is also supported:</para> -<ProgramListing> +<programlisting> data T = T {-# UNPACK #-} !S data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int -</ProgramListing> +</programlisting> <para>will store two unboxed <literal>Int#</literal>s - directly in the <Function>T</Function> constructor. The + directly in the <function>T</function> constructor. The unpacker can see through newtypes, too.</para> <para>If a field cannot be unpacked, you will not get a warning, @@ -4425,9 +4425,9 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int <para> The programmer can specify rewrite rules as part of the source program (in a pragma). GHC applies these rewrite rules wherever it can, provided (a) -the <option>-O</option> flag (<xref LinkEnd="options-optimise">) is on, +the <option>-O</option> flag (<xref linkend="options-optimise"/>) is on, and (b) the <option>-frules-off</option> flag -(<xref LinkEnd="options-f">) is not specified. +(<xref linkend="options-f"/>) is not specified. </para> <para> @@ -4465,7 +4465,7 @@ no significance at all. It is only used when reporting how many times the rule <listitem> <para> -A rule may optionally have a phase-control number (see <xref LinkEnd="phase-control">), +A rule may optionally have a phase-control number (see <xref linkend="phase-control"/>), immediately after the name of the rule. Thus: <programlisting> {-# RULES @@ -4623,7 +4623,7 @@ But not beta conversion (that's called higher-order matching). <para> Matching is carried out on GHC's intermediate language, which includes type abstractions and applications. So a rule only matches if the -types match too. See <xref LinkEnd="rule-spec"> below. +types match too. See <xref linkend="rule-spec"/> below. </para> </listitem> <listitem> @@ -4640,8 +4640,8 @@ For example, consider: </programlisting> The expression <literal>s (t xs)</literal> does not match the rule <literal>"map/map"</literal>, but GHC -will substitute for <VarName>s</VarName> and <VarName>t</VarName>, giving an expression which does match. -If <VarName>s</VarName> or <VarName>t</VarName> was (a) used more than once, and (b) large or a redex, then it would +will substitute for <varname>s</varname> and <varname>t</varname>, giving an expression which does match. +If <varname>s</varname> or <varname>t</varname> was (a) used more than once, and (b) large or a redex, then it would not be substituted, and the rule would not fire. </para> @@ -4982,7 +4982,7 @@ If you add <option>-dppr-debug</option> you get a more detailed listing. <listitem> <para> - The defintion of (say) <function>build</function> in <FileName>GHC/Base.lhs</FileName> looks llike this: + The defintion of (say) <function>build</function> in <filename>GHC/Base.lhs</filename> looks llike this: <programlisting> build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a] @@ -5041,7 +5041,7 @@ g x = show x <para> However, when external for is generated (via <option>-fext-core</option>), there will be Notes attached to the - expressions <function>show</function> and <VarName>x</VarName>. + expressions <function>show</function> and <varname>x</varname>. The core function declaration for <function>f</function> is: </para> @@ -5069,8 +5069,8 @@ r) -> Here, we can see that the function <function>show</function> (which has been expanded out to a case expression over the Show dictionary) has a <literal>%note</literal> attached to it, as does the - expression <VarName>eta</VarName> (which used to be called - <VarName>x</VarName>). + expression <varname>eta</varname> (which used to be called + <varname>x</varname>). </para> </sect2> diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml index 2f0321cd8f..d4fc7f9ae8 100644 --- a/ghc/docs/users_guide/gone_wrong.sgml +++ b/ghc/docs/users_guide/gone_wrong.sgml @@ -1,30 +1,30 @@ <chapter id="wrong"> <title>What to do when something goes wrong</title> - <Indexterm><Primary>problems</Primary></Indexterm> + <indexterm><primary>problems</primary></indexterm> <para>If you still have a problem after consulting this section, - then you may have found a <Emphasis>bug</Emphasis>—please - report it! See <XRef LinkEnd="bug-reporting"> for details on how to + then you may have found a <emphasis>bug</emphasis>—please + report it! See <xref linkend="bug-reporting"/> for details on how to report a bug and a list of things we'd like to know about your bug. If in doubt, send a report—we love mail from irate users :-!</para> - <para>(<XRef LinkEnd="vs-Haskell-defn">, which describes Glasgow + <para>(<xref linkend="vs-Haskell-defn"/>, which describes Glasgow Haskell's shortcomings vs. the Haskell language definition, may also be of interest.)</para> <sect1 id="wrong-compiler"> <title>When the compiler “does the wrong thing”</title> - <Indexterm><Primary>compiler problems</Primary></Indexterm> - <Indexterm><Primary>problems with the compiler</Primary></Indexterm> + <indexterm><primary>compiler problems</primary></indexterm> + <indexterm><primary>problems with the compiler</primary></indexterm> <variablelist> <varlistentry> <term>“Help! The compiler crashed (or `panic'd)!”</term> <listitem> - <para>These events are <Emphasis>always</Emphasis> bugs in + <para>These events are <emphasis>always</emphasis> bugs in the GHC system—please report them.</para> </listitem> </varlistentry> @@ -48,7 +48,7 @@ </varlistentry> <varlistentry> - <term>Sensitivity to <Filename>.hi</Filename> interface files:</term> + <term>Sensitivity to <filename>.hi</filename> interface files:</term> <listitem> <para>GHC is very sensitive about interface files. For example, if it picks up a non-standard @@ -107,11 +107,11 @@ <sect1 id="wrong-compilee"> <title>When your program “does the wrong thing”</title> - <Indexterm><Primary>problems running your program</Primary></Indexterm> + <indexterm><primary>problems running your program</primary></indexterm> <para>(For advice about overly slow or memory-hungry Haskell - programs, please see <XRef - LinkEnd="sooner-faster-quicker">).</para> + programs, please see <xref + linkend="sooner-faster-quicker"/>).</para> <variablelist> @@ -134,8 +134,8 @@ <para>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. <Emphasis>This applies to pragmas - inside interfaces too!</Emphasis> If the pragma is lying + for the importing module. <emphasis>This applies to pragmas + inside interfaces too!</emphasis> If the pragma is lying (e.g., about the “arity” of a value), then duff code may result. Furthermore, arities may change even if types do not.</para> @@ -154,7 +154,7 @@ automatically generate the dependencies required in order to make sure that every module <emphasis>is</emphasis> up-to-date with respect to its imported interfaces. Please - see <xref linkend="sec-makefile-dependencies">.</para> + see <xref linkend="sec-makefile-dependencies"/>.</para> <para>If you are down to your last-compile-before-a-bug-report, we would recommend that @@ -164,12 +164,12 @@ <para>So, before you report a bug because of a core dump, you should probably:</para> -<Screen> +<screen> % rm *.o # scrub your object files % make my_prog # re-make your program; use -hi-diffs to highlight changes; # as mentioned above, use -dcore-lint to be more paranoid % ./my_prog ... # retry... -</Screen> +</screen> <para>Of course, if you have foreign calls in your program then all bets are off, because you can trash the heap, the @@ -181,7 +181,7 @@ <term>“My program entered an `absent' argument.”</term> <listitem> <para>This is definitely caused by a bug in GHC. Please - report it (see <xref linkend="bug-reporting">).</para> + report it (see <xref linkend="bug-reporting"/>).</para> </listitem> </varlistentry> diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml index f96494ef04..2abdca9732 100644 --- a/ghc/docs/users_guide/installing.sgml +++ b/ghc/docs/users_guide/installing.sgml @@ -1,40 +1,40 @@ -<Chapter id="sec-installing-bin-distrib"> - <Title>Installing GHC</Title> -<IndexTerm><Primary>binary installations</Primary></IndexTerm> -<IndexTerm><Primary>installation, of binaries</Primary></IndexTerm> +<chapter id="sec-installing-bin-distrib"> + <title>Installing GHC</title> +<indexterm><primary>binary installations</primary></indexterm> +<indexterm><primary>installation, of binaries</primary></indexterm> -<Para> +<para> 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 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 proceed. For the -other <Literal>fptools</Literal> programs, many are written in +other <literal>fptools</literal> programs, many are written in Haskell, so binary distributions allow you to install them without having a Haskell compiler.) -</Para> +</para> -<Para>This guide is in several parts:</para> +<para>This guide is in several parts:</para> <itemizedlist> <listitem> - <para> Installing on Unix-a-likes (<Xref - LinkEnd="sec-unix-a-likes">). </para> + <para> Installing on Unix-a-likes (<xref + linkend="sec-unix-a-likes"/>). </para> </listitem> <listitem> - <para> Installing on Windows (<Xref - LinkEnd="sec-install-windows">). </para> + <para> Installing on Windows (<xref + linkend="sec-install-windows"/>). </para> </listitem> <listitem> - <para> The layout of installed files (<Xref - LinkEnd="sec-install-files">). You don't need to know this to + <para> The layout of installed files (<xref + linkend="sec-install-files"/>). You don't need to know this to install GHC, but it's useful if you are changing the implementation.</para> </listitem> </itemizedlist> - <Sect1 id="sec-unix-a-likes"><Title>Installing on Unix-a-likes</Title> + <sect1 id="sec-unix-a-likes"><title>Installing on Unix-a-likes</title> <sect2> <title>When a platform-specific package is available</title> @@ -53,7 +53,7 @@ having a Haskell compiler.) <varlistentry> <term>RedHat or SuSE Linux/x86</term> <listitem> - <para>RPM source & binary packages for RedHat and SuSE + <para>RPM source & binary packages for RedHat and SuSE Linux (x86 only) are available for most major releases.</para> </listitem> @@ -71,7 +71,7 @@ having a Haskell compiler.) <term>FreeBSD/x86</term> <listitem> <para>On FreeBSD/x86, GHC can be installed using either - the ports tree (<literal>cd /usr/ports/lang/ghc && make + the ports tree (<literal>cd /usr/ports/lang/ghc && make install</literal>) or from a pre-compiled package available from your local FreeBSD mirror.</para> </listitem> @@ -82,386 +82,386 @@ having a Haskell compiler.) the GHC download page for details.</para> </sect2> -<Sect2> -<Title>GHC binary distributions</Title> +<sect2> +<title>GHC binary distributions</title> -<Para> -<IndexTerm><Primary>bundles of binary stuff</Primary></IndexTerm> -</Para> +<para> +<indexterm><primary>bundles of binary stuff</primary></indexterm> +</para> -<Para> +<para> Binary distributions come in “bundles,” one bundle per file called -<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus: -</Para> +<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</literal>. (See the building guide for the definition of a platform.) Suppose that you untar a binary-distribution bundle, thus: +</para> -<Para> +<para> -<Screen> +<screen> % cd /your/scratch/space -% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -</Screen> +% gunzip < ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -</screen> -</Para> +</para> -<Para> +<para> Then you should find a single directory, -<Literal>ghc-<replaceable>version</replaceable></Literal>, with the +<literal>ghc-<replaceable>version</replaceable></literal>, with the following structure: -</Para> - -<Para> -<IndexTerm><Primary>binary distribution, layout</Primary></IndexTerm> -<IndexTerm><Primary>directory layout (binary distributions)</Primary></IndexTerm> -<VariableList> - -<VarListEntry> -<Term><Literal>Makefile.in</Literal></Term> -<ListItem> -<Para> -the raw material from which the <Literal>Makefile</Literal> -will be made (<Xref LinkEnd="sec-install">). -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>configure</Literal></Term> -<ListItem> -<Para> -the configuration script (<Xref LinkEnd="sec-install">). -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>README</Literal></Term> -<ListItem> -<Para> +</para> + +<para> +<indexterm><primary>binary distribution, layout</primary></indexterm> +<indexterm><primary>directory layout (binary distributions)</primary></indexterm> +<variablelist> + +<varlistentry> +<term><literal>Makefile.in</literal></term> +<listitem> +<para> +the raw material from which the <literal>Makefile</literal> +will be made (<xref linkend="sec-install"/>). +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>configure</literal></term> +<listitem> +<para> +the configuration script (<xref linkend="sec-install"/>). +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>README</literal></term> +<listitem> +<para> Contains this file summary. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>INSTALL</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>INSTALL</literal></term> +<listitem> +<para> Contains this description of how to install the bundle. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>ANNOUNCE</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>ANNOUNCE</literal></term> +<listitem> +<para> The announcement message for the bundle. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>NEWS</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>NEWS</literal></term> +<listitem> +<para> release notes for the bundle—a longer version -of <Literal>ANNOUNCE</Literal>. For GHC, the release notes are contained in the User +of <literal>ANNOUNCE</literal>. For GHC, the release notes are contained in the User Guide and this file isn't present. -</Para> -</ListItem></VarListEntry> -<VarListEntry> - <Term><Literal>bin/<replaceable>platform</replaceable></Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> + <term><literal>bin/<replaceable>platform</replaceable></literal></term> +<listitem> +<para> contains platform-specific executable files to be invoked directly by the user. These are the files that must end up in your path. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>lib/<replaceable>platform</replaceable>/</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>lib/<replaceable>platform</replaceable>/</literal></term> +<listitem> +<para> contains platform-specific support files for the installation. Typically there is a subdirectory for -each <Literal>fptools</Literal> project, whose name is the name of the project with its +each <literal>fptools</literal> project, whose name is the name of the project with its version number. For example, for GHC there would be a sub-directory -<Literal>ghc-x.xx</Literal>/ where <Literal>x.xx</Literal> is the version number of GHC in the bundle. -</Para> +<literal>ghc-x.xx</literal>/ where <literal>x.xx</literal> is the version number of GHC in the bundle. +</para> -<Para> +<para> These sub-directories have the following general structure: -</Para> +</para> -<Para> -<VariableList> +<para> +<variablelist> -<VarListEntry> -<Term><Literal>libHSstd.a</Literal> etc:</Term> -<ListItem> -<Para> +<varlistentry> +<term><literal>libHSstd.a</literal> etc:</term> +<listitem> +<para> supporting library archives. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>ghc-iface.prl</Literal> etc:</Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>ghc-iface.prl</literal> etc:</term> +<listitem> +<para> support scripts. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>import/</Literal></Term> -<ListItem> -<Para> -<IndexTerm><Primary>Interface files</Primary></IndexTerm> (<Literal>.hi</Literal>) for the prelude. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>include/</Literal></Term> -<ListItem> -<Para> -A few C <Literal>#include</Literal> files. -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>share/</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>import/</literal></term> +<listitem> +<para> +<indexterm><primary>Interface files</primary></indexterm> (<literal>.hi</literal>) for the prelude. +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>include/</literal></term> +<listitem> +<para> +A few C <literal>#include</literal> files. +</para> +</listitem></varlistentry> +</variablelist> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>share/</literal></term> +<listitem> +<para> contains platform-independent support files for the installation. Again, there is a sub-directory for each -<Literal>fptools</Literal> project. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>html/</Literal></Term> -<ListItem> -<Para> +<literal>fptools</literal> project. +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>html/</literal></term> +<listitem> +<para> contains HTML documentation files (one sub-directory per project). -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> +</para> +</listitem></varlistentry> +</variablelist> +</para> -<Sect3 id="sec-install"> -<Title>Installing</Title> +<sect3 id="sec-install"> +<title>Installing</title> -<Para> +<para> OK, so let's assume that you have unpacked your chosen bundles. What next? Well, you will at least need to run the -<Literal>configure</Literal><IndexTerm><Primary>configure</Primary></IndexTerm> +<literal>configure</literal><indexterm><primary>configure</primary></indexterm> script by changing directory into the top-level directory for the -bundle and typing <Literal>./configure</Literal>. That should convert -<Literal>Makefile.in</Literal> to <Literal>Makefile</Literal>. -</Para> - -<Para> -<IndexTerm><Primary>installing in-place</Primary></IndexTerm> -<IndexTerm><Primary>in-place installation</Primary></IndexTerm> -You can now either start using the tools <Emphasis>in-situ</Emphasis> without going -through any installation process, just type <Literal>make in-place</Literal> to set the -tools up for this. You'll also want to add the path which <Literal>make</Literal> will -now echo to your <Literal>PATH</Literal> environment variable. This option is useful if +bundle and typing <literal>./configure</literal>. That should convert +<literal>Makefile.in</literal> to <literal>Makefile</literal>. +</para> + +<para> +<indexterm><primary>installing in-place</primary></indexterm> +<indexterm><primary>in-place installation</primary></indexterm> +You can now either start using the tools <emphasis>in-situ</emphasis> without going +through any installation process, just type <literal>make in-place</literal> to set the +tools up for this. You'll also want to add the path which <literal>make</literal> will +now echo to your <literal>PATH</literal> environment variable. This option is useful if you simply want to try out the package and/or you don't have the necessary privileges (or inclination) to properly install the tools locally. Note that if you do decide to install the package `properly' at a later date, you have to go through the installation steps that follow. -</Para> +</para> -<Para> +<para> To install a package, you'll have to do the following: -</Para> +</para> -<Para> +<para> -<OrderedList> -<ListItem> +<orderedlist> +<listitem> -<Para> - Edit the <Literal>Makefile</Literal> and check the settings of the following variables: +<para> + Edit the <literal>Makefile</literal> and check the settings of the following variables: -<IndexTerm><Primary>directories, installation</Primary></IndexTerm> -<IndexTerm><Primary>installation directories</Primary></IndexTerm> +<indexterm><primary>directories, installation</primary></indexterm> +<indexterm><primary>installation directories</primary></indexterm> -<VariableList> +<variablelist> -<VarListEntry> -<Term><Literal>platform</Literal></Term> -<ListItem> -<Para> +<varlistentry> +<term><literal>platform</literal></term> +<listitem> +<para> the platform you are going to install for. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>bindir</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>bindir</literal></term> +<listitem> +<para> the directory in which to install user-invokable binaries. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>libdir</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>libdir</literal></term> +<listitem> +<para> the directory in which to install platform-dependent support files. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>datadir</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>datadir</literal></term> +<listitem> +<para> the directory in which to install platform-independent support files. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>infodir</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>infodir</literal></term> +<listitem> +<para> the directory in which to install Emacs info files. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>htmldir</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>htmldir</literal></term> +<listitem> +<para> the directory in which to install HTML documentation. -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>dvidir</Literal></Term> -<ListItem> -<Para> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>dvidir</literal></term> +<listitem> +<para> the directory in which to install DVI documentation. -</Para> -</ListItem></VarListEntry> -</VariableList> +</para> +</listitem></varlistentry> +</variablelist> The values for these variables can be set through invocation of the -<Command>configure</Command><IndexTerm><Primary>configure</Primary></IndexTerm> +<command>configure</command><indexterm><primary>configure</primary></indexterm> script that comes with the distribution, but doing an optical diff to see if the values match your expectations is always a Good Idea. </para> <para> -<Emphasis>Instead of running <Command>configure</Command>, it is -perfectly OK to copy <Filename>Makefile.in</Filename> to -<Filename>Makefile</Filename> and set all these variables directly -yourself. But do it right!</Emphasis> -</Para> +<emphasis>Instead of running <command>configure</command>, it is +perfectly OK to copy <filename>Makefile.in</filename> to +<filename>Makefile</filename> and set all these variables directly +yourself. But do it right!</emphasis> +</para> -</ListItem> -<ListItem> +</listitem> +<listitem> -<Para> -Run <Literal>make install</Literal>. This <Emphasis> -should</Emphasis> work with ordinary Unix -<Literal>make</Literal>—no need for fancy stuff like GNU -<Literal>make</Literal>. +<para> +Run <literal>make install</literal>. This <emphasis> +should</emphasis> work with ordinary Unix +<literal>make</literal>—no need for fancy stuff like GNU +<literal>make</literal>. -</Para> -</ListItem> -<ListItem> +</para> +</listitem> +<listitem> -<Para> -<Literal>rehash</Literal> (t?csh or zsh users), so your shell will see the new +<para> +<literal>rehash</literal> (t?csh or zsh users), so your shell will see the new stuff in your bin directory. -</Para> -</ListItem> -<ListItem> +</para> +</listitem> +<listitem> -<Para> +<para> Once done, test your “installation” as suggested in -<XRef LinkEnd="sec-GHC-test">. Be sure to use a <Literal>-v</Literal> +<xref linkend="sec-GHC-test"/>. Be sure to use a <literal>-v</literal> option, so you can see exactly what pathnames it's using. If things don't work as expected, check the list of known pitfalls in the building guide. -</Para> -</ListItem> +</para> +</listitem> -</OrderedList> +</orderedlist> -</Para> +</para> -<Para> -<IndexTerm><Primary>link, installed as ghc</Primary></IndexTerm> +<para> +<indexterm><primary>link, installed as ghc</primary></indexterm> When installing the user-invokable binaries, this installation -procedure will install GHC as <Literal>ghc-x.xx</Literal> where <Literal>x.xx</Literal> is the version +procedure will install GHC as <literal>ghc-x.xx</literal> where <literal>x.xx</literal> is the version number of GHC. It will also make a link (in the binary installation -directory) from <Literal>ghc</Literal> to <Literal>ghc-x.xx</Literal>. If you install multiple versions -of GHC then the last one “wins”, and “<Literal>ghc</Literal>” will invoke the last +directory) from <literal>ghc</literal> to <literal>ghc-x.xx</literal>. If you install multiple versions +of GHC then the last one “wins”, and “<literal>ghc</literal>” will invoke the last one installed. You can change this manually if you want. But -regardless, <Literal>ghc-x.xx</Literal> should always invoke GHC version <Literal>x.xx</Literal>. -</Para> +regardless, <literal>ghc-x.xx</literal> should always invoke GHC version <literal>x.xx</literal>. +</para> -</Sect3> +</sect3> -<Sect3> -<Title>What bundles there are</Title> +<sect3> +<title>What bundles there are</title> -<Para> -<IndexTerm><Primary>bundles, binary</Primary></IndexTerm> There are +<para> +<indexterm><primary>bundles, binary</primary></indexterm> There are plenty of “non-basic” GHC bundles. The files for them are called -<Literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>, +<literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</literal>, where the <replaceable>platform</replaceable> is as above, and <replaceable>bundle</replaceable> is one of these: -</Para> +</para> -<Para> -<VariableList> +<para> +<variablelist> -<VarListEntry> -<Term><Literal>prof</Literal>:</Term> -<ListItem> -<Para> +<varlistentry> +<term><literal>prof</literal>:</term> +<listitem> +<para> Profiling with cost-centres. You probably want this. -<IndexTerm><Primary>profiling bundles</Primary></IndexTerm> -<IndexTerm><Primary>bundles, profiling</Primary></IndexTerm> -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>par</Literal>:</Term> -<ListItem> -<Para> +<indexterm><primary>profiling bundles</primary></indexterm> +<indexterm><primary>bundles, profiling</primary></indexterm> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>par</literal>:</term> +<listitem> +<para> Parallel Haskell features (sits on top of PVM). You'll want this if you're into that kind of thing. -<IndexTerm><Primary>parallel bundles</Primary></IndexTerm> -<IndexTerm><Primary>bundles, parallel</Primary></IndexTerm> -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>gran</Literal>:</Term> -<ListItem> -<Para> +<indexterm><primary>parallel bundles</primary></indexterm> +<indexterm><primary>bundles, parallel</primary></indexterm> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>gran</literal>:</term> +<listitem> +<para> The “GranSim” parallel-Haskell simulator (hmm… mainly for implementors). -<IndexTerm><Primary>bundles, gransim</Primary></IndexTerm> -<IndexTerm><Primary>gransim bundles</Primary></IndexTerm> -</Para> -</ListItem></VarListEntry> -<VarListEntry> -<Term><Literal>ticky</Literal>:</Term> -<ListItem> -<Para> +<indexterm><primary>bundles, gransim</primary></indexterm> +<indexterm><primary>gransim bundles</primary></indexterm> +</para> +</listitem></varlistentry> +<varlistentry> +<term><literal>ticky</literal>:</term> +<listitem> +<para> “Ticky-ticky” profiling; very detailed information about “what happened when I ran this program”—really for implementors. -<IndexTerm><Primary>bundles, ticky-ticky</Primary></IndexTerm> -<IndexTerm><Primary>ticky-ticky bundles</Primary></IndexTerm> -</Para> -</ListItem></VarListEntry> -</VariableList> -</Para> - -<Para> -One likely scenario is that you will grab <Emphasis>two</Emphasis> +<indexterm><primary>bundles, ticky-ticky</primary></indexterm> +<indexterm><primary>ticky-ticky bundles</primary></indexterm> +</para> +</listitem></varlistentry> +</variablelist> +</para> + +<para> +One likely scenario is that you will grab <emphasis>two</emphasis> binary bundles—basic, and profiling. We don't usually make the rest, although you can build them yourself from a source distribution. -</Para> +</para> <para>The various GHC bundles are designed to be unpacked into the same directory; then installing as per the directions above will @@ -469,85 +469,85 @@ install the whole lot in one go. Note: you <emphasis>must</emphasis> at least have the basic GHC binary distribution bundle, these extra bundles won't install on their own.</para> -</Sect3> +</sect3> -<Sect3 id="sec-GHC-test"> -<Title>Testing that GHC seems to be working -</Title> +<sect3 id="sec-GHC-test"> +<title>Testing that GHC seems to be working +</title> -<Para> -<IndexTerm><Primary>testing a new GHC</Primary></IndexTerm> -</Para> +<para> +<indexterm><primary>testing a new GHC</primary></indexterm> +</para> -<Para> -The way to do this is, of course, to compile and run <Emphasis>this</Emphasis> program -(in a file <Literal>Main.hs</Literal>): -</Para> +<para> +The way to do this is, of course, to compile and run <emphasis>this</emphasis> program +(in a file <literal>Main.hs</literal>): +</para> -<Para> +<para> -<ProgramListing> +<programlisting> main = putStr "Hello, world!\n" -</ProgramListing> +</programlisting> -</Para> +</para> -<Para> -Compile the program, using the <Literal>-v</Literal> (verbose) flag to verify that +<para> +Compile the program, using the <literal>-v</literal> (verbose) flag to verify that libraries, etc., are being found properly: -<Screen> -% ghc -v -o hello Main.hs</Screen> +<screen> +% ghc -v -o hello Main.hs</screen> -</Para> +</para> -<Para> +<para> Now run it: -<Screen> +<screen> % ./hello -Hello, world!</Screen> +Hello, world!</screen> -</Para> +</para> -<Para> +<para> Some simple-but-profitable tests are to compile and run the notorious -<Literal>nfib</Literal><IndexTerm><Primary>nfib</Primary></IndexTerm> program, using different numeric types. Start with -<Literal>nfib :: Int -> Int</Literal>, and then try <Literal>Integer</Literal>, <Literal>Float</Literal>, <Literal>Double</Literal>, -<Literal>Rational</Literal> and perhaps the overloaded version. Code for this is -distributed in <Literal>ghc/misc/examples/nfib/</Literal> in a source distribution. -</Para> +<literal>nfib</literal><indexterm><primary>nfib</primary></indexterm> program, using different numeric types. Start with +<literal>nfib :: Int -> Int</literal>, and then try <literal>Integer</literal>, <literal>Float</literal>, <literal>Double</literal>, +<literal>Rational</literal> and perhaps the overloaded version. Code for this is +distributed in <literal>ghc/misc/examples/nfib/</literal> in a source distribution. +</para> <para>For more information on how to “drive” GHC, read on...</para> -</Sect3> +</sect3> -</Sect2> +</sect2> -</Sect1> +</sect1> -<Sect1 id="sec-install-windows"><Title>Installing on Windows</Title> +<sect1 id="sec-install-windows"><title>Installing on Windows</title> <para> Getting the Glasgow Haskell Compiler (post 5.02) to run on Windows platforms is a snap: the Installshield does everything you need. </para> -<Sect2><Title>Installing GHC on Windows</Title> +<sect2><title>Installing GHC on Windows</title> <para> To install GHC, use the following steps: </para> <itemizedlist> -<listitem><para>Download the Installshield <Filename>setup.exe</Filename> +<listitem><para>Download the Installshield <filename>setup.exe</filename> from the GHC download page -<ULink -URL="http://www.haskell.org/ghc">haskell.org</ULink>. +<ulink +URL="http://www.haskell.org/ghc">haskell.org</ulink>. </para></listitem> -<listitem><para>Run <Filename>setup.exe</Filename>. +<listitem><para>Run <filename>setup.exe</filename>. On Windows, all of GHC's files are installed in a single directory. If you choose ``Custom'' from the list of install options, you will be given a choice about where this directory is; otherwise it will be installed @@ -556,7 +556,7 @@ The executable binary for GHC will be installed in the <filename>bin/</filename> of the installation directory you choose. </para> <para>(If you have already installed the same version of GHC, Installshield will offer to "modify", -or "remove" GHC. Choose "remove"; then run <Filename>setup.exe</Filename> a +or "remove" GHC. Choose "remove"; then run <filename>setup.exe</filename> a second time. This time it should offer to install.) </para> <para> @@ -584,7 +584,7 @@ if TEMP is set.</para></listitem> <listitem><para>Otherwise, there is a per-user default which varies between versions of Windows. On NT and XP-ish versions, it might be: -<Filename>c:\Documents and Settings\<username>\Local Settings\Temp</filename> +<filename>c:\Documents and Settings\<username>\Local Settings\Temp</filename> </para></listitem> </itemizedlist> The main point is that if you don't do anything GHC will work fine; @@ -593,12 +593,12 @@ setting TMP or TEMP. </para></listitem> <listitem> -<Para> +<para> To test the fruits of your labour, try now to compile a simple Haskell program: -</Para> +</para> -<Screen> +<screen> bash$ cat main.hs module Main(main) where @@ -607,7 +607,7 @@ bash$ ghc -o main main.hs .. bash$ ./main Hello, world! -bash$ </Screen> +bash$ </screen> </listitem> </itemizedlist> @@ -615,18 +615,18 @@ bash$ </Screen> You do <emphasis>not</emphasis> need the Cygwin toolchain, or anything else, to install and run GHC. </para> -<Para> +<para> An installation of GHC requires about 140M of disk space. To run GHC comfortably, your machine should have at least 64M of memory. -</Para> +</para> </sect2> -<Sect2><title>Moving GHC around</title> -<Para> -At the moment, GHC installs in a fixed place (<Filename>c:/ghc/ghc-x.yy</Filename>, +<sect2><title>Moving GHC around</title> +<para> +At the moment, GHC installs in a fixed place (<filename>c:/ghc/ghc-x.yy</filename>, but once it is installed, you can freely move the entire GHC tree just by copying -the <Filename>ghc-x.yy</Filename> directory. (You may need to fix up +the <filename>ghc-x.yy</filename> directory. (You may need to fix up the links in "Start/Programs/Glasgow Haskell Compiler" if you do this.) </para> <para> @@ -636,69 +636,70 @@ because Cygwin can get confused when this happpens. We havn't quite got to the bottom of this, but so far as we know it's not a problem with GHC itself. Nevertheless, just to keep life simple we usually put GHC in a place with a space-free path. -</Para> +</para> </sect2> -<Sect2 id="winfaq"><title>Installing ghc-win32 FAQ</title> +<sect2 id="winfaq"> +<title>Installing ghc-win32 FAQ</title> -<QandASet> +<qandaset> -<QandAEntry> +<qandaentry> -<Question> -<Para> +<question> +<para> I'm having trouble with symlinks. -</Para> -</Question> +</para> +</question> -<Answer> -<Para> -Symlinks only work under Cygwin (<Xref LinkEnd="sec-install">), so binaries +<answer> +<para> +Symlinks only work under Cygwin (<xref linkend="sec-install"/>), so binaries not linked to the Cygwin DLL, in particular those built for Mingwin, will not work with symlinks. -</Para> -</Answer> +</para> +</answer> -</QandAEntry> +</qandaentry> -<QandAEntry> +<qandaentry> -<Question> -<Para> -I'm getting “permission denied” messages from the <Command>rm</Command> or -<Command>mv</Command>. -</Para> -</Question> +<question> +<para> +I'm getting “permission denied” messages from the <command>rm</command> or +<command>mv</command>. +</para> +</question> -<Answer> -<Para> +<answer> +<para> This can have various causes: trying to rename a directory when an Explorer window is open on it tends to fail. Closing the window generally cures the problem, but sometimes its cause is more mysterious, and logging off and back on or rebooting may be the quickest cure. -</Para> -</Answer> +</para> +</answer> -</QandAEntry> +</qandaentry> -</QandASet> +</qandaset> <!-- doesn't add much value any longer; leave out [sof 7/2002]. -<Para> -Further information on using GHC under Windows can be found in <ULink +<para> +Further information on using GHC under Windows can be found in <ulink URL="http://www.dcs.gla.ac.uk/~sof/ghc-win32.html">Sigbjørn Finne's -pages</ULink>. Note: ignore the installation instructions, which are rather -out of date; the <Emphasis>Miscellaneous</Emphasis> section at the bottom of +pages</ulink>. Note: ignore the installation instructions, which are rather +out of date; the <emphasis>Miscellaneous</emphasis> section at the bottom of the page is of most interest, covering topics beyond the scope of this manual. -</Para> +</para> --> -</Sect2> +</sect2> -</Sect1> +</sect1> -<Sect1 id="sec-install-files"><Title>The layout of installed files</Title> +<sect1 id="sec-install-files"><title>The layout of installed files</title> <para> This section describes what files get installed where. You don't need to know it @@ -709,19 +710,19 @@ the implementation. <variablelist> <varlistentry> <term>Library directory,</term> -<listitem> <para> known as <Filename>$(libdir)</Filename>, holds all the +<listitem> <para> known as <filename>$(libdir)</filename>, holds all the support files needed to run GHC. On Unix, this -directory is usually something like <Filename>/usr/lib/ghc/ghc-5.02</Filename>. </para> +directory is usually something like <filename>/usr/lib/ghc/ghc-5.02</filename>. </para> </listitem> </varlistentry> <varlistentry> <term>Binary directory</term> -<listitem> <para> known as <Filename>$(bindir)</Filename>, holds executables that +<listitem> <para> known as <filename>$(bindir)</filename>, holds executables that the user is expected to invoke. Notably, it contains -<Filename>ghc</Filename> and <Filename>ghci</FileName>. On Unix, this directory -can be anywhere, but is typically something like <Filename>/usr/local/bin</Filename>. On Windows, -however, this directory <emphasis>must be</emphasis> <Filename>$(libdir)/bin</Filename>. +<filename>ghc</filename> and <filename>ghci</filename>. On Unix, this directory +can be anywhere, but is typically something like <filename>/usr/local/bin</filename>. On Windows, +however, this directory <emphasis>must be</emphasis> <filename>$(libdir)/bin</filename>. </para> </listitem> </varlistentry> @@ -734,7 +735,7 @@ It finds this out in one of two ways: <itemizedlist> <listitem> <para> -<Filename>$(libdir)</Filename> is passed to GHC using the <option>-B</option> flag. +<filename>$(libdir)</filename> is passed to GHC using the <option>-B</option> flag. On Unix (but not Windows), the installed <filename>ghc</filename> is just a one-line shell script that invokes the real GHC, passing a suitable <option>-B</option> flag. [All the user-supplied flags @@ -745,22 +746,22 @@ one wins.] <listitem> <para> On Windows (but not Unix), if no <option>-B</option> flag is given, GHC uses a system call to find the directory in which the running GHC executable lives, and derives -<Filename>$(libdir)</Filename> from that. [Unix lacks such a system call.] -That is why <Filename>$(bindir)</Filename> must be <Filename>$(libdir)/bin</Filename>. +<filename>$(libdir)</filename> from that. [Unix lacks such a system call.] +That is why <filename>$(bindir)</filename> must be <filename>$(libdir)/bin</filename>. </para> </listitem> </itemizedlist> <sect2> <title>The binary directory</title> -<para>The binary directory, <Filename>$(bindir)</Filename> contains user-visible +<para>The binary directory, <filename>$(bindir)</filename> contains user-visible executables, notably <filename>ghc</filename> and <filename>ghci</filename>. You should add it to your <literal>$PATH</literal> </para> <para>On Unix, the user-invokable <filename>ghc</filename> invokes <filename>$(libdir)/ghc-<replaceable>version</replaceable></filename>, passing a suitable <option>-B</option> flag to tell <filename>ghc-<replaceable>version</replaceable></filename> where -<Filename>$(libdir)</Filename> is. +<filename>$(libdir)</filename> is. Similarly <filename>ghci</filename>, except the extra flag <literal>--interactive</literal> is passed. </para> @@ -882,7 +883,7 @@ with the Win32 distribution of GHC. </para> </sect1> -</Chapter> +</chapter> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/intro.sgml b/ghc/docs/users_guide/intro.sgml index 32f8fa9498..733f8c8846 100644 --- a/ghc/docs/users_guide/intro.sgml +++ b/ghc/docs/users_guide/intro.sgml @@ -8,8 +8,8 @@ <para>GHC has two main components: an interactive Haskell interpreter (also known as GHCi), described in <xref - linkend="ghci">, and a batch compiler, described throughout <xref - linkend="using-ghc">. In fact, GHC consists of a single program + linkend="ghci"/>, and a batch compiler, described throughout <xref + linkend="using-ghc"/>. In fact, GHC consists of a single program which is just run with different options to provide either the interactive or the batch system.</para> @@ -26,7 +26,7 @@ extensions such as multi-parameter type classes, local universal and existential quantification, functional dependencies, scoped type variables and explicit unboxed types. These are all described in - <xref linkend="ghc-language-features">.</para> + <xref linkend="ghc-language-features"/>.</para> <para>GHC has a comprehensive optimiser, so when you want to Really Go For It (and you've got time to spare) GHC can produce pretty fast @@ -37,18 +37,18 @@ <para>GHC's profiling system supports “cost centre stacks”: a way of seeing the profile of a Haskell program in a - call-graph like structure. See <xref linkend="profiling"> for more + call-graph like structure. See <xref linkend="profiling"/> for more details.</para> <para>GHC comes with a large collection of libraries, with everything from parser combinators to networking. The libraries are described in separate documentation.</para> - <Sect1 id="mailing-lists-GHC"> - <Title>Meta-information: Web sites, mailing lists, etc.</Title> + <sect1 id="mailing-lists-GHC"> + <title>Meta-information: Web sites, mailing lists, etc.</title> - <IndexTerm><Primary>mailing lists, Glasgow Haskell</Primary></IndexTerm> - <IndexTerm><Primary>Glasgow Haskell mailing lists</Primary></IndexTerm> + <indexterm><primary>mailing lists, Glasgow Haskell</primary></indexterm> + <indexterm><primary>Glasgow Haskell mailing lists</primary></indexterm> <para>On the World-Wide Web, there are several URLs of likely interest:</para> @@ -81,7 +81,7 @@ <listitem> <para>This list is for GHC users to chat among themselves. If you have a specific question about GHC, please check the - FAQ first (<xref linkend="faq">).</para> + FAQ first (<xref linkend="faq"/>).</para> <variablelist> <varlistentry> @@ -236,15 +236,15 @@ </listitem> <listitem> <para>Email your bug report to - <Email>glasgow-haskell-bugs@haskell.org</Email>. </para> + <email>glasgow-haskell-bugs@haskell.org</email>. </para> </listitem> </itemizedlist> <sect2> <title>How do I tell if I should report my bug?</title> - <para>Take a look at the FAQ (<xref linkend="faq">) and <xref - linkend="wrong">, which will give you some guidance as to + <para>Take a look at the FAQ (<xref linkend="faq"/>) and <xref + linkend="wrong"/>, which will give you some guidance as to whether the behaviour you're seeing is really a bug or not.</para> @@ -271,13 +271,13 @@ <listitem> <para>What kind of machine are you running on, and exactly what version of the operating system are you using? - (on a Unix system, <Command>uname -a</Command> or <Command>cat - /etc/motd</Command> will show the desired information.)</para> + (on a Unix system, <command>uname -a</command> or <command>cat + /etc/motd</command> will show the desired information.)</para> </listitem> <listitem> - <para> What version of GCC are you using? <Command>gcc - -v</Command> will tell you.</para> + <para> What version of GCC are you using? <command>gcc + -v</command> will tell you.</para> </listitem> <listitem> @@ -289,7 +289,7 @@ <listitem> <para> Be sure any Haskell compilations are run with a - <Option>-v</Option> (verbose) flag, so we can see exactly + <option>-v</option> (verbose) flag, so we can see exactly what was run, what versions of things you have, etc.</para> </listitem> @@ -335,7 +335,7 @@ old libraries.</para> <para>The value of <literal>__GLASGOW_HASKELL__</literal> - (see <xref linkend="c-pre-processor">) for a major release + (see <xref linkend="c-pre-processor"/>) for a major release <literal><replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable></literal> is the integer <replaceable>xyy</replaceable> (if <replaceable>y</replaceable> is a single digit, then a leading zero @@ -391,13 +391,13 @@ <para>The version number of your copy of GHC can be found by invoking <literal>ghc</literal> with the <literal>––version</literal> flag (see <xref - linkend="options-help">).</para> + linkend="options-help"/>).</para> </sect1> &relnotes; -</Chapter> +</chapter> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/lang.sgml b/ghc/docs/users_guide/lang.sgml index bae8c86abf..65c0a19bee 100644 --- a/ghc/docs/users_guide/lang.sgml +++ b/ghc/docs/users_guide/lang.sgml @@ -1,10 +1,10 @@ -<Chapter id="ghc-language-features"> -<Title>GHC Language Features</Title> +<chapter id="ghc-language-features"> +<title>GHC Language Features</title> -&glasgowexts -¶llel +&glasgowexts; +∥ -</Chapter> +</chapter> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/license.sgml b/ghc/docs/users_guide/license.sgml index ca425542fc..897e8d5ddd 100644 --- a/ghc/docs/users_guide/license.sgml +++ b/ghc/docs/users_guide/license.sgml @@ -1,46 +1,46 @@ -<Preface id="License"> -<Title>The Glasgow Haskell Compiler License</Title> +<preface id="License"> +<title>The Glasgow Haskell Compiler License</title> -<Para> +<para> Copyright 2002, The University Court of the University of Glasgow. All rights reserved. -</Para> +</para> -<Para> +<para> Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: -</Para> +</para> -<Para> -<ItemizedList> +<para> +<itemizedlist> -<ListItem> -<Para> +<listitem> +<para> Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. -</Para> -</ListItem> +</para> +</listitem> -<ListItem> -<Para> +<listitem> +<para> Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. -</Para> -</ListItem> +</para> +</listitem> -<ListItem> -<Para> +<listitem> +<para> Neither name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. -</Para> -</ListItem> +</para> +</listitem> -</ItemizedList> -</Para> +</itemizedlist> +</para> -<Para> +<para> THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY COURT OF THE UNIVERSITY OF GLASGOW AND THE CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND @@ -53,6 +53,6 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -</Para> +</para> -</Preface> +</preface> diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml index 0852ec7217..9e8e7c9222 100644 --- a/ghc/docs/users_guide/packages.sgml +++ b/ghc/docs/users_guide/packages.sgml @@ -18,7 +18,7 @@ from an existing GHC installation, using the supplied <literal>ghc-pkg</literal><indexterm><primary><literal>ghc-pkg</literal></primary> </indexterm> tool, described in <xref - linkend="package-management">.</para> + linkend="package-management"/>.</para> <sect2 id="using-packages"> <title>Using a package</title> @@ -59,7 +59,7 @@ <para>There's one case where you need to use the <option>-package</option> option even for auto packages: when - linking a program in batch mode mode (<xref linkend="options-order">) + linking a program in batch mode mode (<xref linkend="options-order"/>) <footnote><para>This is because GHC can't figure out from the object files which packages are required; in <option>––make</option> mode and in @@ -75,7 +75,7 @@ The same flag is necessary even if we compiled the modules from source, because GHC still reckons it's in batch mode: <screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen> -In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes">), however, GHC figures out +In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes"/>), however, GHC figures out the auto packages required for linking without further assistance. </para> @@ -112,7 +112,7 @@ the auto packages required for linking without further assistance. <quote><literal>[]</literal></quote> in it. Packages can be added to the new configuration file using the <literal>ghc-pkg</literal> tool, described in <xref - linkend="package-management">.</para> + linkend="package-management"/>.</para> </sect2> <sect2 id="building-packages"> @@ -146,7 +146,7 @@ the auto packages required for linking without further assistance. make an inter-DLL call rather than an intra-DLL call (inter-DLL calls require an extra indirection). <emphasis>Building packages as DLLs doesn't - work at the moment; see <XRef LinkEnd="win32-dlls-create"> + work at the moment; see <xref linkend="win32-dlls-create"/> for the gory details.</emphasis> </para> @@ -168,7 +168,7 @@ the auto packages required for linking without further assistance. called <filename>HSfoo.o</filename> and load that. On some systems, the <literal>ghc-pkg</literal> tool can automatically build the GHCi version of each library, see - <xref linkend="package-management">. To build these + <xref linkend="package-management"/>. To build these libraries by hand from the <literal>.a</literal> archive, it is possible to use GNU <command>ld</command> as follows:</para> @@ -438,7 +438,7 @@ the auto packages required for linking without further assistance. <listitem> <para>Set to <literal>True</literal> if the package should be automatically available (see <xref - linkend="using-packages">). This is normally set to + linkend="using-packages"/>). This is normally set to <literal>True</literal> for packages which contain hierarchical libraries, because in that case there is no danger of polluting the module namespace.</para> @@ -668,7 +668,7 @@ the auto packages required for linking without further assistance. database as follows: </para> <screen> - $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg + $ installdir=/usr/local/lib ghc-pkg -a < mypkg.pkg </screen> <para> diff --git a/ghc/docs/users_guide/parallel.sgml b/ghc/docs/users_guide/parallel.sgml index 9a6502ac41..3a754af61b 100644 --- a/ghc/docs/users_guide/parallel.sgml +++ b/ghc/docs/users_guide/parallel.sgml @@ -1,122 +1,121 @@ -<Sect1 id="concurrent-and-parallel"> -<Title>Concurrent and Parallel Haskell -</Title> +<sect1 id="concurrent-and-parallel"> +<title>Concurrent and Parallel Haskell</title> -<Para> -<IndexTerm><Primary>Concurrent Haskell</Primary></IndexTerm> -<IndexTerm><Primary>Parallel Haskell</Primary></IndexTerm> +<para> +<indexterm><primary>Concurrent Haskell</primary></indexterm> +<indexterm><primary>Parallel Haskell</primary></indexterm> Concurrent and Parallel Haskell are Glasgow extensions to Haskell which let you structure your program as a group of independent `threads'. -</Para> +</para> -<Para> +<para> Concurrent and Parallel Haskell have very different purposes. -</Para> +</para> -<Para> +<para> Concurrent Haskell is for applications which have an inherent structure of interacting, concurrent tasks (i.e. `threads'). Threads -in such programs may be <Emphasis>required</Emphasis>. For example, if a concurrent thread has been spawned to handle a mouse click, it isn't +in such programs may be <emphasis>required</emphasis>. For example, if a concurrent thread has been spawned to handle a mouse click, it isn't optional—the user wants something done! -</Para> +</para> -<Para> +<para> A Concurrent Haskell program implies multiple `threads' running within a single Unix process on a single processor. -</Para> +</para> -<Para> +<para> You will find at least one paper about Concurrent Haskell hanging off -of <ULink URL="http://research.microsoft.com/~simonpj/">Simon Peyton -Jones's Web page</ULink>. -</Para> +of <ulink URL="http://research.microsoft.com/~simonpj/">Simon Peyton +Jones's Web page</ulink>. +</para> -<Para> -Parallel Haskell is about <Emphasis>speed</Emphasis>—spawning +<para> +Parallel Haskell is about <emphasis>speed</emphasis>—spawning threads onto multiple processors so that your program will run faster. -The `threads' are always <Emphasis>advisory</Emphasis>—if the +The `threads' are always <emphasis>advisory</emphasis>—if the runtime system thinks it can get the job done more quickly by sequential execution, then fine. -</Para> +</para> -<Para> +<para> A Parallel Haskell program implies multiple processes running on multiple processors, under a PVM (Parallel Virtual Machine) framework. An MPI interface is under development but not fully functional, yet. -</Para> +</para> -<Para> +<para> Parallel Haskell is still relatively new; it is more about “research fun” than about “speed.” That will change. -</Para> +</para> -<Para> -Check the <ULink URL="http://www.cee.hw.ac.uk/~dsg/gph/">GPH Page</Ulink> +<para> +Check the <ulink url="http://www.cee.hw.ac.uk/~dsg/gph/">GPH Page</ulink> for more information on “GPH” (Haskell98 with extensions for parallel execution), the latest version of “GUM” (the runtime system to enable parallel executions) and papers on research issues. A list of publications about GPH and about GUM is also available from Simon's Web Page. -</Para> +</para> -<Para> +<para> Some details about Parallel Haskell follow. For more information about concurrent Haskell, see the module <literal>Control.Concurrent</literal> in the library documentation. -</Para> +</para> -<Sect2> -<Title>Features specific to Parallel Haskell -<IndexTerm><Primary>Parallel Haskell—features</Primary></IndexTerm></Title> +<sect2> +<title>Features specific to Parallel Haskell +<indexterm><primary>Parallel Haskell—features</primary></indexterm></title> -<Sect3> -<Title>The <Literal>Parallel</Literal> interface (recommended) -<IndexTerm><Primary>Parallel interface</Primary></IndexTerm></Title> +<sect3> +<title>The <literal>Parallel</literal> interface (recommended) +<indexterm><primary>Parallel interface</primary></indexterm></title> -<Para> +<para> GHC provides two functions for controlling parallel execution, through -the <Literal>Parallel</Literal> interface: -</Para> +the <literal>Parallel</literal> interface: +</para> -<Para> +<para> -<ProgramListing> +<programlisting> interface Parallel where infixr 0 `par` infixr 1 `seq` par :: a -> b -> b seq :: a -> b -> b -</ProgramListing> +</programlisting> -</Para> +</para> -<Para> -The expression <Literal>(x `par` y)</Literal> <Emphasis>sparks</Emphasis> the evaluation of <Literal>x</Literal> -(to weak head normal form) and returns <Literal>y</Literal>. Sparks are queued for +<para> +The expression <literal>(x `par` y)</literal> <emphasis>sparks</emphasis> the evaluation of <literal>x</literal> +(to weak head normal form) and returns <literal>y</literal>. Sparks are queued for execution in FIFO order, but are not executed immediately. At the next heap allocation, the currently executing thread will yield control to the scheduler, and the scheduler will start a new thread (until reaching the active thread limit) for each spark which has not already been evaluated to WHNF. -</Para> +</para> -<Para> -The expression <Literal>(x `seq` y)</Literal> evaluates <Literal>x</Literal> to weak head normal -form and then returns <Literal>y</Literal>. The <Function>seq</Function> primitive can be used to +<para> +The expression <literal>(x `seq` y)</literal> evaluates <literal>x</literal> to weak head normal +form and then returns <literal>y</literal>. The <function>seq</function> primitive can be used to force evaluation of an expression beyond WHNF, or to impose a desired execution sequence for the evaluation of an expression. -</Para> +</para> -<Para> +<para> For example, consider the following parallel version of our old -nemesis, <Function>nfib</Function>: -</Para> +nemesis, <function>nfib</function>: +</para> -<Para> +<para> -<ProgramListing> +<programlisting> import Parallel nfib :: Int -> Int @@ -124,83 +123,83 @@ nfib n | n <= 1 = 1 | otherwise = par n1 (seq n2 (n1 + n2 + 1)) where n1 = nfib (n-1) n2 = nfib (n-2) -</ProgramListing> +</programlisting> -</Para> +</para> -<Para> -For values of <VarName>n</VarName> greater than 1, we use <Function>par</Function> to spark a thread -to evaluate <Literal>nfib (n-1)</Literal>, and then we use <Function>seq</Function> to force the -parent thread to evaluate <Literal>nfib (n-2)</Literal> before going on to add +<para> +For values of <varname>n</varname> greater than 1, we use <function>par</function> to spark a thread +to evaluate <literal>nfib (n-1)</literal>, and then we use <function>seq</function> to force the +parent thread to evaluate <literal>nfib (n-2)</literal> before going on to add together these two subexpressions. In this divide-and-conquer approach, we only spark a new thread for one branch of the computation (leaving the parent to evaluate the other branch). Also, we must use -<Function>seq</Function> to ensure that the parent will evaluate <VarName>n2</VarName> <Emphasis>before</Emphasis> -<VarName>n1</VarName> in the expression <Literal>(n1 + n2 + 1)</Literal>. It is not sufficient to -reorder the expression as <Literal>(n2 + n1 + 1)</Literal>, because the compiler may +<function>seq</function> to ensure that the parent will evaluate <varname>n2</varname> <emphasis>before</emphasis> +<varname>n1</varname> in the expression <literal>(n1 + n2 + 1)</literal>. It is not sufficient to +reorder the expression as <literal>(n2 + n1 + 1)</literal>, because the compiler may not generate code to evaluate the addends from left to right. -</Para> +</para> -</Sect3> +</sect3> -<Sect3> -<Title>Underlying functions and primitives -<IndexTerm><Primary>parallelism primitives</Primary></IndexTerm> -<IndexTerm><Primary>primitives for parallelism</Primary></IndexTerm></Title> +<sect3> +<title>Underlying functions and primitives +<indexterm><primary>parallelism primitives</primary></indexterm> +<indexterm><primary>primitives for parallelism</primary></indexterm></title> -<Para> -The functions <Function>par</Function> and <Function>seq</Function> are wired into GHC, and unfold -into uses of the <Function>par#</Function> and <Function>seq#</Function> primitives, respectively. If +<para> +The functions <function>par</function> and <function>seq</function> are wired into GHC, and unfold +into uses of the <function>par#</function> and <function>seq#</function> primitives, respectively. If you'd like to see this with your very own eyes, just run GHC with the -<Option>-ddump-simpl</Option> option. (Anything for a good time…) -</Para> +<option>-ddump-simpl</option> option. (Anything for a good time…) +</para> -</Sect3> +</sect3> -<Sect3> -<Title>Scheduling policy for concurrent threads -<IndexTerm><Primary>Scheduling—concurrent</Primary></IndexTerm> -<IndexTerm><Primary>Concurrent scheduling</Primary></IndexTerm></Title> +<sect3> +<title>Scheduling policy for concurrent threads +<indexterm><primary>Scheduling—concurrent</primary></indexterm> +<indexterm><primary>Concurrent scheduling</primary></indexterm></title> -<Para> +<para> Runnable threads are scheduled in round-robin fashion. Context switches are signalled by the generation of new sparks or by the expiry of a virtual timer (the timer interval is configurable with the -<Option>-C[<num>]</Option><IndexTerm><Primary>-C<num> RTS option (concurrent, -parallel)</Primary></IndexTerm> RTS option). However, a context switch doesn't +<option>-C[<num>]</option><indexterm><primary>-C<num> RTS option (concurrent, +parallel)</primary></indexterm> RTS option). However, a context switch doesn't really happen until the current heap block is full. You can't get any faster context switching than this. -</Para> +</para> -<Para> +<para> When a context switch occurs, pending sparks which have not already been reduced to weak head normal form are turned into new threads. However, there is a limit to the number of active threads (runnable or blocked) which are allowed at any given time. This limit can be -adjusted with the <Option>-t<num></Option><IndexTerm><Primary>-t <num> RTS option (concurrent, parallel)</Primary></IndexTerm> +adjusted with the <option>-t<num></option><indexterm><primary>-t <num> RTS option (concurrent, parallel)</primary></indexterm> RTS option (the default is 32). Once the thread limit is reached, any remaining sparks are deferred until some of the currently active threads are completed. -</Para> +</para> -</Sect3> +</sect3> -<Sect3> -<Title>Scheduling policy for parallel threads -<IndexTerm><Primary>Scheduling—parallel</Primary></IndexTerm> -<IndexTerm><Primary>Parallel scheduling</Primary></IndexTerm></Title> +<sect3> +<title>Scheduling policy for parallel threads +<indexterm><primary>Scheduling—parallel</primary></indexterm> +<indexterm><primary>Parallel scheduling</primary></indexterm></title> -<Para> +<para> In GUM we use an unfair scheduler, which means that a thread continues to perform graph reduction until it blocks on a closure under evaluation, on a remote closure or until the thread finishes. -</Para> +</para> -</Sect3> +</sect3> -</Sect2> +</sect2> -</Sect1> +</sect1> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/phases.sgml b/ghc/docs/users_guide/phases.sgml index 39e4ea4995..3fb17cf031 100644 --- a/ghc/docs/users_guide/phases.sgml +++ b/ghc/docs/users_guide/phases.sgml @@ -7,7 +7,7 @@ <para>You may specify that a different program be used for one of the phases of the compilation system, in place of whatever - the <Command>ghc</Command> has wired into it. For example, you + the <command>ghc</command> has wired into it. For example, you might want to try a different assembler. The following options allow you to change the external program used for a given compilation phase:</para> @@ -128,7 +128,7 @@ </indexterm> <listitem> <para>Pass <replaceable>option</replaceable> to the - custom pre-processor (see <xref linkend="pre-processor">).</para> + custom pre-processor (see <xref linkend="pre-processor"/>).</para> </listitem> </varlistentry> <varlistentry> @@ -182,7 +182,7 @@ <para>GHC is itself a Haskell program, so if you need to pass options directly to GHC's runtime system you can enclose them in <literal>+RTS ... -RTS</literal> (see <xref - linkend="runtime-control">).</para> + linkend="runtime-control"/>).</para> </sect2> @@ -218,7 +218,7 @@ <option>-D</option> macros passed to the C compiler when compiling via C! For those, use the <option>-optc-Dfoo</option> hack… (see <xref - linkend="forcing-options-through">).</para> + linkend="forcing-options-through"/>).</para> </listitem> </varlistentry> @@ -344,11 +344,11 @@ gaps vs -cpp</primary></indexterm>. In other words, strings such as the following:</para> -<ProgramListing> +<programlisting> strmod = "\ \ p \ \ " -</ProgramListing> +</programlisting> <para>don't work with <option>-cpp</option>; <filename>/usr/bin/cpp</filename> elides the backslash-newline @@ -426,9 +426,9 @@ strmod = "\ way to do this, but you can use this hack from the command-line:</para> -<Screen> +<screen> % ghc -c '-#include <X/Xlib.h>' Xstuff.lhs -</Screen> +</screen> </sect2> @@ -445,7 +445,7 @@ strmod = "\ fast), but may produce code that is slightly slower than compiling via C. <option>-fasm</option> is the default when optimisation is off (see <xref - linkend="options-optimise">).</para> + linkend="options-optimise"/>).</para> </listitem> </varlistentry> @@ -543,7 +543,7 @@ strmod = "\ <indexterm><primary><option>-package</option></primary></indexterm> <listitem> <para>If you are using a Haskell “package” - (see <xref linkend="packages">), don't forget to add the + (see <xref linkend="packages"/>), don't forget to add the relevant <option>-package</option> option when linking the program too: it will cause the appropriate libraries to be linked in with the program. Forgetting the @@ -650,7 +650,7 @@ strmod = "\ be supplying its definition of <function>main()</function> at link-time, you will have to. To signal that to the compiler when linking, use - <option>-no-hs-main</option>. See also <xref linkend="using-own-main">.</para> + <option>-no-hs-main</option>. See also <xref linkend="using-own-main"/>.</para> <para>Notice that since the command-line passed to the linker is rather involved, you probably want to use diff --git a/ghc/docs/users_guide/primitives.sgml b/ghc/docs/users_guide/primitives.sgml index 807e55ad4b..4706671f3d 100644 --- a/ghc/docs/users_guide/primitives.sgml +++ b/ghc/docs/users_guide/primitives.sgml @@ -787,7 +787,7 @@ primitive ops compile to one machine instruction or thereabouts. <para> We use the terms “reading” and “writing” to refer to accessing -<emphasis>mutable</emphasis> arrays (see <xref LinkEnd="sect-mutable">), and +<emphasis>mutable</emphasis> arrays (see <xref linkend="sect-mutable">), and “indexing” to refer to reading a value from an <emphasis>immutable</emphasis> array. </para> @@ -835,7 +835,7 @@ objects, because the result is simply the boxed object. So presumably it should be entered—we never usually return an unevaluated object! This is a pain: primitive ops aren't supposed to do complicated things like enter objects. The current solution is to -return a single element unboxed tuple (see <xref LinkEnd="unboxed-tuples">). +return a single element unboxed tuple (see <xref linkend="unboxed-tuples">). </para> <para> diff --git a/ghc/docs/users_guide/profiling.sgml b/ghc/docs/users_guide/profiling.sgml index e79e63824a..25ea4bca1f 100644 --- a/ghc/docs/users_guide/profiling.sgml +++ b/ghc/docs/users_guide/profiling.sgml @@ -1,5 +1,5 @@ <chapter id="profiling"> - <title>Profiling</Title> + <title>Profiling</title> <indexterm><primary>profiling</primary> </indexterm> <indexterm><primary>cost-centre profiling</primary></indexterm> @@ -20,7 +20,7 @@ <literal>-prof</literal> option, and probably one of the <literal>-auto</literal> or <literal>-auto-all</literal> options. These options are described in more detail in <xref - linkend="prof-compiler-options"> </para> + linkend="prof-compiler-options"/> </para> <indexterm><primary><literal>-prof</literal></primary> </indexterm> <indexterm><primary><literal>-auto</literal></primary> @@ -61,7 +61,7 @@ <programlisting> main = print (nfib 25) -nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2) +nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2) </programlisting> <para>Compile and run this program as follows:</para> @@ -137,7 +137,7 @@ MAIN MAIN 0 0.0 0.0 100.0 100.0 main = print (f 25 + g 25) f n = nfib n g n = nfib (n `div` 2) -nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2) +nfib n = if n < 2 then 1 else nfib (n-1) + nfib (n-2) </programlisting> <para>Compile and run this program as before, and take a look at @@ -208,7 +208,7 @@ MAIN MAIN 0 0.0 0.0 100.0 100.0 </varlistentry> </variablelist> - <para>In addition you can use the <Option>-P</Option> RTS option + <para>In addition you can use the <option>-P</option> RTS option <indexterm><primary><option>-P</option></primary></indexterm> to get the following additional information:</para> @@ -225,13 +225,13 @@ MAIN MAIN 0 0.0 0.0 100.0 100.0 <varlistentry> <term><literal>bytes</literal></term> - <listItem> + <listitem> <para>Number of bytes allocated in the heap while in this cost-centre; again, this is the raw number from which we get the <literal>%alloc</literal> figure mentioned above.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> </variablelist> <para>What about recursive functions, and mutually recursive @@ -240,7 +240,7 @@ MAIN MAIN 0 0.0 0.0 100.0 100.0 called each other recursively, this information isn't displayed in the basic time and allocation profile, instead the call-graph is flattened into a tree. The XML profiling tool (described in <xref - linkend="prof-xml-tool">) will be able to display real loops in + linkend="prof-xml-tool"/>) will be able to display real loops in the call-graph.</para> <sect2><title>Inserting cost centres by hand</title> @@ -294,7 +294,7 @@ MAIN MAIN 0 0.0 0.0 100.0 100.0 </listitem> <listitem> - <para>Time spent in foreign code (see <xref linkend="ffi">) + <para>Time spent in foreign code (see <xref linkend="ffi"/>) is always attributed to the cost centre in force at the Haskell call-site of the foreign function.</para> </listitem> @@ -342,11 +342,11 @@ x = nfib 25 <indexterm><primary>profiling</primary><secondary>options</secondary></indexterm> <indexterm><primary>options</primary><secondary>for profiling</secondary></indexterm> - <variableList> - <varListEntry> - <term><Option>-prof</Option>:</Term> + <variablelist> + <varlistentry> + <term><option>-prof</option>:</term> <indexterm><primary><option>-prof</option></primary></indexterm> - <listItem> + <listitem> <para> To make use of the profiling system <emphasis>all</emphasis> modules must be compiled and linked with the <option>-prof</option> option. Any @@ -357,8 +357,8 @@ x = nfib 25 <literal>SCC</literal>s are ignored; so you can compile <literal>SCC</literal>-laden code without changing it.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> </variablelist> <para>There are a few other profiling-related compilation options. @@ -368,73 +368,73 @@ x = nfib 25 <variablelist> <varlistentry> - <term><option>-auto</option>:</Term> + <term><option>-auto</option>:</term> <indexterm><primary><option>-auto</option></primary></indexterm> <indexterm><primary>cost centres</primary><secondary>automatically inserting</secondary></indexterm> - <listItem> + <listitem> <para> GHC will automatically add - <Function>_scc_</Function> constructs for all + <function>_scc_</function> constructs for all top-level, exported functions.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><option>-auto-all</option>:</Term> + <varlistentry> + <term><option>-auto-all</option>:</term> <indexterm><primary><option>-auto-all</option></primary></indexterm> - <listItem> - <para> <Emphasis>All</Emphasis> top-level functions, + <listitem> + <para> <emphasis>All</emphasis> top-level functions, exported or not, will be automatically - <Function>_scc_</Function>'d.</para> - </listItem> - </varListEntry> + <function>_scc_</function>'d.</para> + </listitem> + </varlistentry> - <varListEntry> - <term><option>-caf-all</option>:</Term> + <varlistentry> + <term><option>-caf-all</option>:</term> <indexterm><primary><option>-caf-all</option></primary></indexterm> - <listItem> + <listitem> <para> 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…</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><option>-ignore-scc</option>:</Term> + <varlistentry> + <term><option>-ignore-scc</option>:</term> <indexterm><primary><option>-ignore-scc</option></primary></indexterm> - <listItem> - <para>Ignore any <Function>_scc_</Function> + <listitem> + <para>Ignore any <function>_scc_</function> constructs, so a module which already has - <Function>_scc_</Function>s can be compiled + <function>_scc_</function>s can be compiled for profiling with the annotations ignored.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - </variableList> + </variablelist> </sect1> <sect1 id="prof-time-options"> - <title>Time and allocation profiling</Title> + <title>Time and allocation profiling</title> <para>To generate a time and allocation profile, give one of the following RTS options to the compiled program when you run it (RTS options should be enclosed between <literal>+RTS...-RTS</literal> as usual):</para> - <variableList> - <varListEntry> - <term><Option>-p</Option> or <Option>-P</Option>:</Term> + <variablelist> + <varlistentry> + <term><option>-p</option> or <option>-P</option>:</term> <indexterm><primary><option>-p</option></primary></indexterm> <indexterm><primary><option>-P</option></primary></indexterm> <indexterm><primary>time profile</primary></indexterm> - <listItem> - <para>The <Option>-p</Option> option produces a standard - <Emphasis>time profile</Emphasis> report. It is written + <listitem> + <para>The <option>-p</option> option produces a standard + <emphasis>time profile</emphasis> report. It is written into the file - <Filename><replaceable>program</replaceable>.prof</Filename>.</para> + <filename><replaceable>program</replaceable>.prof</filename>.</para> - <para>The <Option>-P</Option> option produces a more + <para>The <option>-P</option> option produces a more detailed report containing the actual time and allocation data as well. (Not used much.)</para> </listitem> @@ -446,7 +446,7 @@ x = nfib 25 <listitem> <para>The <option>-px</option> option generates profiling information in the XML format understood by our new - profiling tool, see <xref linkend="prof-xml-tool">.</para> + profiling tool, see <xref linkend="prof-xml-tool"/>.</para> </listitem> </varlistentry> @@ -458,11 +458,11 @@ x = nfib 25 <para>This option makes use of the extra information maintained by the cost-centre-stack profiler to provide useful information about the location of runtime errors. - See <xref linkend="rts-options-debugging">.</para> + See <xref linkend="rts-options-debugging"/>.</para> </listitem> </varlistentry> - </variableList> + </variablelist> </sect1> @@ -482,7 +482,7 @@ x = nfib 25 <orderedlist> <listitem> <para>Compile the program for profiling (<xref - linkend="prof-compiler-options">).</para> + linkend="prof-compiler-options"/>).</para> </listitem> <listitem> <para>Run it with one of the heap profiling options described @@ -495,7 +495,7 @@ x = nfib 25 file, <filename><replaceable>prog</replaceable>.ps</filename>. The <command>hp2ps</command> utility is described in detail in - <xref linkend="hp2ps">.</para> + <xref linkend="hp2ps"/>.</para> </listitem> <listitem> <para>Display the heap profile using a postscript viewer such @@ -565,7 +565,7 @@ x = nfib 25 <listitem> <para>Break down the graph by <firstterm>retainer set</firstterm>. Retainer profiling is described in more - detail below (<xref linkend="retainer-prof">).</para> + detail below (<xref linkend="retainer-prof"/>).</para> </listitem> </varlistentry> @@ -577,7 +577,7 @@ x = nfib 25 <para>Break down the graph by <firstterm>biography</firstterm>. Biographical profiling is described in more detail below (<xref - linkend="biography-prof">).</para> + linkend="biography-prof"/>).</para> </listitem> </varlistentry> </variablelist> @@ -686,16 +686,16 @@ x = nfib 25 <variablelist> <varlistentry> - <term><Option>-i<replaceable>secs</replaceable></Option>:</Term> + <term><option>-i<replaceable>secs</replaceable></option>:</term> <indexterm><primary><option>-i</option></primary></indexterm> - <listItem> + <listitem> <para>Set the profiling (sampling) interval to <replaceable>secs</replaceable> seconds (the default is 0.1 second). Fractions are allowed: for example - <Option>-i0.2</Option> will get 5 samples per second. + <option>-i0.2</option> will get 5 samples per second. This only affects heap profiling; time profiles are always sampled on a 1/50 second frequency.</para> - </listItem> + </listitem> </varlistentry> <varlistentry> @@ -931,7 +931,7 @@ hp2ps [flags] [<file>[.hp]] <para>The program <command>hp2ps</command><indexterm><primary>hp2ps program</primary></indexterm> converts a heap profile as produced - by the <Option>-h<break-down></Option> runtime option into a + by the <option>-h<break-down></option> runtime option into a PostScript graph of the heap profile. By convention, the file to be processed by <command>hp2ps</command> has a <filename>.hp</filename> extension. The PostScript output is @@ -946,36 +946,36 @@ hp2ps [flags] [<file>[.hp]] <para>The flags are:</para> - <variableList> + <variablelist> - <varListEntry> - <term><Option>-d</Option></Term> - <listItem> + <varlistentry> + <term><option>-d</option></term> + <listitem> <para>In order to make graphs more readable, <command>hp2ps</command> sorts the shaded bands for each identifier. The default sort ordering is for the bands with the largest area to be stacked on top of the smaller ones. - The <Option>-d</Option> option causes rougher bands (those + The <option>-d</option> option causes rougher bands (those representing series of values with the largest standard deviations) to be stacked on top of smoother ones.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-b</Option></Term> - <listItem> + <varlistentry> + <term><option>-b</option></term> + <listitem> <para>Normally, <command>hp2ps</command> puts the title of the graph in a small box at the top of the page. However, if the JOB string is too long to fit in a small box (more than 35 characters), then <command>hp2ps</command> will choose to - use a big box instead. The <Option>-b</Option> option + use a big box instead. The <option>-b</option> option forces <command>hp2ps</command> to use a big box.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-e<float>[in|mm|pt]</Option></Term> - <listItem> + <varlistentry> + <term><option>-e<float>[in|mm|pt]</option></term> + <listitem> <para>Generate encapsulated PostScript suitable for inclusion in LaTeX documents. Usually, the PostScript graph is drawn in landscape mode in an area 9 inches wide by 6 @@ -983,112 +983,112 @@ hp2ps [flags] [<file>[.hp]] area to be approximately centred on a sheet of a4 paper. This format is convenient of studying the graph in detail, but it is unsuitable for inclusion in LaTeX documents. The - <Option>-e</Option> option causes the graph to be drawn in + <option>-e</option> option causes the graph to be drawn in portrait mode, with float specifying the width in inches, millimetres or points (the default). The resulting PostScript file conforms to the Encapsulated PostScript (EPS) convention, and it can be included in a LaTeX document using Rokicki's dvi-to-PostScript converter <command>dvips</command>.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-g</Option></Term> - <listItem> + <varlistentry> + <term><option>-g</option></term> + <listitem> <para>Create output suitable for the <command>gs</command> PostScript previewer (or similar). In this case the graph is printed in portrait mode without scaling. The output is unsuitable for a laser printer.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-l</Option></Term> - <listItem> + <varlistentry> + <term><option>-l</option></term> + <listitem> <para>Normally a profile is limited to 20 bands with additional identifiers being grouped into an - <literal>OTHER</literal> band. The <Option>-l</Option> flag + <literal>OTHER</literal> band. The <option>-l</option> flag removes this 20 band and limit, producing as many bands as necessary. No key is produced as it won't fit!. It is useful for creation time profiles with many bands.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-m<int></Option></Term> - <listItem> + <varlistentry> + <term><option>-m<int></option></term> + <listitem> <para>Normally a profile is limited to 20 bands with additional identifiers being grouped into an - <literal>OTHER</literal> band. The <Option>-m</Option> flag + <literal>OTHER</literal> band. The <option>-m</option> flag specifies an alternative band limit (the maximum is 20).</para> - <para><Option>-m0</Option> requests the band limit to be + <para><option>-m0</option> requests the band limit to be removed. As many bands as necessary are produced. However no key is produced as it won't fit! It is useful for displaying creation time profiles with many bands.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-p</Option></Term> - <listItem> + <varlistentry> + <term><option>-p</option></term> + <listitem> <para>Use previous parameters. By default, the PostScript graph is automatically scaled both horizontally and vertically so that it fills the page. However, when preparing a series of graphs for use in a presentation, it is often useful to draw a new graph using the same scale, shading and ordering as a previous one. The - <Option>-p</Option> flag causes the graph to be drawn using + <option>-p</option> flag causes the graph to be drawn using the parameters determined by a previous run of <command>hp2ps</command> on <filename>file</filename>. These are extracted from <filename>file@.aux</filename>.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-s</Option></Term> - <listItem> + <varlistentry> + <term><option>-s</option></term> + <listitem> <para>Use a small box for the title.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-t<float></Option></Term> - <listItem> + <varlistentry> + <term><option>-t<float></option></term> + <listitem> <para>Normally trace elements which sum to a total of less than 1% of the profile are removed from the profile. The <option>-t</option> option allows this percentage to be modified (maximum 5%).</para> - <para><Option>-t0</Option> requests no trace elements to be + <para><option>-t0</option> requests no trace elements to be removed from the profile, ensuring that all the data will be displayed.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-c</Option></Term> - <listItem> + <varlistentry> + <term><option>-c</option></term> + <listitem> <para>Generate colour output.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-y</Option></Term> - <listItem> + <varlistentry> + <term><option>-y</option></term> + <listitem> <para>Ignore marks.</para> - </listItem> - </varListEntry> + </listitem> + </varlistentry> - <varListEntry> - <term><Option>-?</Option></Term> - <listItem> + <varlistentry> + <term><option>-?</option></term> + <listitem> <para>Print out usage information.</para> - </listItem> - </varListEntry> - </variableList> + </listitem> + </varlistentry> + </variablelist> <sect2 id="manipulating-hp"> @@ -1186,7 +1186,7 @@ This can all be encapsulated in a little script: #!/bin/sh head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ | hp2ps > FOO.ps - gv -watch -seascape FOO.ps & + gv -watch -seascape FOO.ps & while [ 1 ] ; do sleep 10 # We generate a new profile every 10 seconds. head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ @@ -1202,7 +1202,7 @@ to re-read its input file: #!/bin/sh head -`fgrep -n END_SAMPLE FOO.hp | tail -1 | cut -d : -f 1` FOO.hp \ | hp2ps > FOO.ps - gv FOO.ps & + gv FOO.ps & gvpsnum=$! while [ 1 ] ; do sleep 10 @@ -1218,7 +1218,7 @@ to re-read its input file: </sect1> <sect1 id="ticky-ticky"> - <title>Using “ticky-ticky” profiling (for implementors)</Title> + <title>Using “ticky-ticky” profiling (for implementors)</title> <indexterm><primary>ticky-ticky profiling</primary></indexterm> <para>(ToDo: document properly.)</para> @@ -1231,7 +1231,7 @@ to re-read its input file: profiling</primary></indexterm> <indexterm><primary>profiling, ticky-ticky</primary></indexterm> because that's the sound a Sun4 makes when it is running up all those counters - (<Emphasis>slowly</Emphasis>).</para> + (<emphasis>slowly</emphasis>).</para> <para>Ticky-ticky profiling is mainly intended for implementors; it is quite separate from the main “cost-centre” @@ -1243,11 +1243,11 @@ to re-read its input file: the installation guide.</para> <para>To get your compiled program to spit out the ticky-ticky - numbers, use a <Option>-r</Option> RTS + numbers, use a <option>-r</option> RTS option<indexterm><primary>-r RTS option</primary></indexterm>. - See <XRef LinkEnd="runtime-control">.</para> + See <xref linkend="runtime-control"/>.</para> - <para>Compiling your program with the <Option>-ticky</Option> + <para>Compiling your program with the <option>-ticky</option> switch yields an executable that performs these counts. Here is a sample ticky-ticky statistics file, generated by the invocation <command>foo +RTS -rfoo.ticky</command>.</para> @@ -1336,12 +1336,12 @@ Total bytes copied during GC: 190096 <para>The formatting of the information above the row of asterisks is subject to change, but hopefully provides a useful - human-readable summary. Below the asterisks <Emphasis>all - counters</Emphasis> maintained by the ticky-ticky system are + human-readable summary. Below the asterisks <emphasis>all + counters</emphasis> maintained by the ticky-ticky system are dumped, in a format intended to be machine-readable: zero or more spaces, an integer, a space, the counter name, and a newline.</para> - <para>In fact, not <Emphasis>all</Emphasis> counters are + <para>In fact, not <emphasis>all</emphasis> counters are necessarily dumped; compile- or run-time flags can render certain counters invalid. In this case, either the counter will simply not appear, or it will appear with a modified counter name, @@ -1350,7 +1350,7 @@ Total bytes copied during GC: 190096 with an inserted <literal>!</literal> above). Software analysing this output should always check that it has the counters it expects. Also, beware: some of the counters can have - <Emphasis>large</Emphasis> values!</para> + <emphasis>large</emphasis> values!</para> </sect1> diff --git a/ghc/docs/users_guide/runtime_control.sgml b/ghc/docs/users_guide/runtime_control.sgml index 15ed0c0080..b7668a00a1 100644 --- a/ghc/docs/users_guide/runtime_control.sgml +++ b/ghc/docs/users_guide/runtime_control.sgml @@ -98,7 +98,7 @@ <variablelist> <varlistentry> - <term><option>-A</option><replaceable>size</replaceable></Term> + <term><option>-A</option><replaceable>size</replaceable></term> <indexterm><primary><option>-A</option></primary><secondary>RTS option</secondary></indexterm> <indexterm><primary>allocation area, size</primary></indexterm> <listitem> @@ -163,7 +163,7 @@ </varlistentry> <varlistentry> - <term><option>-F</option><replaceable>factor</replaceable></Term> + <term><option>-F</option><replaceable>factor</replaceable></term> <listitem> <indexterm><primary><option>-F</option></primary><secondary>RTS option</secondary></indexterm> <indexterm><primary>heap size, factor</primary></indexterm> @@ -190,7 +190,7 @@ </varlistentry> <varlistentry> - <term><option>-G</option><replaceable>generations</replaceable></Term> + <term><option>-G</option><replaceable>generations</replaceable></term> <indexterm><primary><option>-G</option></primary><secondary>RTS option</secondary></indexterm> <indexterm><primary>generations, number of</primary></indexterm> @@ -206,7 +206,7 @@ <para>Specifying 1 generation with <option>+RTS -G1</option> gives you a simple 2-space collector, as you would expect. In a 2-space collector, the <option>-A</option> option (see - above) specifies the <Emphasis>minimum</Emphasis> allocation + above) specifies the <emphasis>minimum</emphasis> allocation area size, since the allocation area will grow with the amount of live data in the heap. In a multi-generational collector the allocation area is a fixed size (unless you @@ -214,7 +214,7 @@ </listitem> </varlistentry> - <VarListEntry> + <varlistentry> <term><option>-H</option><replaceable>size</replaceable></term> <indexterm><primary><option>-H</option></primary><secondary>RTS option</secondary></indexterm> <indexterm><primary>heap size, suggested</primary></indexterm> @@ -304,7 +304,7 @@ <varlistentry> <term><option>-s</option><replaceable>file</replaceable></term> - <term><option>-S</option><replaceable>file</replaceable></Term> + <term><option>-S</option><replaceable>file</replaceable></term> <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm> <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm> <listitem> @@ -312,7 +312,7 @@ (<option>-S</option>) garbage-collector statistics into file <replaceable>file</replaceable>. The default <replaceable>file</replaceable> is - <Filename><replaceable>program</replaceable>.stat</Filename>. The + <filename><replaceable>program</replaceable>.stat</filename>. The <replaceable>file</replaceable> <constant>stderr</constant> is treated specially, with the output really being sent to <constant>stderr</constant>.</para> @@ -336,16 +336,14 @@ </sect2> -<!-- ---------------------------------------------------------------------- --> <sect2> <title>RTS options for profiling and Concurrent/Parallel Haskell</title> - <para>The RTS options related to profiling are described in <XRef - LinkEnd="prof-rts-options">; and those for concurrent/parallel - stuff, in <XRef LinkEnd="parallel-rts-opts">.</para> + <para>The RTS options related to profiling are described in <xref + linkend="rts-options-heap-prof"/>; and those for concurrent/parallel + stuff, in <xref linkend="parallel-rts-opts"/>.</para> </sect2> -<!-- ---------------------------------------------------------------------- --> <sect2 id="rts-options-debugging"> <title>RTS options for hackers, debuggers, and over-interested souls</title> @@ -408,8 +406,8 @@ be really useful, linked with suitable system libraries. Not a trivial undertaking: consult the installation guide on how to set things up for easy “ticky-ticky” - profiling. For more information, see <XRef - LinkEnd="ticky-ticky">.</para> + profiling. For more information, see <xref + linkend="ticky-ticky"/>.</para> </listitem> </varlistentry> @@ -441,7 +439,7 @@ </screen> <para>each <literal>cc</literal><subscript>i</subscript> is a cost centre in the program (see <xref - linkend="cost-centres">), and the sequence represents the + linkend="cost-centres"/>), and the sequence represents the “call stack” at the point the exception was raised. The leftmost item is the innermost function in the call stack, and the rightmost item is the outermost @@ -511,7 +509,7 @@ char *ghc_rts_opts = "-H128m -K1m"; <varlistentry> <term><function>void OutOfHeapHook (unsigned long, unsigned long)</function></term> <indexterm><primary><function>OutOfHeapHook</function></primary></indexterm> - <ListItem> + <listitem> <para>The heap-overflow message.</para> </listitem> </varlistentry> @@ -528,7 +526,7 @@ char *ghc_rts_opts = "-H128m -K1m"; <term><function>void MallocFailHook (long int)</function></term> <indexterm><primary><function>MallocFailHook</function></primary></indexterm> <listitem> - <para>The message printed if <Function>malloc</Function> + <para>The message printed if <function>malloc</function> fails.</para> </listitem> </varlistentry> diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml index 6595b88435..e1052bd163 100644 --- a/ghc/docs/users_guide/separate_compilation.sgml +++ b/ghc/docs/users_guide/separate_compilation.sgml @@ -11,7 +11,7 @@ <para>Note that this section is written with <firstterm>hierarchical modules</firstterm> in mind (see <xref - linkend="hierarchical-modules">); hierarchical modules are an + linkend="hierarchical-modules"/>); hierarchical modules are an extension to Haskell 98 which extends the lexical syntax of module names to include a dot ‘.’. Non-hierarchical modules are thus a special case in which none of the module names @@ -38,7 +38,7 @@ should be placed in the file <literal>A/B/C.hs</literal>, relative to some base directory. GHC's behaviour if this rule is not followed is fully defined by the following section (<xref - linkend="output-files">).</para> + linkend="output-files"/>).</para> </sect2> <sect2 id="output-files"> @@ -64,7 +64,7 @@ types of exported functions, definitions of data types, and so on. It is stored in a binary format, so don't try to read one; use the <option>--show-iface</option> option instead (see <xref - linkend="hi-options">).</para> + linkend="hi-options"/>).</para> <para>You should think of the object file and the interface file as a pair, since the interface file is in a sense a compiler-readable @@ -121,7 +121,7 @@ <para>For any module that is imported, GHC requires that the name of the module in the import statement exactly matches the name of the module in the interface file (or source file) found - using the strategy specified in <xref linkend="search-path">. + using the strategy specified in <xref linkend="search-path"/>. This means that for most modules, the source file name should match the module name.</para> @@ -203,7 +203,7 @@ <para>This isn't the whole story: GHC also looks for modules in pre-compiled libraries, known as packages. See the section on - packages (<xref linkend="packages">), for details.</para> + packages (<xref linkend="packages"/>), for details.</para> </sect2> <sect2 id="options-output"> @@ -260,9 +260,9 @@ <para>Redirects object files to directory <replaceable>dir</replaceable>. For example:</para> -<Screen> +<screen> $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` -</Screen> +</screen> <para>The object files, <filename>Foo.o</filename>, <filename>Bar.o</filename>, and @@ -335,7 +335,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` <para>Similarly, the <option>-hisuf</option> <replaceable>suffix</replaceable> will change the <literal>.hi</literal> file suffix for non-system - interface files (see <XRef LinkEnd="hi-options">).</para> + interface files (see <xref linkend="hi-options"/>).</para> <para>Finally, the option <option>-hcsuf</option> <replaceable>suffix</replaceable> will change the @@ -346,11 +346,11 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` game is particularly useful if you want to compile a program both with and without profiling, in the same directory. You can say: - <Screen> - ghc ...</Screen> + <screen> + ghc ...</screen> to get the ordinary version, and - <Screen> - ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</Screen> + <screen> + ghc ... -osuf prof.o -hisuf prof.hi -prof -auto-all</screen> to get the profiled version.</para> </listitem> </varlistentry> @@ -423,7 +423,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` <para>Instructs the GHC driver not to delete any of its temporary files, which it normally keeps in <literal>/tmp</literal> (or possibly elsewhere; see <xref - linkend="temp-files">). Running GHC with + linkend="temp-files"/>). Running GHC with <option>-v</option> will show you what temporary files were generated along the way.</para> </listitem> @@ -448,30 +448,30 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` in <filename>/tmp</filename> (or wherever your installation thinks temporary files should go), you may use the <option>-tmpdir - <dir></option><IndexTerm><Primary>-tmpdir - <dir> option</Primary></IndexTerm> option to specify + <dir></option><indexterm><primary>-tmpdir + <dir> option</primary></indexterm> option to specify an alternate directory. For example, <option>-tmpdir .</option> says to put temporary files in the current working directory.</para> - <para>Alternatively, use your <Constant>TMPDIR</Constant> - environment variable.<IndexTerm><Primary>TMPDIR - environment variable</Primary></IndexTerm> Set it to the + <para>Alternatively, use your <constant>TMPDIR</constant> + environment variable.<indexterm><primary>TMPDIR + environment variable</primary></indexterm> Set it to the name of the directory where temporary files should be put. GCC and other programs will honour the - <Constant>TMPDIR</Constant> variable as well.</para> + <constant>TMPDIR</constant> variable as well.</para> <para>Even better idea: Set the - <Constant>DEFAULT_TMPDIR</Constant> make variable when + <constant>DEFAULT_TMPDIR</constant> make variable when building GHC, and never worry about - <Constant>TMPDIR</Constant> again. (see the build + <constant>TMPDIR</constant> again. (see the build documentation).</para> </listitem> </varlistentry> </variablelist> </sect2> - <Sect2 id="hi-options"> + <sect2 id="hi-options"> <title>Other options related to interface files</title> <indexterm><primary>interface files, options</primary></indexterm> @@ -589,8 +589,8 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` required”. What a beautiful sight!</para> <para>Patrick Sansom had a workshop paper about how all this is - done (though the details have changed quite a bit). <ULink - URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a + done (though the details have changed quite a bit). <ulink + URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ulink> if you want a copy.</para> </sect2> @@ -604,7 +604,7 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `arch` <filename>Makefile</filename> to use with GHC, assuming you name your source files the same as your modules. Thus:</para> -<ProgramListing> +<programlisting> HC = ghc HC_OPTS = -cpp $(EXTRA_HC_OPTS) @@ -630,17 +630,17 @@ cool_pgm : $(OBJS) # Inter-module dependencies Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz -</ProgramListing> +</programlisting> <para>(Sophisticated <command>make</command> variants may achieve some of the above more elegantly. Notably, <command>gmake</command>'s pattern rules let you write the more comprehensible:</para> -<ProgramListing> +<programlisting> %.o : %.lhs $(HC) -c $< $(HC_OPTS) -</ProgramListing> +</programlisting> <para>What we've shown should work with any <command>make</command>.)</para> @@ -654,9 +654,9 @@ Main.o Main.hc Main.s : Foo.hi Baz.hi # Main imports Foo and Baz <para>Note the inter-module dependencies at the end of the Makefile, which take the form</para> -<ProgramListing> +<programlisting> Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz -</ProgramListing> +</programlisting> <para>They tell <command>make</command> that if any of <literal>Foo.o</literal>, <literal>Foo.hc</literal> or @@ -677,10 +677,10 @@ Foo.o Foo.hc Foo.s : Baz.hi # Foo imports Baz automatically generating the required dependencies. Add the following to your <filename>Makefile</filename>:</para> -<ProgramListing> +<programlisting> depend : ghc -M $(HC_OPTS) $(SRCS) -</ProgramListing> +</programlisting> <para>Now, before you start compiling, and any time you change the <literal>imports</literal> in your program, do @@ -716,7 +716,7 @@ import {-# SOURCE #-} B ...blah... A.o : B.hi-boot </programlisting> - (See <xref linkend="mutual-recursion"> for details of + (See <xref linkend="mutual-recursion"/> for details of <literal>hi-boot</literal> style interface files.) If <literal>A</literal> imports multiple modules, then there will be multiple lines with <filename>A.o</filename> as the @@ -873,7 +873,7 @@ ghc -M -optdep-f -optdep.depend ... <para>Currently, the compiler does not have proper support for dealing with mutually recursive modules:</para> -<ProgramListing> +<programlisting> module A where import B @@ -891,7 +891,7 @@ data TB = MkTB !Int g :: TA -> TB g (MkTA x) = MkTB x -</ProgramListing> +</programlisting> <para>When compiling either module A and B, the compiler will try (in vain) to look for the interface file of the other. So, @@ -906,9 +906,9 @@ g (MkTA x) = MkTB x files</primary></indexterm> <indexterm><primary>importing, <literal>hi-boot</literal> files</primary></indexterm></para> -<ProgramListing> +<programlisting> import {-# SOURCE #-} A -</ProgramListing> +</programlisting> <para>The hand-written interface need only contain the bare minimum of information needed to get the bootstrapping process @@ -920,10 +920,10 @@ import {-# SOURCE #-} A <para>For the example at hand, the boot interface file for A would look like the following:</para> -<ProgramListing> +<programlisting> module A where newtype TA = MkTA GHC.Base.Int -</ProgramListing> +</programlisting> <para>The syntax is similar to a normal Haskell source file, but with some important differences:</para> @@ -956,12 +956,12 @@ newtype GHC.IOBase.IO a <listitem> <para>For <literal>data</literal> or <literal>newtype</literal> declaration, you may omit all the constructors, by omitting the '=' and everything that follows it: -<ProgramListing> +<programlisting> module A where data TA -</ProgramListing> +</programlisting> In a <emphasis>source</emphasis> program - this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types">), + this would declare TA to have no constructors (a GHC extension: see <xref linkend="nullary-types"/>), but in an hi-boot file it means "I don't know or care what the construtors are". This is the most common form of data type declaration, because it's easy to get right.</para> <para> @@ -976,7 +976,7 @@ module A where <para> Regardless of whether you write the constructors, you must write all the type parameters, <emphasis>including their kinds</emphasis> - if they are not '*'. (You can give explicit kinds in source files too (<xref linkend="sec-kinding">), + if they are not '*'. (You can give explicit kinds in source files too (<xref linkend="sec-kinding"/>), but you <emphasis>must</emphasis> do so in hi-boot files.)</para> </listitem> @@ -987,8 +987,8 @@ operations. We could lift this restriction if it became tiresome.</para> <para>Notice that we only put the declaration for the newtype <literal>TA</literal> in the <literal>hi-boot</literal> file, - not the signature for <Function>f</Function>, since - <Function>f</Function> isn't used by <literal>B</literal>.</para> + not the signature for <function>f</function>, since + <function>f</function> isn't used by <literal>B</literal>.</para> </sect2> @@ -1006,21 +1006,21 @@ be a disaster in practice, so GHC tries to be clever. </para> <para>In particular, if an instance declaration is in the same module as the definition of any type or class mentioned in the head of the instance declaration, then GHC has to visit that interface file anyway. Example:</para> -<ProgramListing> +<programlisting> module A where instance C a => D (T a) where ... data T a = ... -</ProgramListing> +</programlisting> <para> The instance declaration is only relevant if the type T is in use, and if so, GHC will have visited A's interface file to find T's definition. </para> <para> The only problem comes when a module contains an instance declaration and GHC has no other reason for visiting the module. Example: -<ProgramListing> +<programlisting> module Orphan where instance C a => D (T a) where ... class C a where ... -</ProgramListing> +</programlisting> Here, neither D nor T is declared in module Orphan. We call such modules ``orphan modules'', defined thus:</para> diff --git a/ghc/docs/users_guide/sooner.sgml b/ghc/docs/users_guide/sooner.sgml index 1a24bf4bc1..22af9a046c 100644 --- a/ghc/docs/users_guide/sooner.sgml +++ b/ghc/docs/users_guide/sooner.sgml @@ -43,8 +43,8 @@ should go here!</para> default), and you have lots of memory, try increasing the maximum with the <option>-M<size></option><indexterm><primary>-M<size> - option</primary></indexterm> option, e.g.: <Command>ghc -c - -O -M1024m Foo.hs</Command>.</para> + option</primary></indexterm> option, e.g.: <command>ghc -c + -O -M1024m Foo.hs</command>.</para> <para>Increasing the default allocation area size used by the compiler's RTS might also help: use the @@ -61,16 +61,16 @@ should go here!</para> <listitem> <para>As soon as GHC plus its “fellow citizens” (other processes on your machine) start using more than the - <Emphasis>real memory</Emphasis> on your machine, and the - machine starts “thrashing,” <Emphasis>the party - is over</Emphasis>. Compile times will be worse than + <emphasis>real memory</emphasis> on your machine, and the + machine starts “thrashing,” <emphasis>the party + is over</emphasis>. Compile times will be worse than terrible! Use something like the csh-builtin - <Command>time</Command> command to get a report on how many + <command>time</command> command to get a report on how many page faults you're getting.</para> <para>If you don't know what virtual memory, thrashing, and page faults are, or you don't know the memory configuration - of your machine, <Emphasis>don't</Emphasis> try to be clever + of your machine, <emphasis>don't</emphasis> try to be clever about memory use: you'll just make your life a misery (and for other people, too, probably).</para> </listitem> @@ -84,14 +84,14 @@ should go here!</para> to/from a remote filesystem.</para> <para>It would be quite sensible to - <Emphasis>compile</Emphasis> on a fast machine using - remotely-mounted disks; then <Emphasis>link</Emphasis> on a + <emphasis>compile</emphasis> on a fast machine using + remotely-mounted disks; then <emphasis>link</emphasis> on a slow machine that had your disks directly mounted.</para> </listitem> </varlistentry> <varlistentry> - <term>Don't derive/use <Function>Read</Function> unnecessarily:</term> + <term>Don't derive/use <function>Read</function> unnecessarily:</term> <listitem> <para>It's ugly and slow.</para> </listitem> @@ -135,7 +135,7 @@ should go here!</para> <literal>import Foo (...stuff I want...)</literal> You can get GHC to tell you the minimal set of required imports by using the <option>-ddump-minimal-imports</option> option - (see <xref linkend="hi-options">).</para> + (see <xref linkend="hi-options"/>).</para> <para>Truthfully, the reduction on compilation time will be very small. However, judicious use of @@ -154,20 +154,20 @@ should go here!</para> <para>The key tool to use in making your Haskell program run faster are GHC's profiling facilities, described separately in - <XRef LinkEnd="profiling">. There is <Emphasis>no - substitute</Emphasis> for finding where your program's time/space - is <Emphasis>really</Emphasis> going, as opposed to where you + <xref linkend="profiling"/>. There is <emphasis>no + substitute</emphasis> for finding where your program's time/space + is <emphasis>really</emphasis> going, as opposed to where you imagine it is going.</para> <para>Another point to bear in mind: By far the best way to - improve a program's performance <Emphasis>dramatically</Emphasis> + improve a program's performance <emphasis>dramatically</emphasis> is to use better algorithms. Once profiling has thrown the spotlight on the guilty time-consumer(s), it may be better to re-think your program than to try all the tweaks listed below.</para> <para>Another extremely efficient way to make your program snappy is to use library code that has been Seriously Tuned By Someone - Else. You <Emphasis>might</Emphasis> be able to write a better + Else. You <emphasis>might</emphasis> be able to write a better quicksort than the one in <literal>Data.List</literal>, but it will take you much longer than typing <literal>import Data.List</literal>.</para> @@ -238,8 +238,8 @@ should go here!</para> <indexterm><primary>overloading, death to</primary></indexterm> <para>Specialize the overloading on key functions in - your program. See <XRef LinkEnd="specialize-pragma"> - and <XRef LinkEnd="specialize-instance-pragma">.</para> + your program. See <xref linkend="specialize-pragma"/> + and <xref linkend="specialize-instance-pragma"/>.</para> </listitem> </varlistentry> @@ -250,7 +250,7 @@ should go here!</para> files for overloaded type signatures. You can view interface files using the <option>--show-iface</option> option (see <xref - linkend="hi-options">). + linkend="hi-options"/>). <programlisting> % ghc --show-iface Foo.hi | egrep '^[a-z].*::.*=>' @@ -335,17 +335,17 @@ f (Wibble x y) # ugly, and proud of it the third field in the pragma; it should say <literal>__S <string></literal>. The <literal><string></literal> gives the strictness of - the function's arguments. <Function>L</Function> is lazy - (bad), <Function>S</Function> and <Function>E</Function> are - strict (good), <Function>P</Function> is - “primitive” (good), <Function>U(...)</Function> + the function's arguments. <function>L</function> is lazy + (bad), <function>S</function> and <function>E</function> are + strict (good), <function>P</function> is + “primitive” (good), <function>U(...)</function> is strict and “unpackable” (very good), and - <Function>A</Function> is absent (very good).</para> + <function>A</function> is absent (very good).</para> <para>For an “unpackable” - <Function>U(...)</Function> argument, the info inside tells + <function>U(...)</function> argument, the info inside tells the strictness of its components. So, if the argument is a - pair, and it says <Function>U(AU(LSS))</Function>, that + pair, and it says <function>U(AU(LSS))</function>, 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 \& @@ -364,7 +364,7 @@ f (Wibble x y) # ugly, and proud of it <listitem> <para>Placing <literal>INLINE</literal> pragmas on certain functions that are used a lot can have a dramatic effect. - See <XRef LinkEnd="inline-pragma">.</para> + See <xref linkend="inline-pragma"/>.</para> </listitem> </varlistentry> @@ -375,7 +375,7 @@ f (Wibble x y) # ugly, and proud of it module, GHC must assume that everything in that module will be exported. This has various pessimising effects. For example, if a bit of code is actually - <Emphasis>unused</Emphasis> (perhaps because of unfolding + <emphasis>unused</emphasis> (perhaps because of unfolding effects), GHC will not be able to throw it away, because it is exported and some other module may be relying on its existence.</para> @@ -413,7 +413,7 @@ f (Wibble x y) # ugly, and proud of it <para>It can also help in a third way: when used with <option>-funbox-strict-fields</option> (see <xref - linkend="options-f">), a strict field can be unpacked or + linkend="options-f"/>), a strict field can be unpacked or unboxed in the constructor, and one or more levels of indirection may be removed. Unpacking only happens for single-constructor datatypes (<literal>Int</literal> is a @@ -433,9 +433,9 @@ f (Wibble x y) # ugly, and proud of it <varlistentry> <term>Use unboxed types (a GHC extension):</term> <listitem> - <para>When you are <Emphasis>really</Emphasis> desperate for + <para>When you are <emphasis>really</emphasis> desperate for speed, and you want to get right down to the “raw - bits.” Please see <XRef LinkEnd="glasgow-unboxed"> for + bits.” Please see <xref linkend="glasgow-unboxed"/> for some information about using unboxed types.</para> <para>Before resorting to explicit unboxed types, try using @@ -452,7 +452,7 @@ f (Wibble x y) # ugly, and proud of it of massively-tuned library code, and the best thing is not to compete with it, but link with it.</para> - <para><XRef LinkEnd="ffi"> describes the foreign function + <para><xref linkend="ffi"/> describes the foreign function interface.</para> </listitem> </varlistentry> @@ -474,7 +474,7 @@ f (Wibble x y) # ugly, and proud of it yourself with numerical errors.</para> <para>One time when <literal>Float</literal> might be a good - idea is if you have a <Emphasis>lot</Emphasis> of them, say + idea is if you have a <emphasis>lot</emphasis> of them, say a giant array of <literal>Float</literal>s. They take up half the space in the heap compared to <literal>Doubles</literal>. However, this isn't true on a @@ -506,8 +506,8 @@ f (Wibble x y) # ugly, and proud of it <option>-M<size></option><indexterm><primary>-M<size> RTS option</primary></indexterm> or <option>-A<size></option><indexterm><primary>-A<size> - RTS option</primary></indexterm> RTS options (see <XRef - LinkEnd="rts-options-gc">).</para> + RTS option</primary></indexterm> RTS options (see <xref + linkend="rts-options-gc"/>).</para> <para>This is especially important if your program uses a lot of mutable arrays of pointers or mutable variables @@ -524,7 +524,7 @@ f (Wibble x y) # ugly, and proud of it </varlistentry> </variablelist> -</Sect1> +</sect1> <sect1 id="smaller"> <title>Smaller: producing a program that is smaller @@ -541,19 +541,19 @@ expressions. Give a option</primary></indexterm> option for the extreme case. (“Only unfoldings with zero cost should proceed.”) Warning: except in certain specialised cases (like Happy parsers) this is likely to actually -<Emphasis>increase</Emphasis> the size of your program, because unfolding +<emphasis>increase</emphasis> the size of your program, because unfolding generally enables extra simplifying optimisations to be performed. </para> <para> -Avoid <Function>Read</Function>. +Avoid <function>Read</function>. </para> <para> Use <literal>strip</literal> on your executables. </para> -</Sect1> +</sect1> <sect1 id="thriftier"> <title>Thriftier: producing a program that gobbles less heap space @@ -570,14 +570,14 @@ Use <literal>strip</literal> on your executables. with <option>+RTS -Sstderr</option>, and remove all doubt! (You'll see the heap usage get bigger and bigger…) [Hmmm…this might be even easier with the -<option>-G1</option> RTS option; so… <Command>./a.out +RTS --Sstderr -G1</Command>...] +<option>-G1</option> RTS option; so… <command>./a.out +RTS +-Sstderr -G1</command>...] <indexterm><primary>-G RTS option</primary></indexterm> <indexterm><primary>-Sstderr RTS option</primary></indexterm> </para> <para> -Once again, the profiling facilities (<XRef LinkEnd="profiling">) are +Once again, the profiling facilities (<xref linkend="profiling"/>) are the basic tool for demystifying the space behaviour of your program. </para> @@ -589,9 +589,9 @@ notes to itself about how to evaluate something, should it eventually be required). </para> -</Sect1> +</sect1> -</Chapter> +</chapter> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/ug-book.sgml b/ghc/docs/users_guide/ug-book.sgml index 9cdcbf5801..90b47185b9 100644 --- a/ghc/docs/users_guide/ug-book.sgml +++ b/ghc/docs/users_guide/ug-book.sgml @@ -1,10 +1,10 @@ -<BookInfo> -<Title>The Glasgow Haskell Compiler User's Guide, Version 6.0</Title> -<Author><OtherName>The GHC Team</OtherName></Author> -<Address> -<Email>glasgow-haskell-{bugs,users}-request@haskell.org</Email> -</Address> -</BookInfo> +<bookinfo> +<title>The Glasgow Haskell Compiler User's Guide, Version 6.0</title> +<author><othername>The GHC Team</othername></author> +<address> +<email>glasgow-haskell-{bugs,users}-request@haskell.org</email> +</address> +</bookinfo> &license; &intro; diff --git a/ghc/docs/users_guide/users_guide.sgml b/ghc/docs/users_guide/users_guide.sgml index 41ef1f8a3d..20022c7480 100644 --- a/ghc/docs/users_guide/users_guide.sgml +++ b/ghc/docs/users_guide/users_guide.sgml @@ -3,7 +3,7 @@ %ug-ent; <!ENTITY ug-book SYSTEM "ug-book.sgml"> ]> - + <Book id="users-guide"> &ug-book; </Book> diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml index 8b65f308ab..a79c54968a 100644 --- a/ghc/docs/users_guide/using.sgml +++ b/ghc/docs/users_guide/using.sgml @@ -13,7 +13,7 @@ Options can be specified in three ways:</para> <sect2> - <title>Command-line arguments</title> + <title>command-line arguments</title> <indexterm><primary>structure, command-line</primary></indexterm> <indexterm><primary>command-line</primary><secondary>arguments</secondary></indexterm> @@ -21,13 +21,13 @@ <para>An invocation of GHC takes the following form:</para> -<Screen> +<screen> ghc [argument...] -</Screen> +</screen> - <para>Command-line arguments are either options or file names.</para> + <para>command-line arguments are either options or file names.</para> - <para>Command-line options begin with <literal>-</literal>. + <para>command-line options begin with <literal>-</literal>. They may <emphasis>not</emphasis> be grouped: <option>-vO</option> is different from <option>-v -O</option>. Options need not precede filenames: e.g., <literal>ghc *.o -o @@ -38,8 +38,8 @@ ghc [argument...] <filename>Bar.hs</filename>.</para> </sect2> - <Sect2 id="source-file-options"> - <title>Command line options in source files</title> + <sect2 id="source-file-options"> + <title>command line options in source files</title> <indexterm><primary>source-file options</primary></indexterm> @@ -53,11 +53,11 @@ ghc [argument...] <literal>OPTIONS</literal> pragma <indexterm><primary>OPTIONS pragma</primary></indexterm>:</para> -<ProgramListing> +<programlisting> {-# OPTIONS -fglasgow-exts #-} module X where ... -</ProgramListing> +</programlisting> <para><literal>OPTIONS</literal> pragmas are only looked for at the top of your source files, upto the first @@ -86,7 +86,7 @@ module X where <title>Setting options in GHCi</title> <para>Options may also be modified from within GHCi, using the - <literal>:set</literal> command. See <xref linkend="ghci-set"> + <literal>:set</literal> command. See <xref linkend="ghci-set"/> for more details.</para> </sect2> </sect1> @@ -107,7 +107,7 @@ module X where <para>As a rule of thumb, options which relate to filenames are static, and the rest are dynamic. The flag reference tables (<xref - linkend="flag-reference">) lists the status of each flag.</para> + linkend="flag-reference"/>) lists the status of each flag.</para> </sect1> <sect1 id="file-suffixes"> @@ -193,7 +193,7 @@ module X where <variablelist> <varlistentry> <term><cmdsynopsis><command>ghc</command> - <arg choice=plain>––interactive</arg> + <arg choice='plain'>––interactive</arg> </cmdsynopsis></term> <indexterm><primary>interactive mode</primary> </indexterm> @@ -202,13 +202,13 @@ module X where <listitem> <para>Interactive mode, which is also available as <command>ghci</command>. Interactive mode is described in - more detail in <xref linkend="ghci">.</para> + more detail in <xref linkend="ghci"/>.</para> </listitem> </varlistentry> <varlistentry> <term><cmdsynopsis><command>ghc</command> - <arg choice=plain>––make</arg> + <arg choice='plain'>––make</arg> </cmdsynopsis></term> <indexterm><primary>make mode</primary> </indexterm> @@ -220,13 +220,13 @@ module X where If you have a straightforward Haskell program, this is likely to be much easier, and faster, than using <command>make</command>. Make mode is described in <xref - linkend="make-mode">.</para> + linkend="make-mode"/>.</para> </listitem> </varlistentry> <varlistentry> <term><cmdsynopsis><command>ghc</command> - <arg choice=plain>–e</arg> <arg choice=plain><replaceable>expr</replaceable></arg> + <arg choice='plain'>–e</arg> <arg choice='plain'><replaceable>expr</replaceable></arg> </cmdsynopsis></term> <indexterm><primary>eval mode</primary> </indexterm> @@ -234,7 +234,7 @@ module X where <para>Expression-evaluation mode. This is very similar to interactive mode, except that there is a single expression to evaluate (<replaceable>expr</replaceable>) which is given - on the command line. See <xref linkend="eval-mode"> for + on the command line. See <xref linkend="eval-mode"/> for more details.</para> </listitem> </varlistentry> @@ -260,31 +260,31 @@ module X where there is no other mode flag specified on the command line, in which case it means that the specified files should be compiled and then linked to form a program. See <xref - linkend="options-order">.</para> + linkend="options-order"/>.</para> </listitem> </varlistentry> <varlistentry> <term><cmdsynopsis><command>ghc</command> - <arg choice=plain>–M</arg></cmdsynopsis></term> + <arg choice='plain'>–M</arg></cmdsynopsis></term> <indexterm><primary>dependency-generation mode</primary> </indexterm> <listitem> <para>Dependency-generation mode. In this mode, GHC can be used to generate dependency information suitable for use in a <literal>Makefile</literal>. See <xref - linkend="sec-makefile-dependencies">.</para> + linkend="sec-makefile-dependencies"/>.</para> </listitem> </varlistentry> <varlistentry> <term><cmdsynopsis><command>ghc</command> - <arg choice=plain>––mk-dll</arg></cmdsynopsis></term> + <arg choice='plain'>––mk-dll</arg></cmdsynopsis></term> <indexterm><primary>dependency-generation mode</primary> </indexterm> <listitem> <para>DLL-creation mode (Windows only). See <xref - linkend="win32-dlls-create">.</para> + linkend="win32-dlls-create"/>.</para> </listitem> </varlistentry> </variablelist> @@ -348,7 +348,7 @@ ghc ––make Main.hs you give on the command line will apply to all the source files compiled, so if you want any options to apply to a single source file only, you'll need to use an <literal>OPTIONS</literal> - pragma (see <xref linkend="source-file-options">).</para> + pragma (see <xref linkend="source-file-options"/>).</para> <para>If the program needs to be linked with additional objects (say, some auxilliary C code), then the object files can be @@ -365,7 +365,7 @@ ghc ––make Main.hs <para>The source files for the program don't all need to be in the same directory; the <option>-i</option> option can be used to add directories to the search path (see <xref - linkend="search-path">).</para> + linkend="search-path"/>).</para> </sect2> <sect2 id="eval-mode"> @@ -415,10 +415,10 @@ olleh <informaltable> <tgroup cols="4"> - <colspec align="left"> - <colspec align="left"> - <colspec align="left"> - <colspec align="left"> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="left"/> <thead> <row> @@ -493,15 +493,15 @@ ghc -c Foo.hs</screen> whether a native-code generator<indexterm><primary>native-code generator</primary></indexterm> is used (producing assembly language) or not (producing C). See <xref - linkend="options-codegen"> for more details.</para> + linkend="options-codegen"/> for more details.</para> <para>Note: C pre-processing is optional, the <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm> - flag turns it on. See <xref linkend="c-pre-processor"> for more + flag turns it on. See <xref linkend="c-pre-processor"/> for more details.</para> - <para>Note: The option <option>-E</option><IndexTerm><Primary>-E - option</Primary></IndexTerm> runs just the pre-processing passes + <para>Note: The option <option>-E</option><indexterm><primary>-E + option</primary></indexterm> runs just the pre-processing passes of the compiler, dumping the result in a file. Note that this differs from the previous behaviour of dumping the file to standard output.</para> @@ -511,8 +511,8 @@ ghc -c Foo.hs</screen> <sect1 id="options-help"> <title>Help and verbosity options</title> - <IndexTerm><Primary>help options</Primary></IndexTerm> - <IndexTerm><Primary>verbosity options</Primary></IndexTerm> + <indexterm><primary>help options</primary></indexterm> + <indexterm><primary>verbosity options</primary></indexterm> <variablelist> <varlistentry> @@ -633,7 +633,7 @@ ghc -c Foo.hs</screen> is the value of <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary> </indexterm>in the package configuration file (see <xref - linkend="packages">).</para> + linkend="packages"/>).</para> </listitem> </varlistentry> @@ -662,12 +662,12 @@ ghc -c Foo.hs</screen> simple ways to select standard “packages” of warnings: </para> - <VariableList> + <variablelist> <varlistentry> <term><option>-W</option>:</term> <listitem> - <IndexTerm><Primary>-W option</Primary></IndexTerm> + <indexterm><primary>-W option</primary></indexterm> <para>Provides the standard warnings plus <option>-fwarn-incomplete-patterns</option>, <option>-fwarn-unused-matches</option>, @@ -680,7 +680,7 @@ ghc -c Foo.hs</screen> <varlistentry> <term><option>-w</option>:</term> <listitem> - <IndexTerm><Primary><option>-w</option></Primary></IndexTerm> + <indexterm><primary><option>-w</option></primary></indexterm> <para>Turns off all warnings, including the standard ones.</para> </listitem> </varlistentry> @@ -719,7 +719,7 @@ ghc -c Foo.hs</screen> <para>Causes a warning to be emitted when a deprecated function or type is used. Entities can be marked as deprecated using a pragma, see <xref - linkend="deprecated-pragma">.</para> + linkend="deprecated-pragma"/>.</para> </listitem> </varlistentry> @@ -878,7 +878,7 @@ f (_:xs) = 1 f "2" = 2 </programlisting> - <para>where the last pattern match in <Function>f</Function> + <para>where the last pattern match in <function>f</function> won't ever be reached, as the second pattern overlaps it. More often than not, redundant patterns is a programmer mistake/error, so this option is enabled by default.</para> @@ -900,7 +900,7 @@ f "2" = 2 the monad <literal>fail</literal> operation (monads). For example: <programlisting> f :: [Maybe a] -> [a] - f xs = [y | Just y <- xs] + f xs = [y | Just y <- xs] </programlisting> Switching on <option>-fwarn-simple-patterns</option> will elicit warnings about these probably-innocent cases, which is why the flag is off by default. </para> @@ -921,7 +921,7 @@ f "2" = 2 in. This is useful information when converting code from a context that assumed one default into one with another, e.g., the `default default' for Haskell 1.4 caused the - otherwise unconstrained value <Constant>1</Constant> to be + otherwise unconstrained value <constant>1</constant> to be given the type <literal>Int</literal>, whereas Haskell 98 defaults it to <literal>Integer</literal>. This may lead to differences in performance and behaviour, hence the @@ -974,7 +974,7 @@ f "2" = 2 <para>Report all unused variables which arise from pattern matches, including patterns consisting of a single variable. For instance <literal>f x y = []</literal> would report - <VarName>x</VarName> and <VarName>y</VarName> as unused. The + <varname>x</varname> and <varname>y</varname> as unused. The warning is suppressed if the variable name begins with an underscore, thus: <programlisting> f _x = True @@ -983,7 +983,7 @@ f "2" = 2 </listitem> </varlistentry> - </VariableList> + </variablelist> <para>If you're feeling really paranoid, the <option>-dcore-lint</option> @@ -1159,7 +1159,7 @@ f "2" = 2 <literal>Exception.assert</literal> in source code (in other words, rewriting <literal>Exception.assert p e</literal> to <literal>e</literal> (see <xref - linkend="sec-assertions">). This flag is turned on by + linkend="sec-assertions"/>). This flag is turned on by <option>-O</option>. </para> </listitem> @@ -1197,7 +1197,7 @@ f "2" = 2 unpacked if possible. It is equivalent to adding an <literal>UNPACK</literal> pragma to every strict constructor field (see <xref - linkend="unpack-pragma">).</para> + linkend="unpack-pragma"/>).</para> <para>This option is a bit of a sledgehammer: it might sometimes make things worse. Selectively unboxing fields @@ -1214,9 +1214,9 @@ f "2" = 2 Switching it on makes the compiler a little keener to inline a function that returns a constructor, if the context is that of a thunk. -<ProgramListing> +<programlisting> x = plusInt a b -</ProgramListing> +</programlisting> If we inlined plusInt we might get an opportunity to use update-in-place for the thunk 'x'.</para> </listitem> @@ -1285,7 +1285,7 @@ library documentation).</para> <para> RTS options are provided for modifying the behaviour of the threaded -runtime system. See <XRef LinkEnd="parallel-rts-opts">. +runtime system. See <xref linkend="parallel-rts-opts"/>. </para> <para> @@ -1293,92 +1293,92 @@ Concurrent Haskell is described in more detail in the documentation for the <literal>Control.Concurrent</literal> module. </para> -</Sect1> +</sect1> -<Sect1 id="sec-using-parallel"> -<title>Using Parallel Haskell</title> +<sect1 id="sec-using-parallel"> +<title>Using parallel Haskell</title> <para> -<indexterm><primary>Parallel Haskell—use</primary></indexterm> +<indexterm><primary>parallel Haskell—use</primary></indexterm> </para> <para> [You won't be able to execute parallel Haskell programs unless PVM3 -(Parallel Virtual Machine, version 3) is installed at your site.] -</Para> +(parallel Virtual Machine, version 3) is installed at your site.] +</para> <para> To compile a Haskell program for parallel execution under PVM, use the -<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel -option</Primary></IndexTerm> both when compiling <Emphasis>and -linking</Emphasis>. You will probably want to <Literal>import -Parallel</Literal> into your Haskell modules. -</Para> +<option>-parallel</option> option,<indexterm><primary>-parallel +option</primary></indexterm> both when compiling <emphasis>and +linking</emphasis>. You will probably want to <literal>import +parallel</literal> into your Haskell modules. +</para> <para> To run your parallel program, once PVM is going, just invoke it “as normal”. The main extra RTS option is -<Option>-qp<n></Option>, to say how many PVM +<option>-qp<n></option>, to say how many PVM “processors” your program to run on. (For more details of -all relevant RTS options, please see <XRef -LinkEnd="parallel-rts-opts">.) +all relevant RTS options, please see <xref +linkend="parallel-rts-opts"/>.) </para> <para> -In truth, running Parallel Haskell programs and getting information +In truth, running parallel Haskell programs and getting information out of them (e.g., parallelism profiles) is a battle with the vagaries of PVM, detailed in the following sections. </para> -<Sect2 id="pvm-dummies"> -<Title>Dummy's guide to using PVM</Title> +<sect2 id="pvm-dummies"> +<title>Dummy's guide to using PVM</title> <para> <indexterm><primary>PVM, how to use</primary></indexterm> -<indexterm><primary>Parallel Haskell—PVM use</primary></indexterm> +<indexterm><primary>parallel Haskell—PVM use</primary></indexterm> Before you can run a parallel program under PVM, you must set the required environment variables (PVM's idea, not ours); something like, probably in your <filename>.cshrc</filename> or equivalent: -<ProgramListing> +<programlisting> setenv PVM_ROOT /wherever/you/put/it setenv PVM_ARCH `$PVM_ROOT/lib/pvmgetarch` setenv PVM_DPATH $PVM_ROOT/lib/pvmd -</ProgramListing> +</programlisting> </para> <para> Creating and/or controlling your “parallel machine” is a purely-PVM -business; nothing specific to Parallel Haskell. The following paragraphs +business; nothing specific to parallel Haskell. The following paragraphs describe how to configure your parallel machine interactively. -</Para> +</para> -<Para> +<para> If you use parallel Haskell regularly on the same machine configuration it is a good idea to maintain a file with all machine names and to make the environment variable PVM_HOST_FILE point to this file. Then you can avoid the interactive operations described below by just saying -</Para> +</para> -<ProgramListing> +<programlisting> pvm $PVM_HOST_FILE -</ProgramListing> +</programlisting> -<Para> -You use the <Command>pvm</Command><IndexTerm><Primary>pvm command</Primary></IndexTerm> command to start PVM on your +<para> +You use the <command>pvm</command><indexterm><primary>pvm command</primary></indexterm> command to start PVM on your machine. You can then do various things to control/monitor your “parallel machine;” the most useful being: </para> <para> -<InformalTable> -<TGroup Cols=2> -<ColSpec Align="Left"> -<TBody> +<informaltable> +<tgroup cols="2"> +<colspec align="left"/> +<tbody> <row> -<entry><KeyCombo><KeyCap>Control</KeyCap><KeyCap>D</KeyCap></KeyCombo></entry> +<entry><keycombo><keycap>Control</keycap><keycap>D</keycap></keycombo></entry> <entry>exit <command>pvm</command>, leaving it running</entry> </row> @@ -1417,9 +1417,9 @@ machine. You can then do various things to control/monitor your <entry>status of a particular process</entry> </row> -</TBody> -</TGroup> -</InformalTable> +</tbody> +</tgroup> +</informaltable> </para> <para> @@ -1428,8 +1428,8 @@ The PVM documentation can tell you much, much more about <command>pvm</command>! </sect2> -<Sect2 id="par-profiles"> -<Title>Parallelism profiles</Title> +<sect2 id="par-profiles"> +<title>parallelism profiles</title> <para> <indexterm><primary>parallelism profiles</primary></indexterm> @@ -1438,29 +1438,29 @@ The PVM documentation can tell you much, much more about <command>pvm</command>! </para> <para> -With Parallel Haskell programs, we usually don't care about the +With parallel Haskell programs, we usually don't care about the results—only with “how parallel” it was! We want pretty pictures. </para> -<Para> -Parallelism profiles (à la <Command>hbcpp</Command>) can be generated with the -<Option>-qP</Option><IndexTerm><Primary>-qP RTS option (concurrent, parallel)</Primary></IndexTerm> RTS option. The +<para> +parallelism profiles (à la <command>hbcpp</command>) can be generated with the +<option>-qP</option><indexterm><primary>-qP RTS option (concurrent, parallel)</primary></indexterm> RTS option. The per-processor profiling info is dumped into files named -<Filename><full-path><program>.gr</Filename>. These are then munged into a PostScript picture, +<filename><full-path><program>.gr</filename>. These are then munged into a PostScript picture, which you can then display. For example, to run your program -<Filename>a.out</Filename> on 8 processors, then view the parallelism profile, do: -</Para> +<filename>a.out</filename> on 8 processors, then view the parallelism profile, do: +</para> -<Para> +<para> -<Screen> +<screen> <prompt>$</prompt> ./a.out +RTS -qP -qp8 <prompt>$</prompt> grs2gr *.???.gr > temp.gr # combine the 8 .gr files into one <prompt>$</prompt> gr2ps -O temp.gr # cvt to .ps; output in temp.ps <prompt>$</prompt> ghostview -seascape temp.ps # look at it! -</Screen> +</screen> -</Para> +</para> <para> The scripts for processing the parallelism profiles are distributed @@ -1469,13 +1469,13 @@ in <filename>ghc/utils/parallel/</filename>. </sect2> -<Sect2> -<Title>Other useful info about running parallel programs</Title> +<sect2> +<title>Other useful info about running parallel programs</title> -<Para> +<para> The “garbage-collection statistics” RTS options can be useful for seeing what parallel programs are doing. If you do either -<Option>+RTS -Sstderr</Option><IndexTerm><Primary>-Sstderr RTS option</Primary></IndexTerm> or <Option>+RTS -sstderr</Option>, then +<option>+RTS -Sstderr</option><indexterm><primary>-Sstderr RTS option</primary></indexterm> or <option>+RTS -sstderr</option>, then you'll get mutator, garbage-collection, etc., times on standard error. The standard error of all PE's other than the `main thread' appears in <filename>/tmp/pvml.nnn</filename>, courtesy of PVM. @@ -1488,32 +1488,32 @@ what's happening overall is: <command>tail -f /tmp/pvml.nnn</command>. </sect2> -<Sect2 id="parallel-rts-opts"> -<title>RTS options for Concurrent/Parallel Haskell +<sect2 id="parallel-rts-opts"> +<title>RTS options for Concurrent/parallel Haskell </title> <para> <indexterm><primary>RTS options, concurrent</primary></indexterm> <indexterm><primary>RTS options, parallel</primary></indexterm> <indexterm><primary>Concurrent Haskell—RTS options</primary></indexterm> -<indexterm><primary>Parallel Haskell—RTS options</primary></indexterm> +<indexterm><primary>parallel Haskell—RTS options</primary></indexterm> </para> <para> Besides the usual runtime system (RTS) options -(<XRef LinkEnd="runtime-control">), there are a few options particularly +(<xref linkend="runtime-control"/>), there are a few options particularly for concurrent/parallel execution. </para> <para> -<VariableList> - -<VarListEntry> -<Term><Option>-qp<N></Option>:</Term> -<ListItem> -<Para> -<IndexTerm><Primary>-qp<N> RTS option</Primary></IndexTerm> -(PARALLEL ONLY) Use <Literal><N></Literal> PVM processors to run this program; +<variablelist> + +<varlistentry> +<Term><option>-qp<N></option>:</Term> +<listitem> +<para> +<indexterm><primary>-qp<N> RTS option</primary></indexterm> +(paraLLEL ONLY) Use <literal><N></literal> PVM processors to run this program; the default is 2. </para> </listitem> @@ -1540,93 +1540,93 @@ is the maximum granularity available for timed context switches. <listitem> <para> <indexterm><primary>-q RTS option</primary></indexterm> -(PARALLEL ONLY) Produce a quasi-parallel profile of thread activity, -in the file <FIlename><program>.qp</FIlename>. In the style of <command>hbcpp</command>, this profile +(paraLLEL ONLY) Produce a quasi-parallel profile of thread activity, +in the file <filename><program>.qp</filename>. In the style of <command>hbcpp</command>, this profile records the movement of threads between the green (runnable) and red (blocked) queues. If you specify the verbose suboption (<option>-qv</option>), the green queue is split into green (for the currently running thread only) and amber (for other runnable threads). We do not recommend that you use the verbose suboption if you are planning to use the -<Command>hbcpp</Command> profiling tools or if you are context switching at every heap -check (with <Option>-C</Option>). +<command>hbcpp</command> profiling tools or if you are context switching at every heap +check (with <option>-C</option>). --> -</Para> -</ListItem> -</VarListEntry> -<VarListEntry> -<Term><Option>-qt<num></Option>:</Term> -<ListItem> -<Para> -<IndexTerm><Primary>-qt<num> RTS option</Primary></IndexTerm> -(PARALLEL ONLY) Limit the thread pool size, i.e. the number of concurrent -threads per processor to <Literal><num></Literal>. The default is -32. Each thread requires slightly over 1K <Emphasis>words</Emphasis> in +</para> +</listitem> +</varlistentry> +<varlistentry> +<Term><option>-qt<num></option>:</Term> +<listitem> +<para> +<indexterm><primary>-qt<num> RTS option</primary></indexterm> +(paraLLEL ONLY) Limit the thread pool size, i.e. the number of concurrent +threads per processor to <literal><num></literal>. The default is +32. Each thread requires slightly over 1K <emphasis>words</emphasis> in the heap for thread state and stack objects. (For 32-bit machines, this translates to 4K bytes, and for 64-bit machines, 8K bytes.) -</Para> -</ListItem> -</VarListEntry> +</para> +</listitem> +</varlistentry> <!-- no more -HWL -<VarListEntry> -<Term><Option>-d</Option>:</Term> -<ListItem> -<Para> -<IndexTerm><Primary>-d RTS option (parallel)</Primary></IndexTerm> -(PARALLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or -something…) per PVM processor. We use the standard <Command>debugger</Command> +<varlistentry> +<Term><option>-d</option>:</Term> +<listitem> +<para> +<indexterm><primary>-d RTS option (parallel)</primary></indexterm> +(paraLLEL ONLY) Turn on debugging. It pops up one xterm (or GDB, or +something…) per PVM processor. We use the standard <command>debugger</command> script that comes with PVM3, but we sometimes meddle with the -<Command>debugger2</Command> script. We include ours in the GHC distribution, -in <Filename>ghc/utils/pvm/</Filename>. -</Para> -</ListItem> -</VarListEntry> +<command>debugger2</command> script. We include ours in the GHC distribution, +in <filename>ghc/utils/pvm/</filename>. +</para> +</listitem> +</varlistentry> --> -<VarListEntry> -<Term><Option>-qe<num></Option>:</Term> -<ListItem> -<Para> -<IndexTerm><Primary>-qe<num> RTS option -(parallel)</Primary></IndexTerm> (PARALLEL ONLY) Limit the spark pool size +<varlistentry> +<Term><option>-qe<num></option>:</Term> +<listitem> +<para> +<indexterm><primary>-qe<num> RTS option +(parallel)</primary></indexterm> (paraLLEL ONLY) Limit the spark pool size i.e. the number of pending sparks per processor to -<Literal><num></Literal>. The default is 100. A larger number may be +<literal><num></literal>. The default is 100. A larger number may be appropriate if your program generates large amounts of parallelism initially. -</Para> -</ListItem> -</VarListEntry> -<VarListEntry> -<Term><Option>-qQ<num></Option>:</Term> -<ListItem> -<Para> -<IndexTerm><Primary>-qQ<num> RTS option (parallel)</Primary></IndexTerm> -(PARALLEL ONLY) Set the size of packets transmitted between processors -to <Literal><num></Literal>. The default is 1024 words. A larger number may be +</para> +</listitem> +</varlistentry> +<varlistentry> +<Term><option>-qQ<num></option>:</Term> +<listitem> +<para> +<indexterm><primary>-qQ<num> RTS option (parallel)</primary></indexterm> +(paraLLEL ONLY) Set the size of packets transmitted between processors +to <literal><num></literal>. The default is 1024 words. A larger number may be appropriate if your machine has a high communication cost relative to computation speed. -</Para> -</ListItem> -</VarListEntry> -<VarListEntry> -<Term><Option>-qh<num></Option>:</Term> -<ListItem> -<Para> -<IndexTerm><Primary>-qh<num> RTS option (parallel)</Primary></IndexTerm> -(PARALLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to +</para> +</listitem> +</varlistentry> +<varlistentry> +<Term><option>-qh<num></option>:</Term> +<listitem> +<para> +<indexterm><primary>-qh<num> RTS option (parallel)</primary></indexterm> +(paraLLEL ONLY) Select a packing scheme. Set the number of non-root thunks to pack in one packet to <num>-1 (0 means infinity). By default GUM uses full-subgraph packing, i.e. the entire subgraph with the requested closure as root is transmitted (provided it fits into one packet). Choosing a smaller value reduces the amount of pre-fetching of work done in GUM. This can be advantageous for improving data locality but it can also worsen the balance of the load in the system. -</Para> -</ListItem> -</VarListEntry> -<VarListEntry> -<Term><Option>-qg<num></Option>:</Term> -<ListItem> -<Para> -<IndexTerm><Primary>-qg<num> RTS option -(parallel)</Primary></IndexTerm> (PARALLEL ONLY) Select a globalisation +</para> +</listitem> +</varlistentry> +<varlistentry> +<Term><option>-qg<num></option>:</Term> +<listitem> +<para> +<indexterm><primary>-qg<num> RTS option +(parallel)</primary></indexterm> (paraLLEL ONLY) Select a globalisation scheme. This option affects the generation of global addresses when transferring data. Global addresses are globally unique identifiers required to maintain sharing in the distributed @@ -1636,15 +1636,15 @@ is transmitted. With <num>=1 a thunk-only globalisation scheme is used, which generated global address only for thunks. The latter case may lose sharing of data but has a reduced overhead in packing graph structures and maintaining internal tables of global addresses. -</Para> -</ListItem> -</VarListEntry> -</VariableList> +</para> +</listitem> +</varlistentry> +</variablelist> </para> </sect2> -</Sect1> +</sect1> <sect1 id="options-platform"> <title>Platform-specific Flags</title> @@ -1680,11 +1680,11 @@ and maintaining internal tables of global addresses. compiling some modules with four stolen registers, it will crash, probably saying: -<Screen> +<screen> Foo.hc:533: fixed or forbidden register was spilled. This may be due to a compiler bug or to impossible asm statements or clauses. -</Screen> +</screen> Just give some registers back with <option>-monly-N-regs</option>. Try `3' first, then `2'. @@ -1705,18 +1705,18 @@ statements or clauses. <para>GHC can dump its optimized intermediate code (said to be in “Core” format) to a file as a side-effect of compilation. Core files, which are given the suffix <filename>.hcr</filename>, can be read and processed by non-GHC back-end - tools. The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz" + tools. The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz"> <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>, and sample tools (in Haskell) for manipulating Core files are available in the GHC source distribution directory <literal>/fptools/ghc/utils/ext-core</literal>. Note that the format of <literal>.hcr</literal> files is <emphasis>different</emphasis> (though similar) to the Core output format generated - for debugging purposes (<xref linkend="options-debugging">).</para> + for debugging purposes (<xref linkend="options-debugging"/>).</para> <para>The Core format natively supports notes which you can add to your source code using the <literal>CORE</literal> pragma (see <xref - linkend="pragmas">).</para> + linkend="pragmas"/>).</para> <variablelist> @@ -1741,7 +1741,7 @@ ordinary Haskell 98, when translated to External Core, uses things like rank-2 t &debug; &flags; -</Chapter> +</chapter> <!-- Emacs stuff: ;;; Local Variables: *** diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml index 8d75b382d2..14e614ee0a 100644 --- a/ghc/docs/users_guide/utils.sgml +++ b/ghc/docs/users_guide/utils.sgml @@ -92,9 +92,9 @@ tags: corresponding type constructor instead.</para> <para>Actually, GHC also comes with <command>etags</command> - [for C], and <Command>perltags</Command> [for You + [for C], and <command>perltags</command> [for You Know What]. And—I cannot tell a lie—there is - Denis Howe's <Command>fptags</Command> [for Haskell, + Denis Howe's <command>fptags</command> [for Haskell, etc.] in the <Filename>ghc/CONTRIB</Filename> section…)</para> @@ -110,11 +110,11 @@ tags: <para>Andy Gill and Simon Marlow have written a parser-generator for Haskell, called - <Command>happy</Command>.<IndexTerm><Primary>happy parser - generator</Primary></IndexTerm> <command>Happy</command> is to + <command>happy</command>.<indexterm><primary>happy parser + generator</primary></indexterm> <command>Happy</command> is to Haskell what <command>Yacc</command> is to C.</para> - <para>You can get <Command>happy</Command> from <ulink + <para>You can get <command>happy</command> from <ulink url="http://www.haskell.org/happy/">the Happy Homepage</ulink>.</para> @@ -125,13 +125,13 @@ tags: <!-- we don't distribute this anymore <sect1 id="pphs"> - <title>Pretty-printing Haskell: <Command>pphs</Command></title> + <title>Pretty-printing Haskell: <command>pphs</command></title> <indexterm><primary>pphs</primary></indexterm> <indexterm><primary>pretty-printing Haskell code</primary></indexterm> <para>Andrew Preece has written - <Command>pphs</Command>,<IndexTerm><Primary>pphs</Primary></IndexTerm><IndexTerm><Primary>pretty-printing - Haskell</Primary></IndexTerm> a utility to pretty-print Haskell + <command>pphs</command>,<indexterm><primary>pphs</primary></indexterm><indexterm><primary>pretty-printing + Haskell</primary></indexterm> 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 @@ -177,7 +177,7 @@ tags: header file.</para> <sect2> - <title>Command line syntax</title> + <title>command line syntax</title> <para><command>hsc2hs</command> takes input files as arguments, and flags that modify its behavior:</para> @@ -288,7 +288,7 @@ tags: <literal>.hsc</literal> suffix replaced:</para> <informaltable> - <tgroup cols=2> + <tgroup cols="2"> <tbody> <row> <entry><literal>.hs</literal></entry> @@ -397,7 +397,7 @@ tags: in which case you must arrange for the importing module to <literal>#include</literal> the C header file generated by <command>hsc2hs</command> (see - <xref linkend="glasgow-foreign-headers">). + <xref linkend="glasgow-foreign-headers"/>). For this reason we avoid using <literal>#def</literal> in the libraries.</para></note> </listitem> diff --git a/ghc/docs/users_guide/win32-dlls.sgml b/ghc/docs/users_guide/win32-dlls.sgml index cdaad9cd60..0cb8b226eb 100644 --- a/ghc/docs/users_guide/win32-dlls.sgml +++ b/ghc/docs/users_guide/win32-dlls.sgml @@ -112,7 +112,7 @@ make-sessions running under cygwin. <sect2><title>Things to do</title> <itemizedlist> <listitem> -<para> Don't use absolute paths in make, configure & co if there is any chance +<para> Don't use absolute paths in make, configure & co if there is any chance that those might be passed to GHC (or to GHC-compiled programs). Relative paths are fine because cygwin tools are happy with them and GHC accepts '/' as path-separator. And relative paths don't depend on where cygwin's @@ -155,38 +155,37 @@ make-sessions running under cygwin. <sect1 id="win32-dlls"> -<Title>Building and using Win32 DLLs -</Title> +<title>Building and using Win32 DLLs +</title> -<Para> -<IndexTerm><Primary>Dynamic link libraries, Win32</Primary></IndexTerm> -<IndexTerm><Primary>DLLs, Win32</Primary></IndexTerm> +<para> +<indexterm><primary>Dynamic link libraries, Win32</primary></indexterm> +<indexterm><primary>DLLs, Win32</primary></indexterm> On Win32 platforms, the compiler is capable of both producing and using dynamic link libraries (DLLs) containing ghc-compiled code. This section shows you how to make use of this facility. -</Para> +</para> -<Para> -Until recently, <Command>strip</Command> didn't work reliably on DLLs, so you +<para> +Until recently, <command>strip</command> didn't work reliably on DLLs, so you should test your version with care, or make sure you have the latest binutils. Unfortunately, we don't know exactly which version of binutils cured the problem (it was supposedly fixed some years ago). -</Para> +</para> -<Sect2 id="win32-dlls-link"> -<Title>Linking with DLLs -</Title> +<sect2 id="win32-dlls-link"> +<title>Linking with DLLs</title> -<Para> +<para> The default on Win32 platforms is to link applications in such a way that the executables will use the Prelude and system libraries DLLs, rather than contain (large chunks of) them. This is transparent at the command-line, so -</Para> +</para> -<Para> -<Screen> +<para> +<screen> sh$ cat main.hs module Main where main = putStrLn "hello, world!" @@ -198,199 +197,198 @@ sh$ ls -l main.exe sh$ ./main hello, world! sh$ -</Screen> -</Para> +</screen> +</para> -<Para> -will give you a binary as before, but the <Filename>main.exe</Filename> +<para> +will give you a binary as before, but the <filename>main.exe</filename> generated will use the Prelude and RTS DLLs instead of linking them in statically. -</Para> +</para> -<Para> -4K for a <Literal>"hello, world"</Literal> application—not bad, huh? :-) -</Para> +<para> +4K for a <literal>"hello, world"</literal> application—not bad, huh? :-) +</para> -</Sect2> +</sect2> -<Sect2 id="win32-dlls-linking-static"> -<Title>Not linking with DLLs -<IndexTerm><Primary>-static option (Win32)</Primary></IndexTerm></Title> +<sect2 id="win32-dlls-linking-static"> +<title>Not linking with DLLs +<indexterm><primary>-static option (Win32)</primary></indexterm></title> -<Para> +<para> If you want to build an executable that doesn't depend on any -ghc-compiled DLLs, use the <Option>-static</Option> option to link in +ghc-compiled DLLs, use the <option>-static</option> option to link in the code statically. -</Para> +</para> -<Para> +<para> Notice that you cannot mix code that has been compiled with -<Option>-static</Option> and not, so you have to use the <Option>-static</Option> +<option>-static</option> and not, so you have to use the <option>-static</option> option on all the Haskell modules that make up your application. -</Para> +</para> -</Sect2> +</sect2> -<Sect2 id="win32-dlls-create"> -<Title>Creating a DLL -</Title> +<sect2 id="win32-dlls-create"> +<title>Creating a DLL</title> -<Para> +<para> <emphasis>Making libraries into DLLs doesn't work on Windows at the moment (and is no longer supported); however, all the machinery is still there. If you're interested, contact the GHC team. Note that building an entire Haskell application as a DLL is still supported (it's just inter-DLL Haskell calls that don't work).</emphasis> -<IndexTerm><Primary>Creating a Win32 DLL</Primary></IndexTerm> -<IndexTerm><Primary>––mk-dll</Primary></IndexTerm> +<indexterm><primary>Creating a Win32 DLL</primary></indexterm> +<indexterm><primary>––mk-dll</primary></indexterm> Sealing up your Haskell library inside a DLL is straightforward; compile up the object files that make up the library, and then build the DLL by issuing a command of the form: -</Para> +</para> -<Para> -<Screen> +<para> +<screen> ghc ––mk-dll -o foo.dll bar.o baz.o wibble.a -lfooble -</Screen> -</Para> +</screen> +</para> -<Para> -By feeding the ghc compiler driver the option <Option>––mk-dll</Option>, it +<para> +By feeding the ghc compiler driver the option <option>––mk-dll</option>, it will build a DLL rather than produce an executable. The DLL will consist of all the object files and archives given on the command line. -</Para> +</para> -<Para> +<para> To create a `static' DLL, i.e. one that does not depend on the GHC DLLs, -use the <Option>-static</Option> when compiling up your Haskell code and +use the <option>-static</option> when compiling up your Haskell code and building the DLL. -</Para> +</para> -<Para> +<para> A couple of things to notice: -</Para> +</para> -<Para> +<para> -<ItemizedList> -<ListItem> -<Para> -Since DLLs correspond to packages (see <XRef LinkEnd="packages">) you need -to use <Option>-package-name dll-name</Option> when compiling modules that +<itemizedlist> +<listitem> +<para> +Since DLLs correspond to packages (see <xref linkend="packages"/>) you need +to use <option>-package-name dll-name</option> when compiling modules that belong to a DLL if you're going to call them from Haskell. Otherwise, Haskell code that calls entry points in that DLL will do so incorrectly, and crash. For similar reasons, you can only compile a single module tree into a DLL, -as <Function>startupHaskell</Function> needs to be able to call its -initialisation function, and only takes one such argument (see <XRef -LinkEnd="win32-dlls-foreign">). Hence the modules +as <function>startupHaskell</function> needs to be able to call its +initialisation function, and only takes one such argument (see <xref +linkend="win32-dlls-foreign"/>). Hence the modules you compile into a DLL must have a common root. -</Para> -</ListItem> +</para> +</listitem> -<ListItem> -<Para> +<listitem> +<para> By default, the entry points of all the object files will be exported from -the DLL when using <Option>––mk-dll</Option>. Should you want to constrain -this, you can specify the <Emphasis>module definition file</Emphasis> to use +the DLL when using <option>––mk-dll</option>. Should you want to constrain +this, you can specify the <emphasis>module definition file</emphasis> to use on the command line as follows: -<Screen> +<screen> ghc ––mk-dll -o .... -optdll--def -optdllMyDef.def -</Screen> +</screen> See Microsoft documentation for details, but a module definition file simply lists what entry points you want to export. Here's one that's suitable when building a Haskell COM server DLL: -<ProgramListing> +<programlisting> EXPORTS DllCanUnloadNow = DllCanUnloadNow@0 DllGetClassObject = DllGetClassObject@12 DllRegisterServer = DllRegisterServer@0 DllUnregisterServer = DllUnregisterServer@0 -</ProgramListing> -</Para> -</ListItem> +</programlisting> +</para> +</listitem> -<ListItem> -<Para> -In addition to creating a DLL, the <Option>––mk-dll</Option> option also +<listitem> +<para> +In addition to creating a DLL, the <option>––mk-dll</option> option also creates an import library. The import library name is derived from the name of the DLL, as follows: -<ProgramListing> +<programlisting> DLL: HScool.dll ==> import lib: libHScool_imp.a -</ProgramListing> +</programlisting> The naming scheme may look a bit weird, but it has the purpose of allowing the co-existence of import libraries with ordinary static libraries (e.g., -<Filename>libHSfoo.a</Filename> and -<Filename>libHSfoo_imp.a</Filename>. +<filename>libHSfoo.a</filename> and +<filename>libHSfoo_imp.a</filename>. Additionally, when the compiler driver is linking in non-static mode, it -will rewrite occurrence of <Option>-lHSfoo</Option> on the command line to -<Option>-lHSfoo_imp</Option>. By doing this for you, switching from +will rewrite occurrence of <option>-lHSfoo</option> on the command line to +<option>-lHSfoo_imp</option>. By doing this for you, switching from non-static to static linking is simply a question of adding -<Option>-static</Option> to your command line. +<option>-static</option> to your command line. -</Para> -</ListItem> -</ItemizedList> -</Para> +</para> +</listitem> +</itemizedlist> +</para> -</Sect2> +</sect2> -<Sect2 id="win32-dlls-foreign"> -<Title>Making DLLs to be called from other languages</Title> +<sect2 id="win32-dlls-foreign"> +<title>Making DLLs to be called from other languages</title> -<Para> +<para> If you want to package up Haskell code to be called from other languages, such as Visual Basic or C++, there are some extra things it is useful to -know. The dirty details are in the <Emphasis>Foreign Function -Interface</Emphasis> definition, but it can be tricky to work out how to +know. The dirty details are in the <emphasis>Foreign Function +Interface</emphasis> definition, but it can be tricky to work out how to combine this with DLL building, so here's an example: -</Para> +</para> -<ItemizedList> +<itemizedlist> -<ListItem> -<Para> -Use <Literal>foreign export</Literal> declarations to export the Haskell +<listitem> +<para> +Use <literal>foreign export</literal> declarations to export the Haskell functions you want to call from the outside. For example, -<ProgramListing> +<programlisting> module Adder where adder :: Int -> Int -> IO Int -- gratuitous use of IO adder x y = return (x+y) foreign export stdcall adder :: Int -> Int -> IO Int -</ProgramListing> -</Para> -</ListItem> +</programlisting> +</para> +</listitem> -<ListItem> -<Para> +<listitem> +<para> Compile it up: -<Screen> +<screen> ghc -c adder.hs -fglasgow-exts -</Screen> +</screen> This will produce two files, adder.o and adder_stub.o -</Para> -</ListItem> +</para> +</listitem> -<ListItem> -<Para> -compile up a <Function>DllMain()</Function> that starts up the Haskell +<listitem> +<para> +compile up a <function>DllMain()</function> that starts up the Haskell RTS-––a possible implementation is: -<ProgramListing> +<programlisting> #include <windows.h> #include <Rts.h> @@ -413,59 +411,59 @@ DllMain } return TRUE; } -</ProgramListing> +</programlisting> -Here, <Literal>Adder</Literal> is the name of the root module in the module +Here, <literal>Adder</literal> is the name of the root module in the module tree (as mentioned above, there must be a single root module, and hence a single module tree in the DLL). Compile this up: -<Screen> +<screen> ghc -c dllMain.c -</Screen> -</Para> -</ListItem> +</screen> +</para> +</listitem> -<ListItem> -<Para> +<listitem> +<para> Construct the DLL: -<Screen> +<screen> ghc ––mk-dll -o adder.dll adder.o adder_stub.o dllMain.o -</Screen> +</screen> -</Para> -</ListItem> +</para> +</listitem> -<ListItem> -<Para> -Start using <Function>adder</Function> from VBA-––here's how I would -<Constant>Declare</Constant> it: +<listitem> +<para> +Start using <function>adder</function> from VBA-––here's how I would +<constant>Declare</constant> it: -<ProgramListing> +<programlisting> Private Declare Function adder Lib "adder.dll" Alias "adder@8" (ByVal x As Long, ByVal y As Long) As Long -</ProgramListing> +</programlisting> Since this Haskell DLL depends on a couple of the DLLs that come with GHC, make sure that they are in scope/visible. -</Para> +</para> -<Para> +<para> Building statically linked DLLs is the same as in the previous section: it -suffices to add <Option>-static</Option> to the commands used to compile up +suffices to add <option>-static</option> to the commands used to compile up the Haskell source and build the DLL. -</Para> +</para> -</ListItem> +</listitem> -</ItemizedList> +</itemizedlist> -</Sect2> +</sect2> </sect1> -</Chapter> +</chapter> <!-- Emacs stuff: ;;; Local Variables: *** |