Commit 2dfd5072 authored by krasimir's avatar krasimir

[project @ 2004-08-08 17:26:26 by krasimir]

xmlize sgml docbooks
parent dc801dc2
......@@ -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>
......
<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&nbsp;98. See also the &ldquo;when things
go wrong&rdquo; section (<XRef LinkEnd="wrong">) for information
go wrong&rdquo; 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 &amp; 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
......
......@@ -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&hellip;</para>
<ProgramListing>
<programlisting>
Desugared:
Main.skip2{-r1L6-} :: _forall_ a$_4 =&#62;{{Num a$_4}} -&#62; a$_4 -&#62; [a$_4]
......@@ -473,7 +473,7 @@ Main.skip2{-r1L6-} =
{- end CoRec -}
} in skip2.t3Ja
</ProgramListing>
</programlisting>
<para>(&ldquo;It's just a simple functional language&rdquo; 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: ***
......
......@@ -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
&ldquo;stack trace&rdquo; 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 &amp;- hGetLine
...</programlisting>
<para>You'll probably find that the behaviour differs when
......@@ -426,7 +426,7 @@ details.</para>
Include files named by <option>-&num;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>
......
<!-- 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 &lt; 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>-&num;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>-&num;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>-&num;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: ***
......
......@@ -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 &amp; 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>
......
......@@ -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>&ndash;&ndash;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 &amp; C:</para>
<screen>
A
/ \
......@@ -522,12 +522,12 @@ Prelude,IO>
<para>Here's an example:</para>
<screen>
Prelude> x <- return 42
Prelude> x &lt;- return 42
Prelude> print x
42
Prelude>
</screen>
<para>The statement <literal>x <- return 42</literal> means
<para>The statement <literal>x &lt;- return 42</literal> means
&ldquo;execute <literal>return 42</literal> in the
<literal>IO</literal> monad, and bind the result to
<literal>x</literal>&rdquo;. 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 &lt;- e</literal>)