Move user's guide to ReStructuredText
authorBen Gamari <ben@smart-cactus.org>
Wed, 30 Sep 2015 23:08:41 +0000 (01:08 +0200)
committerBen Gamari <ben@smart-cactus.org>
Sat, 3 Oct 2015 07:44:48 +0000 (09:44 +0200)
131 files changed:
.gitignore
.travis.yml
INSTALL.md
README.md
aclocal.m4
configure.ac
docs/man/gen_flags.xsl.sh [deleted file]
docs/man/ghc.mk [deleted file]
docs/users_guide/7.12.1-notes.rst [new file with mode: 0644]
docs/users_guide/7.12.1-notes.xml [deleted file]
docs/users_guide/bugs.rst [new file with mode: 0644]
docs/users_guide/bugs.xml [deleted file]
docs/users_guide/codegens.rst [new file with mode: 0644]
docs/users_guide/codegens.xml [deleted file]
docs/users_guide/conf.py [new file with mode: 0644]
docs/users_guide/debugging.rst [new file with mode: 0644]
docs/users_guide/debugging.xml [deleted file]
docs/users_guide/editing-guide.rst [new file with mode: 0644]
docs/users_guide/extending_ghc.rst [new file with mode: 0644]
docs/users_guide/extending_ghc.xml [deleted file]
docs/users_guide/ffi-chap.rst [new file with mode: 0644]
docs/users_guide/ffi-chap.xml [deleted file]
docs/users_guide/flags.rst [new file with mode: 0644]
docs/users_guide/flags.xml [deleted file]
docs/users_guide/ghc-theme/layout.html [new file with mode: 0644]
docs/users_guide/ghc-theme/static/ghc-theme.css [new file with mode: 0644]
docs/users_guide/ghc-theme/theme.conf [new file with mode: 0644]
docs/users_guide/ghc.mk
docs/users_guide/ghc.rst [new file with mode: 0644]
docs/users_guide/ghc_config.py.in [new file with mode: 0644]
docs/users_guide/ghci.rst [new file with mode: 0644]
docs/users_guide/ghci.xml [deleted file]
docs/users_guide/glasgow_exts.rst [new file with mode: 0644]
docs/users_guide/glasgow_exts.xml [deleted file]
docs/users_guide/gone_wrong.rst [new file with mode: 0644]
docs/users_guide/gone_wrong.xml [deleted file]
docs/users_guide/images/logo.pdf [new file with mode: 0644]
docs/users_guide/images/prof_scc.pdf [new file with mode: 0644]
docs/users_guide/images/prof_scc.svg [new file with mode: 0644]
docs/users_guide/index.rst [new file with mode: 0644]
docs/users_guide/intro.rst [new file with mode: 0644]
docs/users_guide/intro.xml [deleted file]
docs/users_guide/lang.rst [new file with mode: 0644]
docs/users_guide/lang.xml [deleted file]
docs/users_guide/license.rst [new file with mode: 0644]
docs/users_guide/license.xml [deleted file]
docs/users_guide/packages.rst [new file with mode: 0644]
docs/users_guide/packages.xml [deleted file]
docs/users_guide/parallel.rst [new file with mode: 0644]
docs/users_guide/parallel.xml [deleted file]
docs/users_guide/phases.rst [new file with mode: 0644]
docs/users_guide/phases.xml [deleted file]
docs/users_guide/prof_scc.eps [deleted file]
docs/users_guide/profiling.rst [new file with mode: 0644]
docs/users_guide/profiling.xml [deleted file]
docs/users_guide/runghc.rst [new file with mode: 0644]
docs/users_guide/runghc.xml [deleted file]
docs/users_guide/runtime_control.rst [new file with mode: 0644]
docs/users_guide/runtime_control.xml [deleted file]
docs/users_guide/safe_haskell.rst [new file with mode: 0644]
docs/users_guide/safe_haskell.xml [deleted file]
docs/users_guide/separate_compilation.rst [new file with mode: 0644]
docs/users_guide/separate_compilation.xml [deleted file]
docs/users_guide/shared_libs.rst [new file with mode: 0644]
docs/users_guide/shared_libs.xml [deleted file]
docs/users_guide/sooner.rst [new file with mode: 0644]
docs/users_guide/sooner.xml [deleted file]
docs/users_guide/ug-book.xml.in [deleted file]
docs/users_guide/ug-ent.xml.in [deleted file]
docs/users_guide/usage.rst [new file with mode: 0644]
docs/users_guide/using-concurrent.rst [new file with mode: 0644]
docs/users_guide/using-optimisation.rst [new file with mode: 0644]
docs/users_guide/using-warnings.rst [new file with mode: 0644]
docs/users_guide/using.rst [new file with mode: 0644]
docs/users_guide/using.xml [deleted file]
docs/users_guide/utils.rst [new file with mode: 0644]
docs/users_guide/utils.xml [deleted file]
docs/users_guide/win32-dlls.rst [new file with mode: 0644]
docs/users_guide/win32-dlls.xml [deleted file]
ghc.mk
mk/config.mk.in
mk/flavours/bench-cross.mk
mk/flavours/bench-llvm.mk
mk/flavours/bench.mk
mk/flavours/devel1.mk
mk/flavours/devel2.mk
mk/flavours/perf-cross.mk
mk/flavours/perf-llvm.mk
mk/flavours/perf.mk
mk/flavours/prof.mk
mk/flavours/quick-cross.mk
mk/flavours/quick-llvm.mk
mk/flavours/quick.mk
mk/flavours/quickest.mk
mk/flavours/validate.mk
rules/docbook.mk [deleted file]
rules/sphinx.mk [new file with mode: 0644]
utils/mkUserGuidePart/DList.hs [new file with mode: 0644]
utils/mkUserGuidePart/Main.hs
utils/mkUserGuidePart/Options.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/CodeGen.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/CompilerDebugging.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Cpp.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/FindingImports.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Interactive.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/InterfaceFiles.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/KeepingIntermediates.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Language.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Linking.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Misc.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Modes.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/OptimizationLevels.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Optimizations.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Packages.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/PhasePrograms.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/PhaseSpecific.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Phases.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/PlatformSpecific.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Plugin.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Profiling.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/ProgramCoverage.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/RecompilationChecking.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/RedirectingOutput.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/TemporaryFiles.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Verbosity.hs [new file with mode: 0644]
utils/mkUserGuidePart/Options/Warnings.hs [new file with mode: 0644]
utils/mkUserGuidePart/Table.hs [new file with mode: 0644]
utils/mkUserGuidePart/Types.hs [new file with mode: 0644]
utils/mkUserGuidePart/ghc.mk
utils/mkUserGuidePart/mkUserGuidePart.cabal
utils/vagrant/bootstrap-rhel.sh

index bb4a293..48ab194 100644 (file)
@@ -39,8 +39,6 @@ configure
 
 # Temporarily generated configure files
 confdefs.h
-conftest-book.xml
-conftest.xml
 
 # -----------------------------------------------------------------------------
 # Ignore any overlapped darcs repos and back up files
@@ -89,16 +87,14 @@ _darcs/
 /distrib/configure.ac
 /distrib/ghc.iss
 /docs/index.html
-/docs/man/flags.xml
-/docs/man/flags.xsl
-/docs/man/ghc.1
-/docs/users_guide/ug-book.xml
-/docs/users_guide/ug-ent.xml
-/docs/users_guide/users_guide.xml
+/docs/users_guide/ghc.1
+/docs/users_guide/*.gen.rst
+/docs/users_guide/ghc_config.py
+/docs/users_guide/ghc_config.pyc
 /docs/users_guide/users_guide.pdf
-/docs/users_guide/users_guide.ps
-/docs/users_guide/users_guide/
-/docs/users_guide/what_glasgow_exts_does.gen.xml
+/docs/users_guide/build-html
+/docs/users_guide/build-pdf
+/docs/users_guide/.doctrees
 /driver/ghci/ghc-pkg-inplace
 /driver/ghci/ghci-inplace
 /driver/ghci/ghci.res
index 3a9d337..2974b81 100644 (file)
@@ -41,9 +41,8 @@ before_install:
 script:
  # do  not build docs
  - echo 'HADDOCK_DOCS       = NO' >> mk/validate.mk
- - echo 'BUILD_DOCBOOK_HTML = NO' >> mk/validate.mk
- - echo 'BUILD_DOCBOOK_PS   = NO' >> mk/validate.mk
- - echo 'BUILD_DOCBOOK_PDF  = NO' >> mk/validate.mk
+ - echo 'BUILD_SPHINX_HTML  = NO' >> mk/validate.mk
+ - echo 'BUILD_SPHINX_PDF   = NO' >> mk/validate.mk
  # do not build dynamic libraries
  - echo 'DYNAMIC_GHC_PROGRAMS = NO' >> mk/validate.mk
  - echo 'GhcLibWays = v' >> mk/validate.mk
index 58930af..34bb5b4 100644 (file)
@@ -13,8 +13,8 @@ because the compiler is itself written in Haskell.  For instructions
 on how to port GHC to a new platform, see the Building Guide [1].
 
 For building library documentation, you'll need Haddock [3].  To build
-the compiler documentation, you need a good DocBook XML toolchain and
-dblatex.
+the compiler documentation, you need [Sphinx](http://www.sphinx-doc.org/) and
+Xelatex (only for PDF output).
 
 Quick start:  the following gives you a default build:
 
index 025140c..227657f 100644 (file)
--- a/README.md
+++ b/README.md
@@ -51,8 +51,8 @@ because the compiler is itself written in Haskell.  You also need
 to port GHC to a new platform, see the [GHC Building Guide] [3].
 
 For building library documentation, you'll need [Haddock] [6].  To build
-the compiler documentation, you need a good DocBook XML toolchain and
-dblatex.
+the compiler documentation, you need [Sphinx](http://www.sphinx-doc.org/)
+and Xelatex (only for PDF output).
 
 **Quick start**: the following gives you a default build:
 
index 2f4d516..0c2633a 100644 (file)
@@ -1373,124 +1373,6 @@ AS_IF([test AS_VAR_GET(fp_func) = yes],
 AS_VAR_POPDEF([fp_func])dnl
 ])# FP_CHECK_FUNC
 
-
-# FP_GEN_DOCBOOK_XML
-# ------------------
-# Generates a DocBook XML V4.5 document in conftest.xml.
-#
-# It took a lot of experimentation to find a document that will cause
-# xsltproc to fail with an error code when the relevant
-# stylesheets/DTDs are not found.  I couldn't make xsltproc fail with
-# a single-file document, it seems a multi-file document is needed.
-# -- SDM 2009-06-03
-#
-AC_DEFUN([FP_GEN_DOCBOOK_XML],
-[rm -f conftest.xml conftest-book.xml
-cat > conftest.xml << EOF
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [[
-<!ENTITY conftest-book SYSTEM "conftest-book.xml">
-]]>
-<book id="test">
-&conftest-book;
-</book>
-EOF
-cat >conftest-book.xml << EOF
-<?xml version="1.0" encoding="iso-8859-1"?>
-  <title>A DocBook &ldquo;Test Document&rdquo;</title>
-  <chapter id="id-one">
-    <title>A Chapter Title</title>
-    <para>This is a paragraph, referencing <xref linkend="id-two"/>.</para>
-  </chapter>
-  <chapter id="id-two">
-    <title>Another Chapter Title</title>
-    <para>This is another paragraph, referencing <xref linkend="id-one"/>.</para>
-  </chapter>
-EOF
-]) # FP_GEN_DOCBOOK_XML
-
-
-# FP_PROG_DBLATEX
-# ----------------
-# Sets the output variable DblatexCmd to the full path of dblatex,
-# which we use for building PDF and PS docs.
-# DblatexCmd is empty if dblatex could not be found.
-AC_DEFUN([FP_PROG_DBLATEX],
-[AC_PATH_PROG([DblatexCmd], [dblatex])
-if test -z "$DblatexCmd"; then
-  AC_MSG_WARN([cannot find dblatex in your PATH, you will not be able to build the PDF and PS documentation])
-fi
-])# FP_PROG_DBLATEX
-
-
-# FP_PROG_XSLTPROC
-# ----------------
-# Sets the output variable XsltprocCmd to the full path of the XSLT processor
-# xsltproc. XsltprocCmd is empty if xsltproc could not be found.
-AC_DEFUN([FP_PROG_XSLTPROC],
-[AC_PATH_PROG([XsltprocCmd], [xsltproc])
-if test -z "$XsltprocCmd"; then
-  AC_MSG_WARN([cannot find xsltproc in your PATH, you will not be able to build the HTML documentation])
-fi
-])# FP_PROG_XSLTPROC
-
-
-# FP_DOCBOOK_XSL
-# ----------------------------
-# Check that we can process a DocBook XML document to HTML using xsltproc.
-AC_DEFUN([FP_DOCBOOK_XSL],
-[AC_REQUIRE([FP_PROG_XSLTPROC])dnl
-if test -n "$XsltprocCmd"; then
-  AC_CACHE_CHECK([for DocBook XSL stylesheet], fp_cv_dir_docbook_xsl,
-  [FP_GEN_DOCBOOK_XML
-  fp_cv_dir_docbook_xsl=no
-  if $XsltprocCmd --nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl conftest.xml > /dev/null 2>&1; then
-     fp_cv_dir_docbook_xsl=yes
-  fi
-  rm -rf conftest*])
-fi
-if test x"$fp_cv_dir_docbook_xsl" = xno; then
-  AC_MSG_WARN([cannot find DocBook XSL stylesheets, you will not be able to build the documentation])
-  HAVE_DOCBOOK_XSL=NO
-else
-  HAVE_DOCBOOK_XSL=YES
-fi
-AC_SUBST([HAVE_DOCBOOK_XSL])
-])# FP_DOCBOOK_XSL
-
-
-# FP_PROG_XMLLINT
-# ----------------
-# Sets the output variable XmllintCmd to the full path of the XSLT processor
-# xmllint. XmllintCmd is empty if xmllint could not be found.
-AC_DEFUN([FP_PROG_XMLLINT],
-[AC_PATH_PROG([XmllintCmd], [xmllint])
-if test -z "$XmllintCmd"; then
-  AC_MSG_WARN([cannot find xmllint in your PATH, you will not be able to validate your documentation])
-fi
-])# FP_PROG_XMLLINT
-
-
-# FP_CHECK_DOCBOOK_DTD
-# --------------------
-AC_DEFUN([FP_CHECK_DOCBOOK_DTD],
-[AC_REQUIRE([FP_PROG_XMLLINT])dnl
-if test -n "$XmllintCmd"; then
-  AC_MSG_CHECKING([for DocBook DTD])
-  FP_GEN_DOCBOOK_XML
-  if $XmllintCmd --nonet --valid --noout conftest.xml ; then
-    AC_MSG_RESULT([ok])
-  else
-    AC_MSG_RESULT([failed])
-    AC_MSG_WARN([cannot find a DTD for DocBook XML V4.5, you will not be able to validate your documentation])
-    AC_MSG_WARN([check your XML_CATALOG_FILES environment variable and/or /etc/xml/catalog])
-  fi
-  rm -rf conftest*
-fi
-])# FP_CHECK_DOCBOOK_DTD
-
-
 # FP_PROG_GHC_PKG
 # ----------------
 # Try to find a ghc-pkg matching the ghc mentioned in the environment variable
index 406a4a6..d890a6f 100644 (file)
@@ -768,10 +768,11 @@ then
     HSCOLOUR=`cygpath -m ${HSCOLOUR}`
 fi
 
-dnl ** check for DocBook toolchain
-FP_CHECK_DOCBOOK_DTD
-FP_DOCBOOK_XSL
-FP_PROG_DBLATEX
+dnl ** check for Sphinx toolchain
+AC_PATH_PROG(SPHINXBUILD,sphinx-build)
+
+dnl ** check for xelatex
+AC_PATH_PROG(XELATEX,xelatex)
 
 dnl ** check for ghc-pkg command
 FP_PROG_GHC_PKG
@@ -1092,25 +1093,22 @@ if test "$use_large_address_space" = "yes" ; then
    AC_DEFINE([USE_LARGE_ADDRESS_SPACE], [1], [Enable single heap address space support])
 fi
 
-if test "$HAVE_DOCBOOK_XSL" = "NO" ||
-   test "$XsltprocCmd" = ""
-then
-    BUILD_DOCBOOK_HTML=NO
-else
-    BUILD_DOCBOOK_HTML=YES
-fi
-AC_SUBST(BUILD_DOCBOOK_HTML)
-
-if test "$DblatexCmd" = ""
-then
-    BUILD_DOCBOOK_PS=NO
-    BUILD_DOCBOOK_PDF=NO
+if test -n "$SPHINXBUILD"; then
+    BUILD_MAN=YES
+    BUILD_SPHINX_HTML=YES
+    if test -n "$XELATEX"; then
+        BUILD_SPHINX_PDF=YES
+    else
+        BUILD_SPHINX_PDF=NO
+    fi
 else
-    BUILD_DOCBOOK_PS=YES
-    BUILD_DOCBOOK_PDF=YES
+    BUILD_MAN=NO
+    BUILD_SPHINX_HTML=NO
+    BUILD_SPHINX_PDF=NO
 fi
-AC_SUBST(BUILD_DOCBOOK_PS)
-AC_SUBST(BUILD_DOCBOOK_PDF)
+AC_SUBST(BUILD_MAN)
+AC_SUBST(BUILD_SPHINX_HTML)
+AC_SUBST(BUILD_SPHINX_PDF)
 
 LIBRARY_VERSION(base)
 LIBRARY_VERSION(Cabal, Cabal/Cabal)
@@ -1122,7 +1120,7 @@ if grep ' ' compiler/ghc.cabal.in 2>&1 >/dev/null; then
    AC_MSG_ERROR([compiler/ghc.cabal.in contains tab characters; please remove them])
 fi
 
-AC_CONFIG_FILES([mk/config.mk mk/install.mk mk/project.mk compiler/ghc.cabal ghc/ghc-bin.cabal utils/runghc/runghc.cabal settings docs/users_guide/ug-book.xml docs/users_guide/ug-ent.xml docs/index.html libraries/prologue.txt distrib/configure.ac])
+AC_CONFIG_FILES([mk/config.mk mk/install.mk mk/project.mk compiler/ghc.cabal ghc/ghc-bin.cabal utils/runghc/runghc.cabal settings docs/users_guide/ghc_config.py docs/index.html libraries/prologue.txt distrib/configure.ac])
 AC_OUTPUT
 
 # We got caught by
@@ -1181,8 +1179,8 @@ echo ["\
    Happy        : $HappyCmd ($HappyVersion)
    Alex         : $AlexCmd ($AlexVersion)
    Perl         : $PerlCmd
-   dblatex      : $DblatexCmd
-   xsltproc     : $XsltprocCmd
+   sphinx-build : $SPHINXBUILD
+   xelatex      : $XELATEX
 
    Using LLVM tools
       llc   : $LlcCmd
@@ -1199,9 +1197,8 @@ echo ["\
 fi
 
 echo ["\
-   Can build DocBook HTML documentation : $BUILD_DOCBOOK_HTML
-   Can build DocBook PS documentation   : $BUILD_DOCBOOK_PS
-   Can build DocBook PDF documentation  : $BUILD_DOCBOOK_PDF"]
+   Building Sphinx HTML documentation : $BUILD_SPHINX_HTML
+   Building Sphinx PDF documentation  : $BUILD_SPHINX_PDF"]
 
 echo ["----------------------------------------------------------------------
 "]
diff --git a/docs/man/gen_flags.xsl.sh b/docs/man/gen_flags.xsl.sh
deleted file mode 100644 (file)
index fed694f..0000000
+++ /dev/null
@@ -1,290 +0,0 @@
-#!/bin/sh
-
-if [ "$#" -ne 2 ]
-then
-    echo "Usage: $0 <ghc commands> <libdir>"
-    exit 1
-fi
-
-GHC_COMMANDS="$1"
-LIBDIR="$2"
-
-cat <<'EOF'
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE xsl:stylesheet [
-]>
-
-<xsl:stylesheet version="1.0"
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- xmlns="http://www.w3.org/TR/xhtml1/strict">
-
-<xsl:output method="text" omit-xml-declaration="yes" />
-
-<xsl:template match="/">.\"
-.\" This is a generated file.  Changes might get clobbered.  Edit at own's risk.
-.\"
-.TH GHC 1 "2002-10-25" "Glasgow FP Suite" "Glasgow Haskell Compiler"
-.SH NAME
-GHC \- the Glasgow Haskell Compiler
-
-
-.SH SYNOPSIS
-EOF
-
-STARTED=0
-
-for GHC_COMMAND in $GHC_COMMANDS
-do
-    if [ "$STARTED" -ne 0 ]
-    then
-        echo ".br"
-    fi
-    STARTED=1
-    cat <<EOF
-.B $GHC_COMMAND
-.RI [ option | filename ]...
-EOF
-done
-
-cat <<'EOF'
-
-.SH DESCRIPTION
-This manual page documents briefly the
-.B ghc
-and
-.B ghci
-commands.
-Note that
-.B ghci
-is not yet available on all architectures.
-Extensive documentation is available in various other formats
-including DVI, PostScript and HTML; see below.
-
-.PP
-Each of GHC's command line options is classified as either
-.IR static " or " dynamic .
-A static flag may only be specified on the command line, whereas a
-dynamic flag may also be given in an \f(CROPTIONS\fP pragma in a
-source file or set from the GHCi command-line with \f(CR:set\fP.
-
-As a rule of thumb, all the language options are dynamic, as are the
-warning options and the debugging options.
-
-The rest are static, with the notable exceptions of
-.BR \-v ", " \-cpp ", " \-fasm ", " \-fvia\-C ", " \-fllvm ", and
-" \-#include .
-The OPTIONS sections lists the status of each flag.
-
-.PP
-Common suffixes of file names for Haskell are:
-.TP
-.B .hs
-Haskell source code; preprocess, compile
-.TP
-.B .lhs
-literate Haskell source; unlit, preprocess, compile
-.TP
-.B .hi
-Interface file; contains information about exported
-symbols
-.TP
-.B .hc
-intermediate C files
-.TP
-.BI . x _o
-way
-.I x
-object files; common ways are:
-.BR p ", " u ", " s
-.TP
-.BI . x _hi
-way
-.I x
-interface files
-
-
-.SH OPTIONS
-
-<xsl:apply-templates select="sect1/sect2" mode="overview"/>
-
-<xsl:apply-templates select="sect1/sect2"/>
-
-
-.SH FILES
-EOF
-
-echo ".I $LIBDIR"
-cat <<'EOF'
-
-.SH COPYRIGHT
-
-Copyright 2002, The University Court of the University of Glasgow.
-.br
-All rights reserved.
-
-
-.SH AUTHOR
-
-This manual page was generated from the XML documentation of GHC with blood,
-sweat, tears and a breaks-if-you-look-at-it-the-wrong-way XSL
-stylesheet originally written by Michael Weber &lt;michaelw@debian.org&gt;
-for the Debian GNU/Linux system (but may be used by others).
-
-.\" End
-</xsl:template>
-
-
-<xsl:template match="sect1/sect2" mode="overview">
-<xsl:choose>
-<xsl:when test="contains(title/.,' (')">
-.SS <xsl:value-of select="substring-before(title/.,' (')"/>
-</xsl:when>
-<xsl:otherwise>
-.SS <xsl:value-of select="title/."/>
-</xsl:otherwise>
-</xsl:choose>
-.nh
-<xsl:apply-templates select="informaltable/tgroup/tbody/row" mode="overview"/>
-.hy
-</xsl:template>
-
-
-<xsl:template match="sect1/sect2">
-<xsl:choose>
-<xsl:when test="contains(title/.,' (')">
-
-.SH <xsl:value-of select='translate(substring-before(title/.," ("),"abcdefghijklmnopqrstuvwxyz","ABCDEFGHIJKLMNOPQRSTUVWXYZ")'/>
-
-</xsl:when>
-<xsl:otherwise>
-
-.SH <xsl:value-of select='translate(title/.,"abcdefghijklmnopqrstuvwxyz","ABCDEFGHIJKLMNOPQRSTUVWXYZ")'/>
-
-</xsl:otherwise>
-</xsl:choose><xsl:text>
-</xsl:text>
-<xsl:apply-templates select="informaltable/tgroup/tbody/row"/>
-</xsl:template>
-
-
-<xsl:template match="informaltable/tgroup/tbody/row" mode="overview">
-  <xsl:apply-templates select="entry[1]|entry[4]" mode="overview"/>
-  <xsl:text> </xsl:text>
-</xsl:template>
-
-<xsl:template match="informaltable/tgroup/tbody/row">
-.TP
-<xsl:apply-templates select="entry[1]"/><xsl:text>
-</xsl:text>
-<xsl:variable name="x">
-<xsl:apply-templates select="entry[2]"/>
-</xsl:variable>
-<xsl:value-of select="normalize-space($x)"/>
-.rj
-[<xsl:apply-templates select="entry[3]"/>]
-<!-- IGNORE NEGATIVE OPTIONS
-<xsl:if test="not(entry[4]='-')">
-  <xsl:text>.TP
-</xsl:text>
-  <xsl:apply-templates select="entry[4]/option"/>
-</xsl:if>
- -->
-</xsl:template>
-
-
-<xsl:template match="option" mode="escape-dash">
-  <xsl:variable name="x">
-    <xsl:value-of select="."/>
-  </xsl:variable>
-  <xsl:variable name="y">
-    <xsl:call-template name="replace-string">
-      <xsl:with-param name="text" select="$x"/>
-      <xsl:with-param name="from" select="'-'"/>
-      <xsl:with-param name="to" select="'\-'"/>
-    </xsl:call-template>
-  </xsl:variable>
-  <xsl:value-of select="$y"/>
-</xsl:template>
-
-<xsl:template match="option" mode="overview">
-  <xsl:apply-templates select="." mode="escape-dash"/>
-</xsl:template>
-
-<xsl:template match="option">
-  <xsl:text>\fB</xsl:text>
-  <xsl:apply-templates select="." mode="escape-dash"/>
-  <xsl:text>\fP</xsl:text>
-</xsl:template>
-
-
-<xsl:template match="entry[1]" mode="overview">
-  <xsl:apply-templates mode="overview"/>
-  <xsl:text> </xsl:text>
-</xsl:template>
-
-<xsl:template match="entry[1]">
-  <xsl:apply-templates/><xsl:text> </xsl:text>
-</xsl:template>
-
-<xsl:template match="entry[4]" mode="overview">
-  <xsl:if test="not(.='-')">
-    <xsl:apply-templates select="option" mode="overview"/>
-    <xsl:text> </xsl:text>
-  </xsl:if>
-</xsl:template>
-
-<xsl:template match="entry[4]">
-  <xsl:if test="not(.='-')">
-    <xsl:value-of select="."/><xsl:text> </xsl:text>
-  </xsl:if>
-</xsl:template>
-
-
-<xsl:template match="replaceable" mode="overview">
-  <xsl:apply-templates select="."/>
-</xsl:template>
-
-<xsl:template match="replaceable">
-  <xsl:text>\fI</xsl:text>
-  <xsl:value-of select='.'/>
-  <xsl:text>\fP</xsl:text>
-</xsl:template>
-
-
-<xsl:template match="literal">
-  <xsl:text>\f(CR</xsl:text>
-  <xsl:value-of select="."/>
-  <xsl:text>\fP</xsl:text>
-</xsl:template>
-
-
-
-<!-- reusable replace-string function -->
-  <xsl:template name="replace-string">
-     <xsl:param name="text"/>
-     <xsl:param name="from"/>
-     <xsl:param name="to"/>
-
-     <xsl:choose>
-       <xsl:when test="contains($text, $from)">
-
-         <xsl:variable name="before" select="substring-before($text, $from)"/>
-         <xsl:variable name="after" select="substring-after($text, $from)"/>
-         <xsl:variable name="prefix" select="concat($before, $to)"/>
-
-         <xsl:value-of select="$before"/>
-         <xsl:value-of select="$to"/>
-         <xsl:call-template name="replace-string">
-           <xsl:with-param name="text" select="$after"/>
-           <xsl:with-param name="from" select="$from"/>
-           <xsl:with-param name="to" select="$to"/>
-         </xsl:call-template>
-       </xsl:when>
-       <xsl:otherwise>
-         <xsl:value-of select="$text"/>
-       </xsl:otherwise>
-     </xsl:choose>
-  </xsl:template>
-</xsl:stylesheet>
-EOF
-
diff --git a/docs/man/ghc.mk b/docs/man/ghc.mk
deleted file mode 100644 (file)
index 470bd9a..0000000
+++ /dev/null
@@ -1,58 +0,0 @@
-
-ifeq "$(BUILD_MAN)" ""
-ifeq "$(strip $(XSLTPROC))" ""
-BUILD_MAN = NO
-else
-BUILD_MAN = YES
-endif
-endif
-
-# The commands which should be mentioned in the man page
-MAN_GHC_COMMANDS = ghc ghci
-
-# The man page we are generating
-MAN_PAGE = ghc
-
-# The manual section
-MAN_SECTION = 1
-
-MAN_PATH = docs/man/$(MAN_PAGE).$(MAN_SECTION)
-
-ifneq "$(BINDIST)" "YES"
-$(MAN_PATH): docs/man/flags.xsl docs/man/flags.xml
-       $(XSLTPROC) $(XSLTPROC_OPTS) $^ > $@
-endif
-
-# Insert the commands and the library directory into the man page
-docs/man/flags.xsl: docs/man/gen_flags.xsl.sh
-       $(SHELL) $< "$(MAN_GHC_COMMANDS)" "$(libdir)" > $@
-
-# Re-use the flags documentation from the user's guide by injecting some
-# entities after the XML declaration to make it a stand-alone document.
-docs/man/flags.xml: docs/users_guide/flags.xml
-       $(call removeFiles,$@)
-       head -n 1 $< >> $@
-       echo "<!DOCTYPE sect1 [<!ENTITY ndash  \"-\"> \
-                              <!ENTITY ldquo  \"\`\"> \
-                              <!ENTITY rdquo  \"'\">]>" >> $@
-# "sed 1d" == "tail -n +2", but Solaris apparently rejects the latter
-       sed 1d $< >> $@
-
-ifeq "$(BUILD_MAN)" "YES"
-ifeq "$(phase)" "final"
-$(eval $(call all-target,docs/man,$(MAN_PATH)))
-endif
-
-INSTALL_MANPAGES += $(MAN_PATH)
-
-install: install_man
-
-.PHONY: install_man
-install_man: $(MAN_PATH)
-       $(INSTALL_DIR) "$(DESTDIR)$(mandir)"
-       $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man$(MAN_SECTION)"
-       $(INSTALL_MAN) $(INSTALL_OPTS) $(MAN_PATH) "$(DESTDIR)$(mandir)/man$(MAN_SECTION)"
-endif
-
-$(eval $(call clean-target,docs/man,,$(MAN_PATH) docs/man/flags.xsl docs/man/flags.xml))
-
diff --git a/docs/users_guide/7.12.1-notes.rst b/docs/users_guide/7.12.1-notes.rst
new file mode 100644 (file)
index 0000000..188daa9
--- /dev/null
@@ -0,0 +1,332 @@
+.. _release-7-12-1:
+
+Release notes for version 7.12.1
+================================
+
+The significant changes to the various parts of the compiler are listed
+in the following sections. There have also been numerous bug fixes and
+performance improvements over the 7.10 branch.
+
+Highlights
+----------
+
+The highlights, since the 7.10 branch, are:
+
+-  TODO FIXME
+
+Full details
+------------
+
+Language
+~~~~~~~~
+
+-  TODO FIXME.
+
+-  The parser now supports Haddock comments on GADT data constructors.
+   For example,
+
+   ::
+
+                             data Expr a where
+                               -- | Just a normal sum
+                               Sum :: Int -> Int -> Expr Int
+
+-  Implicit parameters of the new ghc-prim type ``GHC.Types.CallStack``
+   are treated specially, and automatically solved for the current
+   source location. For example
+
+   ::
+
+                             f = print (?stk :: CallStack)
+
+   will print the singleton stack containing the occurrence of ``?stk``.
+   If there is another ``CallStack`` implicit in-scope, the new location
+   will be appended to the existing stack, e.g.
+
+   ::
+
+                             f :: (?stk :: CallStack) => IO ()
+                             f = print (?stk :: CallStack)
+
+   will print the occurrence of ``?stk`` and the call-site of ``f``. The
+   name of the implicit parameter does not matter.
+
+   See the release notes for ghc-prim for a description of the
+   ``CallStack`` type.
+
+-  To conform to the common case, the default role assigned to
+   parameters of datatypes declared in ``hs-boot`` files is
+   ``representational``. However, if the constructor(s) for the datatype
+   are given, it makes sense to do normal role inference. This is now
+   implemented, effectively making the default role for non-abstract
+   datatypes in ``hs-boot`` files to be ``phantom``, like it is in
+   regular Haskell code.
+
+-  Wildcards can be used in the type arguments of type/data family
+   instance declarations to indicate that the name of a type variable
+   doesn't matter. They will be replaced with new unique type variables.
+   See :ref:`data-instance-declarations` for more details.
+
+-  GHC now allows to declare type families as injective. Injectivity
+   information can then be used by the typechecker. See
+   :ref:`injective-ty-fams` for details.
+
+-  Due to a :ghc-ticket:`security issue <10826>`, Safe Haskell now forbids
+   annotations in programs marked as ``-XSafe``.
+
+
+Compiler
+~~~~~~~~
+
+-  Added the option ``-dth-dec-file``. This dumps out a .th.hs file of
+   all Template Haskell declarations in a corresponding .hs file. The
+   idea is that application developers can check this into their
+   repository so that they can grep for identifiers used elsewhere that
+   were defined in Template Haskell. This is similar to using
+   ``-ddump-to-file`` with ``-ddump-splices`` but it always generates a
+   file instead of being coupled to ``-ddump-to-file`` and only outputs
+   code that does not exist in the .hs file and a comment for the splice
+   location in the original file.
+
+-  Added the option ``-fprint-expanded-types``. When enabled, GHC also
+   prints type-synonym-expanded types in type errors.
+
+-  Added the option ``-fcpr-anal``. When enabled, the demand analyser
+   performs CPR analysis. It is implied by ``-O``. Consequently,
+   ``-fcpr-off`` is now removed, run with ``-fno-cpr-anal`` to get the
+   old ``-fcpr-off`` behaviour.
+
+GHCi
+~~~~
+
+-  ``Main`` with an explicit module header but without ``main`` is now
+   an error (#7765).
+
+   The ``:back`` and ``:forward`` commands now take an optional count
+   allowing the user to move forward or backward in history several
+   steps at a time.
+
+   Added commands ``:load!`` and ``:reload!``, effectively setting
+   "-fdefer-type-errors" before loading a module and unsetting it after
+   loading if it has not been set before (#8353).
+
+Template Haskell
+~~~~~~~~~~~~~~~~
+
+-  The ``TemplateHaskell`` now no longer automatically errors when used
+   with a stage 1 compiler (i.e. GHC without interpreter support); in
+   particular, plain Haskell quotes (not quasi-quotes) can now be
+   compiled without erroring. Splices and quasi-quotes continue to only
+   be supported by a stage 2 compiler.
+
+-  Partial type signatures can now be used in splices, see
+   :ref:`pts-where`.
+
+-  ``Template Haskell`` now supports the use of ``UInfixT`` in types to
+   resolve infix operator fixities, in the same vein as ``UInfixP`` and
+   ``UInfixE`` in patterns and expressions. ``ParensT`` and ``InfixT``
+   have also been introduced, serving the same functions as their
+   pattern and expression counterparts.
+
+-  Primitive chars (e.g., ``[| 'a'# |]``) and primitive strings (e.g.,
+   ``[| "abc"# |]``) can now be quoted with Template Haskell. The
+   ``Lit`` data type also has a new constructor, ``CharPrimL``, for
+   primitive char literals.
+
+-  ``addTopDecls`` now accepts annotation pragmas.
+
+-  Internally, the implementation of quasi-quotes has been unified with
+   that of normal Template Haskell splices. Under the previous
+   implementation, top-level declaration quasi-quotes did not cause a
+   break in the declaration groups, unlike splices of the form
+   ``$(...)``. This behavior has been preserved under the new
+   implementation, and is now recognized and documented in
+   :ref:`th-syntax`.
+
+-  The ``Lift`` class is now derivable via the ``-XDeriveLift`` extension. See
+   :ref:`deriving-lift` for more information.
+
+
+Runtime system
+~~~~~~~~~~~~~~
+
+-  TODO FIXME.
+
+Build system
+~~~~~~~~~~~~
+
+-  TODO FIXME.
+
+Package system
+~~~~~~~~~~~~~~
+
+-  TODO FIXME.
+
+Libraries
+---------
+
+array
+~~~~~
+
+-  Version number XXXXX (was 0.5.0.0)
+
+base
+~~~~
+
+-  Version number XXXXX (was 4.7.0.0)
+
+-  A new module ``GHC.SrcLoc`` was added, exporting a new type
+   ``SrcLoc``. A ``SrcLoc`` contains package, module, and file names, as
+   well as start and end positions.
+
+-  A new type ``CallStack`` was added for use with the new implicit
+   callstack parameters. A ``CallStack`` is a ``[(String, SrcLoc)]``,
+   sorted by most-recent call.
+
+-  A new function, ``interruptible``, was added to ``GHC.IO`` allowing
+   an ``IO`` action to be run such that it can be interrupted by an
+   asynchronous exception, even if exceptions are masked (except if
+   masked with ``interruptibleMask``).
+
+   This was introduced to fix the behavior of ``allowInterrupt``, which
+   would previously incorrectly allow exceptions in uninterruptible
+   regions (see :ghc-ticket:`9516`).
+
+-  Per-thread allocation counters (``setAllocationCounter`` and
+   ``getAllocationCounter``) and limits (``enableAllocationLimit``,
+   ``disableAllocationLimit`` are now available from ``System.Mem``. Previously
+   this functionality was only available from ``GHC.Conc``.
+
+
+bin-package-db
+~~~~~~~~~~~~~~
+
+-  This is an internal package, and should not be used.
+
+binary
+~~~~~~
+
+-  Version number XXXXX (was 0.7.1.0)
+
+bytestring
+~~~~~~~~~~
+
+-  Version number XXXXX (was 0.10.4.0)
+
+Cabal
+~~~~~
+
+-  Version number XXXXX (was 1.18.1.3)
+
+containers
+~~~~~~~~~~
+
+-  Version number XXXXX (was 0.5.4.0)
+
+deepseq
+~~~~~~~
+
+-  Version number XXXXX (was 1.3.0.2)
+
+directory
+~~~~~~~~~
+
+-  Version number XXXXX (was 1.2.0.2)
+
+filepath
+~~~~~~~~
+
+-  Version number XXXXX (was 1.3.0.2)
+
+ghc
+~~~
+
+-  TODO FIXME.
+
+-  The ``HsBang`` type has been removed in favour of ``HsSrcBang`` and
+   ``HsImplBang``. Data constructors now always carry around their
+   strictness annotations as the user wrote them, whether from an
+   imported module or not.
+
+ghc-prim
+~~~~~~~~
+
+-  Version number XXXXX (was 0.3.1.0)
+
+haskell98
+~~~~~~~~~
+
+-  Version number XXXXX (was 2.0.0.3)
+
+haskell2010
+~~~~~~~~~~~
+
+-  Version number XXXXX (was 1.1.1.1)
+
+hoopl
+~~~~~
+
+-  Version number XXXXX (was 3.10.0.0)
+
+hpc
+~~~
+
+-  Version number XXXXX (was 0.6.0.1)
+
+integer-gmp
+~~~~~~~~~~~
+
+-  Version number XXXXX (was 0.5.1.0)
+
+old-locale
+~~~~~~~~~~
+
+-  Version number XXXXX (was 1.0.0.6)
+
+old-time
+~~~~~~~~
+
+-  Version number XXXXX (was 1.1.0.2)
+
+process
+~~~~~~~
+
+-  Version number XXXXX (was 1.2.0.0)
+
+template-haskell
+~~~~~~~~~~~~~~~~
+
+-  Version number XXXXX (was 2.9.0.0)
+
+-  The ``Lift`` type class for lifting values into Template Haskell
+   splices now has a default signature ``lift :: Data a => a -> Q Exp``,
+   which means that you do not have to provide an explicit
+   implementation of ``lift`` for types which have a ``Data`` instance.
+   To manually use this default implementation, you can use the
+   ``liftData`` function which is now exported from
+   ``Language.Haskell.TH.Syntax``.
+
+-  ``Info``'s constructors no longer have ``Fixity`` fields. A
+   ``qReifyFixity`` function was added to the ``Quasi`` type class (as
+   well as the ``reifyFixity`` function, specialized for ``Q``) to allow
+   lookup of fixity information for any given ``Name``.
+
+time
+~~~~
+
+-  Version number XXXXX (was 1.4.1)
+
+unix
+~~~~
+
+-  Version number XXXXX (was 2.7.0.0)
+
+Win32
+~~~~~
+
+-  Version number XXXXX (was 2.3.0.1)
+
+Known bugs
+----------
+
+-  TODO FIXME
diff --git a/docs/users_guide/7.12.1-notes.xml b/docs/users_guide/7.12.1-notes.xml
deleted file mode 100644 (file)
index c71887f..0000000
+++ /dev/null
@@ -1,628 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<sect1 id="release-7-12-1">
-  <title>Release notes for version 7.12.1</title>
-
-  <para>
-      The significant changes to the various parts of the compiler are listed
-      in the following sections. There have also been numerous bug fixes and
-      performance improvements over the 7.10 branch.
-  </para>
-
-  <sect2>
-    <title>Highlights</title>
-
-    <para>
-        The highlights, since the 7.10 branch, are:
-    </para>
-
-    <itemizedlist>
-        <listitem>
-            <para>
-                TODO FIXME
-           </para>
-       </listitem>
-   </itemizedlist>
-  </sect2>
-
-  <sect2>
-    <title>Full details</title>
-    <sect3>
-        <title>Language</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    TODO FIXME.
-               </para>
-           </listitem>
-
-            <listitem>
-                <para>
-                    The parser now supports Haddock comments on GADT data constructors. For example,
-                    <programlisting>
-                      data Expr a where
-                        -- | Just a normal sum
-                        Sum :: Int -> Int -> Expr Int
-                    </programlisting>
-               </para>
-           </listitem>
-            <listitem>
-                <para>
-                    Implicit parameters of the new ghc-prim type
-                    <literal>GHC.Types.CallStack</literal> are treated
-                    specially, and automatically solved for the current source
-                    location. For example
-                    <programlisting>
-                      f = print (?stk :: CallStack)
-                    </programlisting>
-                    will print the singleton stack containing the occurrence of
-                    <literal>?stk</literal>. If there is another
-                    <literal>CallStack</literal> implicit in-scope, the new location
-                    will be appended to the existing stack, e.g.
-                    <programlisting>
-                      f :: (?stk :: CallStack) => IO ()
-                      f = print (?stk :: CallStack)
-                    </programlisting>
-                    will print the occurrence of <literal>?stk</literal> and the
-                    call-site of <literal>f</literal>. The name of the implicit
-                    parameter does not matter.
-               </para>
-                <para>
-                    See the release notes for ghc-prim for a description of the
-                    <literal>CallStack</literal> type.
-               </para>
-            </listitem>
-
-           <listitem>
-             <para>
-               To conform to the common case, the default role assigned to parameters
-               of datatypes declared in <literal>hs-boot</literal> files is
-               <literal>representational</literal>. However, if the constructor(s)
-               for the datatype are given, it makes sense to do normal role inference.
-               This is now implemented, effectively making the default role for
-               non-abstract datatypes in <literal>hs-boot</literal> files to be
-               <literal>phantom</literal>, like it is in regular Haskell code.
-             </para>
-           </listitem>
-            <listitem>
-              <para>
-                Wildcards can be used in the type arguments of type/data
-                family instance declarations to indicate that the name of a
-                type variable doesn't matter. They will be replaced with new
-                unique type variables. See <xref
-                linkend="data-instance-declarations"/> for more details.
-              </para>
-            </listitem>
-
-            <listitem>
-                <para>
-                    GHC now allows to declare type families as injective.
-                    Injectivity information can then be used by the typechecker.
-                    See <xref linkend="injective-ty-fams"/> for details.
-               </para>
-           </listitem>
-
-           <listitem>
-               <para>
-                   Due to a <ulink href="https://ghc.haskell.org/trac/ghc/ticket/10826">
-                       security issue
-                   </ulink>, Safe Haskell now forbids annotations in programs marked as
-                   <literal>-XSafe</literal>
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>Compiler</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Added the option <option>-dth-dec-file</option>.
-
-                    This dumps out a .th.hs file of all Template Haskell declarations in a corresponding .hs file. The idea is that application developers can check this into their repository so that they can grep for identifiers used elsewhere that were defined in Template Haskell.
-                    This is similar to using <option>-ddump-to-file</option> with <option>-ddump-splices</option> but it always generates a file instead of being coupled to <option>-ddump-to-file</option> and only outputs code that does not exist in the .hs file and a comment for the splice location in the original file.
-                </para>
-           </listitem>
-           <listitem>
-               <para>
-                   Added the option <option>-fprint-expanded-types</option>.
-
-                   When enabled, GHC also prints type-synonym-expanded types in
-                   type errors.
-               </para>
-           </listitem>
-           <listitem>
-               <para>
-                   Added the option <option>-fcpr-anal</option>.
-
-                   When enabled, the demand analyser performs CPR analysis.
-                   It is implied by <option>-O</option>. Consequently,
-                   <option>-fcpr-off</option> is now removed, run with
-                   <option>-fno-cpr-anal</option> to get the old
-                   <option>-fcpr-off</option> behaviour.
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>GHCi</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    <literal>Main</literal> with an explicit module header but
-                    without <literal>main</literal> is now an error (#7765).
-               </para>
-               <para>
-                    The <literal>:back</literal> and <literal>:forward</literal>
-                    commands now take an optional count allowing the user to move forward or
-                    backward in history several steps at a time.
-               </para>
-               <para>
-                    Added commands <literal>:load!</literal> and <literal>:reload!</literal>,
-                    effectively setting "-fdefer-type-errors" before loading a module and
-                    unsetting it after loading if it has not been set before (#8353).
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>Template Haskell</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    The <literal>TemplateHaskell</literal> now no longer automatically
-                    errors when used with a stage 1 compiler (i.e. GHC without
-                    interpreter support); in particular, plain
-                    Haskell quotes (not quasi-quotes) can now be compiled without erroring.
-                    Splices and quasi-quotes continue to only be supported by a
-                    stage 2 compiler.
-               </para>
-            </listitem>
-            <listitem>
-                <para>
-                    Partial type signatures can now be used in splices, see <xref linkend="pts-where"/>.
-                </para>
-            </listitem>
-            <listitem>
-                <para>
-                    <literal>Template Haskell</literal> now supports the use of
-                    <literal>UInfixT</literal> in types to resolve infix
-                    operator fixities, in the same vein as
-                    <literal>UInfixP</literal> and <literal>UInfixE</literal>
-                    in patterns and expressions. <literal>ParensT</literal>
-                    and <literal>InfixT</literal> have also been introduced,
-                    serving the same functions as their pattern and expression
-                    counterparts.
-                </para>
-            </listitem>
-             <listitem>
-                 <para>
-                     Primitive chars (e.g., <literal>[| 'a'# |]</literal>) and
-                     primitive strings (e.g., <literal>[| "abc"# |]</literal>)
-                     can now be quoted with Template Haskell. The
-                     <literal>Lit</literal> data type also has a new
-                     constructor, <literal>CharPrimL</literal>, for primitive
-                     char literals.
-                </para>
-            </listitem>
-             <listitem>
-                 <para>
-                     <literal>addTopDecls</literal> now accepts annotation
-                     pragmas.
-                </para>
-            </listitem>
-             <listitem>
-                 <para>
-                     Internally, the implementation of quasi-quotes has been
-                     unified with that of normal Template Haskell splices. Under
-                     the previous implementation, top-level declaration
-                     quasi-quotes did not cause a break in the declaration
-                     groups, unlike splices of the form
-                     <literal>$(...)</literal>. This behavior has been
-                     preserved under the new implementation, and is now
-                     recognized and documented in <xref linkend="th-syntax"/>.
-               </para>
-           </listitem>
-            <listitem>
-                <para>
-                     The <literal>Lift</literal> class is now derivable via
-                     the <option>-XDeriveLift</option> extension. See
-                     <xref linkend="deriving-lift"/> for more information.
-                </para>
-            </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>Runtime system</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    TODO FIXME.
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>Build system</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    TODO FIXME.
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>Package system</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    TODO FIXME.
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-  </sect2>
-
-  <sect2>
-    <title>Libraries</title>
-
-    <sect3>
-        <title>array</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 0.5.0.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>base</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 4.7.0.0)
-               </para>
-           </listitem>
-            <listitem>
-                <para>
-                    A new module <literal>GHC.SrcLoc</literal> was added,
-                    exporting a new type <literal>SrcLoc</literal>. A
-                    <literal>SrcLoc</literal> contains package, module,
-                    and file names, as well as start and end positions.
-               </para>
-           </listitem>
-            <listitem>
-                <para>
-                    A new type <literal>CallStack</literal> was added for use
-                    with the new implicit callstack parameters. A
-                    <literal>CallStack</literal> is a
-                    <literal>[(String, SrcLoc)]</literal>, sorted by most-recent
-                    call.
-               </para>
-           </listitem>
-            <listitem>
-                <para>
-                    A new function, <literal>interruptible</literal>, was added
-                    to <literal>GHC.IO</literal> allowing an
-                    <literal>IO</literal> action to be run such that it can be
-                    interrupted by an asynchronous exception, even if exceptions
-                    are masked (except if masked with
-                    <literal>interruptibleMask</literal>).
-                </para>
-                <para>
-                    This was introduced to fix the behavior of
-                    <literal>allowInterrupt</literal>, which would previously
-                    incorrectly allow exceptions in uninterruptible regions
-                    (see Trac #9516).
-               </para>
-           </listitem>
-           <listitem>
-                <para>
-                    Per-thread allocation counters
-                    (<literal>setAllocationCounter</literal> and
-                    <literal>getAllocationCounter</literal>) and limits
-                    (<literal>enableAllocationLimit</literal>,
-                    <literal>disableAllocationLimit</literal> are now
-                    available from <literal>System.Mem</literal>.
-                    Previously this functionality was only available
-                    from <literal>GHC.Conc</literal>.
-                </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>bin-package-db</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    This is an internal package, and should not be used.
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>binary</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 0.7.1.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>bytestring</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 0.10.4.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>Cabal</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.18.1.3)
-              </para>
-          </listitem>
-      </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>containers</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 0.5.4.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>deepseq</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.3.0.2)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>directory</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.2.0.2)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>filepath</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.3.0.2)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>ghc</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    TODO FIXME.
-               </para>
-            </listitem>
-            <listitem>
-              <para>
-                The <literal>HsBang</literal> type has been removed in
-                favour of <literal>HsSrcBang</literal> and
-                <literal>HsImplBang</literal>. Data constructors now
-                always carry around their strictness annotations as
-                the user wrote them, whether from an imported module
-                or not.
-              </para>
-            </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>ghc-prim</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 0.3.1.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>haskell98</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 2.0.0.3)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>haskell2010</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.1.1.1)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>hoopl</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 3.10.0.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>hpc</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 0.6.0.1)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>integer-gmp</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 0.5.1.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>old-locale</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.0.0.6)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>old-time</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.1.0.2)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>process</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.2.0.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>template-haskell</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 2.9.0.0)
-               </para>
-           </listitem>
-            <listitem>
-                <para>
-                    The <literal>Lift</literal> type class for lifting values
-                    into Template Haskell splices now has a default signature
-                    <literal>lift :: Data a => a -> Q Exp</literal>, which means
-                    that you do not have to provide an explicit implementation
-                    of <literal>lift</literal> for types which have a <literal>Data</literal>
-                    instance.  To manually use this default implementation, you
-                    can use the <literal>liftData</literal> function which is
-                    now exported from <literal>Language.Haskell.TH.Syntax</literal>.
-               </para>
-          </listitem>
-           <listitem>
-               <para>
-                    <literal>Info</literal>'s constructors no longer have
-                    <literal>Fixity</literal> fields. A <literal>qReifyFixity
-                    </literal> function was added to the <literal>Quasi
-                    </literal> type class (as well as the <literal>reifyFixity
-                    </literal> function, specialized for <literal>Q</literal>)
-                    to allow lookup of fixity information for any given
-                    <literal>Name</literal>.
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>time</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 1.4.1)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>unix</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 2.7.0.0)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-
-    <sect3>
-        <title>Win32</title>
-        <itemizedlist>
-            <listitem>
-                <para>
-                    Version number XXXXX (was 2.3.0.1)
-               </para>
-           </listitem>
-       </itemizedlist>
-    </sect3>
-  </sect2>
-
-  <sect2>
-    <title>Known bugs</title>
-    <itemizedlist>
-        <listitem>
-            <para>
-                TODO FIXME
-           </para>
-       </listitem>
-   </itemizedlist>
-  </sect2>
-</sect1>
diff --git a/docs/users_guide/bugs.rst b/docs/users_guide/bugs.rst
new file mode 100644 (file)
index 0000000..944925a
--- /dev/null
@@ -0,0 +1,492 @@
+.. _bugs-and-infelicities:
+
+Known bugs and infelicities
+===========================
+
+.. _vs-Haskell-defn:
+
+Haskell standards vs. Glasgow Haskell: language non-compliance
+--------------------------------------------------------------
+
+.. index::
+   single: GHC vs the Haskell standards
+   single: Haskell standards vs GHC
+
+This section lists Glasgow Haskell infelicities in its implementation of
+Haskell 98 and Haskell 2010. See also the “when things go wrong” section
+(:ref:`wrong`) for information about crashes, space leaks, and other
+undesirable phenomena.
+
+The limitations here are listed in Haskell Report order (roughly).
+
+.. _haskell-standards-divergence:
+
+Divergence from Haskell 98 and Haskell 2010
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, GHC mainly aims to behave (mostly) like a Haskell 2010
+compiler, although you can tell it to try to behave like a particular
+version of the language with the ``-XHaskell98`` and ``-XHaskell2010``
+flags. The known deviations from the standards are described below.
+Unless otherwise stated, the deviation applies in Haskell 98,
+Haskell 2010 and the default modes.
+
+.. _infelicities-lexical:
+
+Lexical syntax
+^^^^^^^^^^^^^^
+
+-  Certain lexical rules regarding qualified identifiers are slightly
+   different in GHC compared to the Haskell report. When you have
+   ⟨module⟩\ ``.``\ ⟨reservedop⟩, such as ``M.\``, GHC will interpret it
+   as a single qualified operator rather than the two lexemes ``M`` and
+   ``.\``.
+
+.. _infelicities-syntax:
+
+Context-free syntax
+^^^^^^^^^^^^^^^^^^^
+
+-  In Haskell 98 mode and by default (but not in Haskell 2010 mode), GHC
+   is a little less strict about the layout rule when used in ``do``
+   expressions. Specifically, the restriction that "a nested context
+   must be indented further to the right than the enclosing context" is
+   relaxed to allow the nested context to be at the same level as the
+   enclosing context, if the enclosing context is a ``do`` expression.
+
+   For example, the following code is accepted by GHC:
+
+   ::
+
+       main = do args <- getArgs
+                 if null args then return [] else do
+                 ps <- mapM process args
+                 mapM print ps
+
+   This behaviour is controlled by the ``NondecreasingIndentation``
+   extension.
+
+-  GHC doesn't do the fixity resolution in expressions during parsing as
+   required by Haskell 98 (but not by Haskell 2010). For example,
+   according to the Haskell 98 report, the following expression is
+   legal:
+
+   ::
+
+           let x = 42 in x == 42 == True
+
+   and parses as:
+
+   ::
+
+           (let x = 42 in x == 42) == True
+
+   because according to the report, the ``let`` expression “extends as
+   far to the right as possible”. Since it can't extend past the second
+   equals sign without causing a parse error (``==`` is non-fix), the
+   ``let``\-expression must terminate there. GHC simply gobbles up the
+   whole expression, parsing like this:
+
+   ::
+
+           (let x = 42 in x == 42 == True)
+-  The Haskell Report allows you to put a unary ``-`` preceding certain
+   expressions headed by keywords, allowing constructs like ``- case x of ...``
+   or ``- do { ... }``. GHC does not allow this. Instead, unary ``-`` is allowed
+   before only expressions that could potentially be applied as a function.
+
+
+.. _infelicities-exprs-pats:
+
+Expressions and patterns
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+In its default mode, GHC makes some programs slightly more defined than
+they should be. For example, consider
+
+::
+
+    f :: [a] -> b -> b
+    f [] = error "urk"
+    f (x:xs) = \v -> v
+
+    main = print (f [] `seq` True)
+
+This should call ``error`` but actually prints ``True``. Reason: GHC
+eta-expands ``f`` to
+
+::
+
+    f :: [a] -> b -> b
+    f []     v = error "urk"
+    f (x:xs) v = v
+
+This improves efficiency slightly but significantly for most programs,
+and is bad for only a few. To suppress this bogus "optimisation" use
+``-fpedantic-bottoms``.
+
+.. _infelicities-decls:
+
+Declarations and bindings
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In its default mode, GHC does not accept datatype contexts, as it has
+been decided to remove them from the next version of the language
+standard. This behaviour can be controlled with the ``DatatypeContexts``
+extension. See :ref:`datatype-contexts`.
+
+.. _infelicities-Modules:
+
+Module system and interface files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GHC requires the use of ``hs-boot`` files to cut the recursive loops
+among mutually recursive modules as described in
+:ref:`mutual-recursion`. This more of an infelicity than a bug: the
+Haskell Report says (`Section
+5.7 <http://haskell.org/onlinereport/modules.html#sect5.7>`__)
+
+    "Depending on the Haskell implementation used, separate compilation of
+    mutually recursive modules may require that imported modules contain
+    additional information so that they may be referenced before they are
+    compiled. Explicit type signatures for all exported values may be
+    necessary to deal with mutual recursion. The precise details of separate
+    compilation are not defined by this Report."
+
+.. _infelicities-numbers:
+
+Numbers, basic types, and built-in classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``Num`` superclasses
+    The ``Num`` class does not have ``Show`` or ``Eq`` superclasses.
+
+    
+    You can make code that works with both Haskell98/Haskell2010 and GHC
+    by:
+
+    -  Whenever you make a ``Num`` instance of a type, also make
+        ``Show`` and ``Eq`` instances, and
+
+    -  Whenever you give a function, instance or class a ``Num t``
+        constraint, also give it ``Show t`` and ``Eq t`` constraints.
+
+``Bits`` superclasses
+    The ``Bits`` class does not have a ``Num`` superclasses. It
+    therefore does not have default methods for the ``bit``, ``testBit``
+    and ``popCount`` methods.
+
+    You can make code that works with both Haskell 2010 and GHC by:
+
+    -  Whenever you make a ``Bits`` instance of a type, also make a
+        ``Num`` instance, and
+
+    -  Whenever you give a function, instance or class a ``Bits t``
+        constraint, also give it a ``Num t`` constraint, and
+
+    -  Always define the ``bit``, ``testBit`` and ``popCount`` methods
+        in ``Bits`` instances.
+
+Extra instances
+    The following extra instances are defined:
+
+    ::
+
+        instance Functor ((->) r)
+        instance Monad ((->) r)
+        instance Functor ((,) a)
+        instance Functor (Either a)
+        instance Monad (Either e)
+
+Multiply-defined array elements not checked
+    This code fragment should elicit a fatal error, but it does not:
+
+    ::
+
+        main = print (array (1,1) [(1,2), (1,3)])
+
+    GHC's implementation of ``array`` takes the value of an array slot
+    from the last (index,value) pair in the list, and does no checking
+    for duplicates. The reason for this is efficiency, pure and simple.
+
+.. _infelicities-Prelude:
+
+In ``Prelude`` support
+^^^^^^^^^^^^^^^^^^^^^^
+
+Arbitrary-sized tuples
+    Tuples are currently limited to size 100. However, standard
+    instances for tuples (``Eq``, ``Ord``, ``Bounded``, ``Ix``, ``Read``,
+    and ``Show``) are available *only* up to 16-tuples.
+
+    This limitation is easily subvertible, so please ask if you get
+    stuck on it.
+
+``splitAt`` semantics
+    ``Data.List.splitAt`` is stricter than specified in the Report.
+    Specifically, the Report specifies that
+
+    ..
+
+       splitAt n xs = (take n xs, drop n xs)
+
+    which implies that
+
+    ..
+
+       splitAt undefined undefined = (undefined, undefined)
+
+    but GHC's implementation is strict in its first argument, so
+
+    ..
+
+        splitAt undefined [] = undefined
+
+``Read``\ ing integers
+    GHC's implementation of the ``Read`` class for integral types
+    accepts hexadecimal and octal literals (the code in the Haskell 98
+    report doesn't). So, for example,
+
+    ::
+
+        read "0xf00" :: Int
+
+    works in GHC.
+
+    A possible reason for this is that ``readLitChar`` accepts hex and
+    octal escapes, so it seems inconsistent not to do so for integers
+    too.
+
+``isAlpha``
+    The Haskell 98 definition of ``isAlpha`` is:
+
+    ::
+
+        isAlpha c = isUpper c || isLower c
+
+    GHC's implementation diverges from the Haskell 98 definition in the
+    sense that Unicode alphabetic characters which are neither upper nor
+    lower case will still be identified as alphabetic by ``isAlpha``.
+
+``hGetContents``
+    Lazy I/O throws an exception if an error is encountered, in contrast
+    to the Haskell 98 spec which requires that errors are discarded (see
+    Section 21.2.2 of the Haskell 98 report). The exception thrown is
+    the usual IO exception that would be thrown if the failing IO
+    operation was performed in the IO monad, and can be caught by
+    ``System.IO.Error.catch`` or ``Control.Exception.catch``.
+
+.. _infelicities-ffi:
+
+The Foreign Function Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``hs_init()``, ``hs_exit()``
+    The FFI spec requires the implementation to support re-initialising
+    itself after being shut down with ``hs_exit()``, but GHC does not
+    currently support that.
+
+    .. index::
+        single: hs_init
+        single: hs_exit
+
+.. _haskell-98-2010-undefined:
+
+GHC's interpretation of undefined behaviour in Haskell 98 and Haskell 2010
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section documents GHC's take on various issues that are left
+undefined or implementation specific in Haskell 98.
+
+``Char``
+    .. index::
+       single: Char; size of
+
+    Following the ISO-10646 standard, ``maxBound :: Char`` in GHC is
+    ``0x10FFFF``.
+
+``Int``
+    .. index::
+       single: Int; size of
+       single: fromInteger function
+       single: fromIntegral function
+
+    In GHC the ``Int`` type follows the size of an address on the host
+    architecture; in other words it holds 32 bits on a 32-bit machine,
+    and 64-bits on a 64-bit machine.
+
+    Arithmetic on ``Int`` is unchecked for overflowoverflow\ ``Int``, so
+    all operations on ``Int`` happen modulo 2\ :sup:`⟨n⟩` where ⟨n⟩ is
+    the size in bits of the ``Int`` type.
+
+    The ``fromInteger`` (and hence also ``fromIntegral``) is a special case when
+    converting to ``Int``. The value of ``fromIntegral x :: Int`` is
+    given by taking the lower ⟨n⟩ bits of ``(abs x)``, multiplied by the
+    sign of ``x`` (in 2's complement ⟨n⟩-bit arithmetic). This behaviour
+    was chosen so that for example writing ``0xffffffff :: Int``
+    preserves the bit-pattern in the resulting ``Int``.
+
+    Negative literals, such as ``-3``, are specified by (a careful
+    reading of) the Haskell Report as meaning
+    ``Prelude.negate (Prelude.fromInteger 3)``. So ``-2147483648`` means
+    ``negate (fromInteger 2147483648)``. Since ``fromInteger`` takes the
+    lower 32 bits of the representation,
+    ``fromInteger (2147483648::Integer)``, computed at type ``Int`` is
+    ``-2147483648::Int``. The ``negate`` operation then overflows, but
+    it is unchecked, so ``negate (-2147483648::Int)`` is just
+    ``-2147483648``. In short, one can write ``minBound::Int`` as a
+    literal with the expected meaning (but that is not in general
+    guaranteed).
+
+    The ``fromIntegral`` function also preserves bit-patterns when
+    converting between the sized integral types (``Int8``, ``Int16``,
+    ``Int32``, ``Int64`` and the unsigned ``Word`` variants), see the
+    modules ``Data.Int`` and ``Data.Word`` in the library documentation.
+
+Unchecked floating-point arithmetic
+    Operations on ``Float`` and ``Double`` numbers are *unchecked* for
+    overflow, underflow, and other sad occurrences. (note, however, that
+    some architectures trap floating-point overflow and
+    loss-of-precision and report a floating-point exception, probably
+    terminating the program)
+
+    .. index::
+        single: floating-point exceptions.
+
+.. _bugs:
+
+Known bugs or infelicities
+--------------------------
+
+The bug tracker lists bugs that have been reported in GHC but not yet
+fixed: see the `GHC Trac <http://ghc.haskell.org/trac/ghc/>`__. In
+addition to those, GHC also has the following known bugs or
+infelicities. These bugs are more permanent; it is unlikely that any of
+them will be fixed in the short term.
+
+.. _bugs-ghc:
+
+Bugs in GHC
+~~~~~~~~~~~
+
+-  GHC's runtime system implements cooperative multitasking, with
+   context switching potentially occurring only when a program
+   allocates. This means that programs that do not allocate may never
+   context switch. See :ghc-ticket:`367` for further discussion.
+
+   If you are hit by this, you may want to compile the affected module
+   with ``-fno-omit-yields``. This flag ensures that yield points are
+   inserted at every function entrypoint (at the expense of a bit of
+   performance).
+
+-  GHC can warn about non-exhaustive or overlapping patterns (see
+   :ref:`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 really.
+
+-  GHC does not allow you to have a data type with a context that
+   mentions type variables that are not data type parameters. For
+   example:
+
+   ::
+
+         data C a b => T a = MkT a
+
+   so that ``MkT``\'s type is
+
+   ::
+
+         MkT :: forall a b. C a b => a -> T a
+
+   In principle, with a suitable class declaration with a functional
+   dependency, it's possible that this type is not ambiguous; but GHC
+   nevertheless rejects it. The type variables mentioned in the context
+   of the data type declaration must be among the type parameters of the
+   data type.
+
+-  GHC's inliner can be persuaded into non-termination using the
+   standard way to encode recursion via a data type:
+
+   ::
+
+         data U = MkU (U -> Bool)
+
+         russel :: U -> Bool
+         russel u@(MkU p) = not $ p u
+
+         x :: Bool
+         x = russel (MkU russel)
+
+   The non-termination is reported like this:
+
+   ::
+
+       ghc: panic! (the 'impossible' happened)
+         (GHC version 7.10.1 for x86_64-unknown-linux):
+           Simplifier ticks exhausted
+         When trying UnfoldingDone x_alB
+         To increase the limit, use -fsimpl-tick-factor=N (default 100)
+
+   with the panic being reported no matter how high a
+   ``-fsimpl-tick-factor`` you supply.
+
+   We have never found another class of programs, other than this
+   contrived one, that makes GHC diverge, and fixing the problem would
+   impose an extra overhead on every compilation. So the bug remains
+   un-fixed. There is more background in `Secrets of the GHC
+   inliner <http://research.microsoft.com/~simonpj/Papers/inlining/>`__.
+
+-  On 32-bit x86 platforms when using the native code generator, the
+   ``-fexcess-precision``\ ``-fexcess-precision`` option is always on.
+   This means that floating-point calculations are non-deterministic,
+   because depending on how the program is compiled (optimisation
+   settings, for example), certain calculations might be done at 80-bit
+   precision instead of the intended 32-bit or 64-bit precision.
+   Floating-point results may differ when optimisation is turned on. In
+   the worst case, referential transparency is violated, because for
+   example ``let x = E1 in E2`` can evaluate to a different value than
+   ``E2[E1/x]``.
+
+   .. index::
+      single: -msse2 option
+
+   One workaround is to use the ``-msse2`` option (see
+   :ref:`options-platform`, which generates code to use the SSE2
+   instruction set instead of the x87 instruction set. SSE2 code uses
+   the correct precision for all floating-point operations, and so gives
+   deterministic results. However, note that this only works with
+   processors that support SSE2 (Intel Pentium 4 or AMD Athlon 64 and
+   later), which is why the option is not enabled by default. The
+   libraries that come with GHC are probably built without this option,
+   unless you built GHC yourself.
+
+.. _bugs-ghci:
+
+Bugs in GHCi (the interactive GHC)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  GHCi does not respect the ``default`` declaration in the module whose
+   scope you are in. Instead, for expressions typed at the command line,
+   you always get the default default-type behaviour; that is,
+   ``default(Int,Double)``.
+
+   It would be better for GHCi to record what the default settings in
+   each module are, and use those of the 'current' module (whatever that
+   is).
+
+-  On Windows, there's a GNU ld/BFD bug whereby it emits bogus PE object
+   files that have more than 0xffff relocations. When GHCi tries to load
+   a package affected by this bug, you get an error message of the form
+
+   ::
+
+       Loading package javavm ... linking ... WARNING: Overflown relocation field (# relocs found: 30765)
+
+   The last time we looked, this bug still wasn't fixed in the BFD
+   codebase, and there wasn't any noticeable interest in fixing it when
+   we reported the bug back in 2001 or so.
+
+   The workaround is to split up the .o files that make up your package
+   into two or more .o's, along the lines of how the ``base`` package does
+   it.
diff --git a/docs/users_guide/bugs.xml b/docs/users_guide/bugs.xml
deleted file mode 100644 (file)
index bff2bcf..0000000
+++ /dev/null
@@ -1,638 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<chapter id="bugs-and-infelicities">
-  <title>Known bugs and infelicities</title>
-
-  <sect1 id="vs-Haskell-defn">
-    <title>Haskell&nbsp;standards vs.&nbsp;Glasgow Haskell: language non-compliance
-</title>
-
-    <indexterm><primary>GHC vs the Haskell standards</primary></indexterm>
-    <indexterm><primary>Haskell standards vs GHC</primary></indexterm>
-
-    <para>
-        This section lists Glasgow Haskell infelicities in its
-        implementation of Haskell&nbsp;98 and Haskell&nbsp;2010.
-        See also the &ldquo;when things 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
-        (roughly).
-    </para>
-
-  <sect2 id="haskell-standards-divergence">
-    <title>Divergence from Haskell&nbsp;98 and Haskell&nbsp;2010</title>
-
-    <para>
-        By default, GHC mainly aims to behave (mostly) like a Haskell&nbsp;2010
-        compiler, although you can tell it to try to behave like a
-        particular version of the language with the
-        <literal>-XHaskell98</literal> and
-        <literal>-XHaskell2010</literal> flags. The known deviations
-        from the standards are described below. Unless otherwise stated,
-        the deviation applies in Haskell&nbsp;98, Haskell&nbsp;2010 and
-        the default modes.
-    </para>
-
-    <sect3 id="infelicities-lexical">
-      <title>Lexical syntax</title>
-
-      <itemizedlist>
-       <listitem>
-         <para>Certain lexical rules regarding qualified identifiers
-         are slightly different in GHC compared to the Haskell
-         report.  When you have
-         <replaceable>module</replaceable><literal>.</literal><replaceable>reservedop</replaceable>,
-         such as <literal>M.\</literal>, GHC will interpret it as a
-         single qualified operator rather than the two lexemes
-         <literal>M</literal> and <literal>.\</literal>.</para>
-       </listitem>
-      </itemizedlist>
-    </sect3>
-
-      <sect3 id="infelicities-syntax">
-       <title>Context-free syntax</title>
-
-       <itemizedlist>
-         <listitem>
-           <para>In Haskell&nbsp;98 mode and by default (but not in
-          Haskell&nbsp;2010 mode), GHC is a little less strict about the
-          layout rule when used
-             in <literal>do</literal> expressions.  Specifically, the
-             restriction that "a nested context must be indented further to
-             the right than the enclosing context" is relaxed to allow the
-             nested context to be at the same level as the enclosing context,
-             if the enclosing context is a <literal>do</literal>
-             expression.</para>
-
-           <para>For example, the following code is accepted by GHC:
-
-<programlisting>
-main = do args &lt;- getArgs
-          if null args then return [] else do
-          ps &lt;- mapM process args
-          mapM print ps</programlisting>
-
-        This behaviour is controlled by the
-        <literal>NondecreasingIndentation</literal> extension.
-             </para>
-         </listitem>
-
-       <listitem>
-         <para>GHC doesn't do the fixity resolution in expressions during
-         parsing as required by Haskell&nbsp;98 (but not by Haskell&nbsp;2010).
-      For example, according to the Haskell&nbsp;98 report, the
-         following expression is legal:
-<programlisting>
-    let x = 42 in x == 42 == True</programlisting>
-       and parses as:
-<programlisting>
-    (let x = 42 in x == 42) == True</programlisting>
-
-          because according to the report, the <literal>let</literal>
-         expression <quote>extends as far to the right as
-         possible</quote>.  Since it can't extend past the second
-         equals sign without causing a parse error
-         (<literal>==</literal> is non-fix), the
-         <literal>let</literal>-expression must terminate there.  GHC
-         simply gobbles up the whole expression, parsing like this:
-<programlisting>
-    (let x = 42 in x == 42 == True)</programlisting></para>
-       </listitem>
-
-       <listitem>
-         <para>The Haskell Report allows you to put a unary
-         <literal>-</literal> preceding certain expressions headed by
-         keywords, allowing constructs like <literal>- case x of
-         ...</literal> or <literal>- do { ... }</literal>. GHC does
-         not allow this. Instead, unary <literal>-</literal> is
-         allowed before only expressions that could potentially
-         be applied as a function.
-         </para>
-       </listitem>
-
-      </itemizedlist>
-    </sect3>
-
-  <sect3 id="infelicities-exprs-pats">
-      <title>Expressions and patterns</title>
-
-    <para>In its default mode, GHC makes some programs slightly more defined
-    than they should be. For example, consider
-    <programlisting>
-f :: [a] -> b -> b
-f [] = error "urk"
-f (x:xs) = \v -> v
-
-main = print (f [] `seq` True)
-    </programlisting>
-This should call <literal>error</literal> but actually prints <literal>True</literal>.
-Reason: GHC eta-expands <literal>f</literal> to
-    <programlisting>
-f :: [a] -> b -> b
-f []     v = error "urk"
-f (x:xs) v = v
-    </programlisting>
-This improves efficiency slightly but significantly for most programs, and
-is bad for only a few.  To suppress this bogus "optimisation" use <option>-fpedantic-bottoms</option>.
-</para>
-
-    </sect3>
-
-    <sect3 id="infelicities-decls">
-      <title>Declarations and bindings</title>
-
-      <para>In its default mode, GHC does not accept datatype contexts,
-      as it has been decided to remove them from the next version of the
-      language standard. This behaviour can be controlled with the
-      <option>DatatypeContexts</option> extension.
-      See <xref linkend="datatype-contexts" />.</para>
-    </sect3>
-
-      <sect3 id="infelicities-Modules">
-       <title>Module system and interface files</title>
-
-       <para>GHC requires the use of <literal>hs-boot</literal>
-         files to cut the recursive loops among mutually recursive modules
-         as described in <xref linkend="mutual-recursion"/>.  This more of an infelicity
-           than a bug: the Haskell Report says
-         (<ulink url="http://haskell.org/onlinereport/modules.html#sect5.7">Section 5.7</ulink>) "Depending on the Haskell
-       implementation used, separate compilation of mutually
-       recursive modules may require that imported modules contain
-       additional information so that they may be referenced before
-       they are compiled. Explicit type signatures for all exported
-       values may be necessary to deal with mutual recursion. The
-       precise details of separate compilation are not defined by
-       this Report."
-
-       </para>
-
-    </sect3>
-
-    <sect3 id="infelicities-numbers">
-      <title>Numbers, basic types, and built-in classes</title>
-
-      <variablelist>
-       <varlistentry>
-         <term>Num superclasses</term>
-         <listitem>
-           <para>
-              The <literal>Num</literal> class does not have
-              <literal>Show</literal> or <literal>Eq</literal>
-              superclasses.
-            </para>
-
-           <para>
-              You can make code that works with both
-              Haskell98/Haskell2010 and GHC by:
-              <itemizedlist>
-                <listitem>
-                  <para>
-                    Whenever you make a <literal>Num</literal> instance
-                    of a type, also make <literal>Show</literal> and
-                    <literal>Eq</literal> instances, and
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    Whenever you give a function, instance or class a
-                    <literal>Num t</literal> constraint, also give it
-                    <literal>Show t</literal> and
-                    <literal>Eq t</literal> constraints.
-                  </para>
-                </listitem>
-              </itemizedlist>
-            </para>
-           </listitem>
-         </varlistentry>
-
-       <varlistentry>
-         <term>Bits superclasses</term>
-         <listitem>
-           <para>
-              The <literal>Bits</literal> class does not have
-              a <literal>Num</literal> superclasses. It therefore
-              does not have default methods for the
-              <literal>bit</literal>,
-              <literal>testBit</literal> and
-              <literal>popCount</literal> methods.
-            </para>
-
-           <para>
-              You can make code that works with both
-              Haskell2010 and GHC by:
-              <itemizedlist>
-                <listitem>
-                  <para>
-                    Whenever you make a <literal>Bits</literal> instance
-                    of a type, also make a <literal>Num</literal>
-                    instance, and
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    Whenever you give a function, instance or class a
-                    <literal>Bits t</literal> constraint, also give it
-                    a <literal>Num t</literal> constraint, and
-                  </para>
-                </listitem>
-                <listitem>
-                  <para>
-                    Always define the <literal>bit</literal>,
-                    <literal>testBit</literal> and
-                    <literal>popCount</literal> methods in
-                    <literal>Bits</literal> instances.
-                  </para>
-                </listitem>
-              </itemizedlist>
-            </para>
-           </listitem>
-         </varlistentry>
-
-       <varlistentry>
-         <term>Extra instances</term>
-         <listitem>
-           <para>
-              The following extra instances are defined:
-            </para>
-<programlisting>
-instance Functor ((->) r)
-instance Monad ((->) r)
-instance Functor ((,) a)
-instance Functor (Either a)
-instance Monad (Either e)
-</programlisting>
-           </listitem>
-         </varlistentry>
-
-       <varlistentry>
-         <term>Multiply-defined array elements&mdash;not checked:</term>
-         <listitem>
-           <para>This code fragment should
-           elicit a fatal error, but it does not:
-
-<programlisting>
-main = print (array (1,1) [(1,2), (1,3)])</programlisting>
-GHC's implementation of <literal>array</literal> takes the value of an
-array slot from the last (index,value) pair in the list, and does no
-checking for duplicates.  The reason for this is efficiency, pure and simple.
-            </para>
-         </listitem>
-       </varlistentry>
-      </variablelist>
-
-    </sect3>
-
-      <sect3 id="infelicities-Prelude">
-       <title>In <literal>Prelude</literal> support</title>
-
-      <variablelist>
-       <varlistentry>
-         <term>Arbitrary-sized tuples</term>
-         <listitem>
-           <para>Tuples are currently limited to size 100.  HOWEVER:
-            standard instances for tuples (<literal>Eq</literal>,
-            <literal>Ord</literal>, <literal>Bounded</literal>,
-            <literal>Ix</literal> <literal>Read</literal>, and
-            <literal>Show</literal>) are available
-            <emphasis>only</emphasis> up to 16-tuples.</para>
-
-           <para>This limitation is easily subvertible, so please ask
-            if you get stuck on it.</para>
-           </listitem>
-         </varlistentry>
-          <varlistentry>
-            <term><literal>splitAt</literal> semantics</term>
-            <para><literal>Data.List.splitAt</literal> is stricter than specified in the
-            Report. Specifically, the Report specifies that
-<programlisting>splitAt n xs = (take n xs, drop n xs)</programlisting>
-            which implies that
-<programlisting>splitAt undefined undefined = (undefined, undefined)</programlisting>
-            but GHC's implementation is strict in its first argument, so
-<programlisting>splitAt undefined [] = undefined</programlisting>
-            </para>
-          </varlistentry>
-         <varlistentry>
-           <term><literal>Read</literal>ing integers</term>
-           <listitem>
-             <para>GHC's implementation of the
-             <literal>Read</literal> class for integral types accepts
-             hexadecimal and octal literals (the code in the Haskell
-             98 report doesn't).  So, for example,
-<programlisting>read "0xf00" :: Int</programlisting>
-              works in GHC.</para>
-             <para>A possible reason for this is that <literal>readLitChar</literal> accepts hex and
-               octal escapes, so it seems inconsistent not to do so for integers too.</para>
-           </listitem>
-         </varlistentry>
-
-         <varlistentry>
-           <term><literal>isAlpha</literal></term>
-           <listitem>
-             <para>The Haskell 98 definition of <literal>isAlpha</literal>
-              is:</para>
-
-<programlisting>isAlpha c = isUpper c || isLower c</programlisting>
-
-             <para>GHC's implementation diverges from the Haskell 98
-              definition in the sense that Unicode alphabetic characters which
-              are neither upper nor lower case will still be identified as
-              alphabetic by <literal>isAlpha</literal>.</para>
-           </listitem>
-         </varlistentry>
-
-          <varlistentry>
-            <term><literal>hGetContents</literal></term>
-            <listitem>
-              <para>
-                Lazy I/O throws an exception if an error is
-                encountered, in contrast to the Haskell 98 spec which
-                requires that errors are discarded (see Section 21.2.2
-                of the Haskell 98 report).  The exception thrown is
-                the usual IO exception that would be thrown if the
-                failing IO operation was performed in the IO monad, and can
-                be caught by <literal>System.IO.Error.catch</literal>
-                or <literal>Control.Exception.catch</literal>.
-              </para>
-            </listitem>
-          </varlistentry>
-       </variablelist>
-    </sect3>
-
-    <sect3 id="infelicities-ffi">
-      <title>The Foreign Function Interface</title>
-      <variablelist>
-      <varlistentry>
-        <term><literal>hs_init()</literal> not allowed
-        after <literal>hs_exit()</literal></term>
-        <listitem>
-          <para>The FFI spec requires the implementation to support
-            re-initialising itself after being shut down
-            with <literal>hs_exit()</literal>, but GHC does not
-            currently support that.</para>
-        </listitem>
-      </varlistentry>
-    </variablelist>
-    </sect3>
-
-  </sect2>
-
-  <sect2 id="haskell-98-2010-undefined">
-    <title>GHC's interpretation of undefined behaviour in
-    Haskell&nbsp;98 and Haskell&nbsp;2010</title>
-
-    <para>This section documents GHC's take on various issues that are
-    left undefined or implementation specific in Haskell 98.</para>
-
-    <variablelist>
-      <varlistentry>
-       <term>
-          The <literal>Char</literal> type
-          <indexterm><primary><literal>Char</literal></primary><secondary>size of</secondary></indexterm>
-        </term>
-       <listitem>
-         <para>Following the ISO-10646 standard,
-         <literal>maxBound :: Char</literal> in GHC is
-         <literal>0x10FFFF</literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          Sized integral types
-          <indexterm><primary><literal>Int</literal></primary><secondary>size of</secondary></indexterm>
-       </term>
-       <listitem>
-         <para>In GHC the <literal>Int</literal> type follows the
-         size of an address on the host architecture; in other words
-         it holds 32 bits on a 32-bit machine, and 64-bits on a
-         64-bit machine.</para>
-
-         <para>Arithmetic on <literal>Int</literal> is unchecked for
-         overflow<indexterm><primary>overflow</primary><secondary><literal>Int</literal></secondary>
-           </indexterm>, so all operations on <literal>Int</literal> happen
-         modulo
-         2<superscript><replaceable>n</replaceable></superscript>
-         where <replaceable>n</replaceable> is the size in bits of
-         the <literal>Int</literal> type.</para>
-
-         <para>The <literal>fromInteger</literal><indexterm><primary><literal>fromInteger</literal></primary>
-           </indexterm> function (and hence
-         also <literal>fromIntegral</literal><indexterm><primary><literal>fromIntegral</literal></primary>
-           </indexterm>) is a special case when
-         converting to <literal>Int</literal>.  The value of
-         <literal>fromIntegral x :: Int</literal> is given by taking
-         the lower <replaceable>n</replaceable> bits of <literal>(abs
-         x)</literal>, multiplied by the sign of <literal>x</literal>
-         (in 2's complement <replaceable>n</replaceable>-bit
-         arithmetic).  This behaviour was chosen so that for example
-         writing <literal>0xffffffff :: Int</literal> preserves the
-         bit-pattern in the resulting <literal>Int</literal>.</para>
-
-
-          <para>Negative literals, such as <literal>-3</literal>, are
-             specified by (a careful reading of) the Haskell Report as
-             meaning <literal>Prelude.negate (Prelude.fromInteger 3)</literal>.
-            So <literal>-2147483648</literal> means <literal>negate (fromInteger 2147483648)</literal>.
-            Since <literal>fromInteger</literal> takes the lower 32 bits of the representation,
-            <literal>fromInteger (2147483648::Integer)</literal>, computed at type <literal>Int</literal> is
-            <literal>-2147483648::Int</literal>.  The <literal>negate</literal> operation then
-            overflows, but it is unchecked, so <literal>negate (-2147483648::Int)</literal> is just
-            <literal>-2147483648</literal>.  In short, one can write <literal>minBound::Int</literal> as
-            a literal with the expected meaning (but that is not in general guaranteed).
-             </para>
-
-         <para>The <literal>fromIntegral</literal> function also
-         preserves bit-patterns when converting between the sized
-         integral types (<literal>Int8</literal>,
-         <literal>Int16</literal>, <literal>Int32</literal>,
-         <literal>Int64</literal> and the unsigned
-         <literal>Word</literal> variants), see the modules
-         <literal>Data.Int</literal> and <literal>Data.Word</literal>
-         in the library documentation.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>Unchecked float arithmetic</term>
-       <listitem>
-         <para>Operations on <literal>Float</literal> and
-          <literal>Double</literal> numbers are
-          <emphasis>unchecked</emphasis> for overflow, underflow, and
-          other sad occurrences.  (note, however, that some
-          architectures trap floating-point overflow and
-          loss-of-precision and report a floating-point exception,
-          probably terminating the
-          program)<indexterm><primary>floating-point
-          exceptions</primary></indexterm>.</para>
-       </listitem>
-      </varlistentry>
-    </variablelist>
-  </sect2>
-
-  </sect1>
-
-
-  <sect1 id="bugs">
-    <title>Known bugs or infelicities</title>
-
-    <para>The bug tracker lists bugs that have been reported in GHC but not
-      yet fixed: see the <ulink url="http://ghc.haskell.org/trac/ghc/">GHC Trac</ulink>.  In addition to those, GHC also has the following known bugs
-      or  infelicities.  These bugs are more permanent; it is unlikely that
-      any of them will be fixed in the short term.</para>
-
-  <sect2 id="bugs-ghc">
-    <title>Bugs in GHC</title>
-
-    <itemizedlist>
-      <listitem>
-        <para>GHC's runtime system implements cooperative multitasking, with
-        context switching potentially occurring only when a program allocates.
-        This means that programs that do not allocate may never context switch.
-        See
-        <ulink url="https://ghc.haskell.org/trac/ghc/ticket/367">Trac #367</ulink>
-        for further discussion.
-        </para>
-        <para>If you are hit by this, you may want to compile the affected module
-        with <literal>-fno-omit-yields</literal>. This flag ensures that yield points
-        are inserted at every function entrypoint (at the expense of a bit of
-        performance).
-        </para>
-      </listitem>
-
-      <listitem>
-       <para> GHC can warn about non-exhaustive or overlapping
-        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
-        really.</para>
-      </listitem>
-
-      <listitem>
-       <para>GHC does not allow you to have a data type with a context
-          that mentions type variables that are not data type parameters.
-         For example:
-<programlisting>
-  data C a b => T a = MkT a
-</programlisting>
-         so that <literal>MkT</literal>'s type is
-<programlisting>
-  MkT :: forall a b. C a b => a -> T a
-</programlisting>
-        In principle, with a suitable class declaration with a functional dependency,
-        it's possible that this type is not ambiguous; but GHC nevertheless rejects
-         it.  The type variables mentioned in the context of the data type declaration must
-       be among the type parameters of the data type.</para>
-      </listitem>
-
-      <listitem>
-       <para>GHC's inliner can be persuaded into non-termination
-        using the standard way to encode recursion via a data type:
-<programlisting>
-  data U = MkU (U -> Bool)
-
-  russel :: U -> Bool
-  russel u@(MkU p) = not $ p u
-
-  x :: Bool
-  x = russel (MkU russel)
-</programlisting>
-        The non-termination is reported like this:
-<programlisting>
-ghc: panic! (the 'impossible' happened)
-  (GHC version 7.10.1 for x86_64-unknown-linux):
-       Simplifier ticks exhausted
-  When trying UnfoldingDone x_alB
-  To increase the limit, use -fsimpl-tick-factor=N (default 100)
-</programlisting>
-        with the panic being reported no matter how high a <literal>-fsimpl-tick-factor</literal> you supply.
-        </para>
-        <para>
-        We have never found another class of programs, other
-        than this contrived one, that makes GHC diverge, and fixing
-        the problem would impose an extra overhead on every
-        compilation.  So the bug remains un-fixed.  There is more
-        background in <ulink
-        url="http://research.microsoft.com/~simonpj/Papers/inlining/">
-        Secrets of the GHC inliner</ulink>.</para>
-      </listitem>
-
-      <listitem>
-        <para>On 32-bit x86 platforms when using the native code
-        generator, the
-        <option>-fexcess-precision</option><indexterm><primary><option>-fexcess-precision</option></primary></indexterm> option
-        is always on.  This means that floating-point calculations are
-        non-deterministic, because depending on how the program is
-        compiled (optimisation settings, for example), certain
-        calculations might be done at 80-bit precision instead of the
-        intended 32-bit or 64-bit precision.  Floating-point results
-        may differ when optimisation is turned on.  In the worst case,
-        referential transparency is violated, because for example
-        <literal>let x = E1 in E2</literal> can evaluate to a
-        different value than <literal>E2[E1/x]</literal>.</para>
-
-        <para>
-          One workaround is to use the
-          <option>-msse2</option><indexterm><primary><option>-msse2</option></primary></indexterm>
-          option (see <xref linkend="options-platform" />, which
-          generates code to use the SSE2 instruction set instead of
-          the x87 instruction set.  SSE2 code uses the correct
-          precision for all floating-point operations, and so gives
-          deterministic results.  However, note that this only works
-          with processors that support SSE2 (Intel Pentium 4 or AMD
-          Athlon 64 and later), which is why the option is not enabled
-          by default.  The libraries that come with GHC are probably
-          built without this option, unless you built GHC yourself.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-  </sect2>
-
-  <sect2 id="bugs-ghci">
-    <title>Bugs in GHCi (the interactive GHC)</title>
-    <itemizedlist>
-      <listitem>
-       <para>GHCi does not respect the <literal>default</literal>
-        declaration in the module whose scope you are in.  Instead,
-        for expressions typed at the command line, you always get the
-        default default-type behaviour; that is,
-        <literal>default(Int,Double)</literal>.</para>
-
-       <para>It would be better for GHCi to record what the default
-        settings in each module are, and use those of the 'current'
-        module (whatever that is).</para>
-      </listitem>
-
-      <listitem>
-      <para>On Windows, there's a GNU ld/BFD bug
-      whereby it emits bogus PE object files that have more than
-      0xffff relocations. When GHCi tries to load a package affected by this
-      bug, you get an error message of the form
-<screen>
-Loading package javavm ... linking ... WARNING: Overflown relocation field (# relocs found: 30765)
-</screen>
-      The last time we looked, this bug still
-      wasn't fixed in the BFD codebase, and there wasn't any
-      noticeable interest in fixing it when we reported the bug
-      back in 2001 or so.
-      </para>
-      <para>The workaround is to split up the .o files that make up
-      your package into two or more .o's, along the lines of
-      how the "base" package does it.</para>
-      </listitem>
-    </itemizedlist>
-  </sect2>
-  </sect1>
-
-</chapter>
-
-<!-- Emacs stuff:
-     ;;; Local Variables: ***
-     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
-     ;;; ispell-local-dictionary: "british" ***
-     ;;; End: ***
- -->
diff --git a/docs/users_guide/codegens.rst b/docs/users_guide/codegens.rst
new file mode 100644 (file)
index 0000000..9915452
--- /dev/null
@@ -0,0 +1,115 @@
+.. _code-generators:
+
+GHC Backends
+============
+
+.. index::
+   single: GHC backends
+   single: GHC code generators
+
+GHC supports multiple backend code generators. This is the part of the
+compiler responsible for taking the last intermediate representation
+that GHC uses (a form called Cmm that is a simple, C like language) and
+compiling it to executable code. The backends that GHC support are
+described below.
+
+.. _native-code-gen:
+
+Native code Generator (``-fasm``)
+---------------------------------
+
+.. index::
+   single: native code generator
+
+The default backend for GHC. It is a native code generator, compiling
+Cmm all the way to assembly code. It is the fastest backend and
+generally produces good performance code. It has the best support for
+compiling shared libraries. Select it with the ``-fasm`` flag.
+
+.. _llvm-code-gen:
+
+LLVM Code Generator (``-fllvm``)
+--------------------------------
+
+.. index::
+   single: LLVM code generator
+
+This is an alternative backend that uses the `LLVM <http://llvm.org>`__
+compiler to produce executable code. It generally produces code as with
+performance as good as the native code generator but for some cases can
+produce much faster code. This is especially true for numeric, array
+heavy code using packages like vector. The penalty is a significant
+increase in compilation times. Select the LLVM backend with the
+``-fllvm`` flag. Currently *LLVM 2.8* and later are supported.
+
+You must install and have LLVM available on your ``PATH`` for the LLVM code
+generator to work. Specifically GHC needs to be able to call the ``opt``
+and ``llc`` tools. Secondly, if you are running Mac OS X with LLVM 3.0
+or greater then you also need the `Clang c
+compiler <http://clang.llvm.org>`__ compiler available on your ``PATH``.
+
+To install LLVM and Clang:
+
+-  *Linux*: Use your package management tool.
+
+-  *Mac OS X*: Clang is included by default on recent OS X machines when
+   XCode is installed (from ``10.6`` and later). LLVM is not included.
+   In order to use the LLVM based code generator, you should install the
+   `Homebrew <http://mxcl.github.com/homebrew/>`__ package manager for
+   OS X. Alternatively you can download binaries for LLVM and Clang from
+   `here <http://llvm.org/releases/download.html>`__.
+
+-  *Windows*: You should download binaries for LLVM and clang from
+   `here <http://llvm.org/releases/download.html>`__.
+
+.. _c-code-gen:
+
+C Code Generator (``-fvia-C``)
+------------------------------
+
+.. index::
+   single: C code generator
+   single: -fvia-C
+
+This is the oldest code generator in GHC and is generally not included
+any more having been deprecated around GHC 7.0. Select it with the
+``-fvia-C`` flag.
+
+The C code generator is only supported when GHC is built in
+unregisterised mode, a mode where GHC produces "portable" C code as
+output to facilitate porting GHC itself to a new platform. This mode
+produces much slower code though so it's unlikely your version of GHC
+was built this way. If it has then the native code generator probably
+won't be available. You can check this information by calling
+```ghc --info`` (see :ref:`ghc-info`).
+
+.. _unreg:
+
+Unregisterised compilation
+--------------------------
+
+.. index::
+   single: unregisterised compilation
+
+The term "unregisterised" really means "compile via vanilla C",
+disabling some of the platform-specific tricks that GHC normally uses to
+make programs go faster. When compiling unregisterised, GHC simply
+generates a C file which is compiled via gcc.
+
+When GHC is build in unregisterised mode only the LLVM and C code
+generators will be available. The native code generator won't be. LLVM
+usually offers a substantial performance benefit over the C backend in
+unregisterised mode.
+
+Unregisterised compilation can be useful when porting GHC to a new
+machine, since it reduces the prerequisite tools to ``gcc``, ``as``, and
+``ld`` and nothing more, and furthermore the amount of platform-specific
+code that needs to be written in order to get unregisterised compilation
+going is usually fairly small.
+
+Unregisterised compilation cannot be selected at compile-time; you have
+to build GHC with the appropriate options set. Consult the GHC Building
+Guide for details.
+
+You can check if your GHC is unregisterised by calling
+```ghc --info`` (see :ref:`ghc-info`).
diff --git a/docs/users_guide/codegens.xml b/docs/users_guide/codegens.xml
deleted file mode 100644 (file)
index d9c4859..0000000
+++ /dev/null
@@ -1,125 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<sect1 id="code-generators">
-  <title>GHC Backends</title>
-  <indexterm><primary>ghc backends</primary></indexterm>
-  <indexterm><primary>ghc code generators</primary></indexterm>
-  
-  <para>GHC supports multiple backend code generators. This is the part
-    of the compiler responsible for taking the last intermediate
-    representation that GHC uses (a form called Cmm that is a simple, C like
-    language) and compiling it to executable code. The backends that GHC
-    support are described below.
-  </para>
-
-  <sect2 id="native-code-gen">
-    <title>Native code Generator (<option>-fasm</option>)</title>
-    <indexterm><primary>native code generator</primary></indexterm>
-
-    The default backend for GHC. It is a native code generator, compiling Cmm
-    all the way to assembly code. It is the fastest backend and generally
-    produces good performance code. It has the best support for compiling
-    shared libraries. Select it with the <option>-fasm</option> flag.
-  </sect2>
-
-  <sect2 id="llvm-code-gen">
-    <title>LLVM Code Generator (<option>-fllvm</option>)</title>
-    <indexterm><primary>LLVM code generator</primary></indexterm>
-
-    <para>This is an alternative backend that uses the
-      <ulink url="http://llvm.org">LLVM</ulink> compiler to produce
-      executable code. It generally produces code as with performance as
-      good as the native code generator but for some cases can produce
-      much faster code. This is especially true for numeric, array heavy
-      code using packages like vector. The penalty is a significant increase in
-      compilation times. Select the LLVM backend with the
-      <option>-fllvm</option> flag. Currently <emphasis>LLVM 2.8</emphasis> and
-      later are supported.
-    </para>
-       
-    <para>You must install and have LLVM available on your PATH for the LLVM
-      code generator to work. Specifically GHC needs to be able to call the
-      <command>opt</command> and <command>llc</command> tools.  Secondly, if you
-      are running Mac OS X with LLVM 3.0 or greater then
-      you also need the <ulink url="http://clang.llvm.org">Clang c
-        compiler</ulink> compiler available on your PATH.
-    </para>
-
-    <para>To install LLVM and Clang:
-      <itemizedlist>
-        <listitem><para><emphasis>Linux</emphasis>: Use your package management tool.</para>
-        </listitem>
-        <listitem><para><emphasis>Mac OS X</emphasis>: Clang is included by
-        default on recent OS X machines when XCode is installed (from
-        <literal>10.6</literal> and later). LLVM is not included. In
-        order to use the LLVM based code generator, you should install
-        the <ulink
-        url="http://mxcl.github.com/homebrew/">Homebrew</ulink>
-        package manager for OS X. Alternatively you can download
-        binaries for LLVM and Clang from <ulink
-        url="http://llvm.org/releases/download.html">here</ulink>.</para>
-        </listitem>
-
-        <listitem><para><emphasis>Windows</emphasis>: You should download binaries for
-          LLVM and clang from
-          <ulink url="http://llvm.org/releases/download.html">here</ulink>.</para>
-        </listitem>
-      </itemizedlist>
-    </para>
-  </sect2>
-
-  <sect2 id="c-code-gen">
-    <title>C Code Generator (<option>-fvia-C</option>)</title>
-    <indexterm><primary>C code generator</primary></indexterm>
-    <indexterm><primary>-fvia-C</primary></indexterm>
-
-    <para>This is the oldest code generator in GHC and is generally not included
-      any more having been deprecated around GHC 7.0. Select it with the
-      <option>-fvia-C</option> flag.
-    </para>
-
-    <para>The C code generator is only supported when GHC is built in
-      unregisterised mode, a mode where GHC produces 'portable' C code as
-      output to facilitate porting GHC itself to a new platform. This mode
-      produces much slower code though so it's unlikely your version of
-      GHC was built this way. If it has then the native code generator
-      probably won't be available. You can check this information by calling
-      <link linkend="ghc-info"><literal>ghc --info</literal></link>.
-    </para>
-  </sect2>
-
-  <sect2 id="unreg">
-    <title>Unregisterised compilation</title>
-    <indexterm><primary>unregisterised compilation</primary></indexterm>
-
-    <para>The term "unregisterised" really means "compile via vanilla C",
-      disabling some of the platform-specific tricks that GHC normally uses to
-      make programs go faster.  When compiling unregisterised, GHC simply
-      generates a C file which is compiled via gcc.</para>
-    
-    <para>When GHC is build in unregisterised mode only the LLVM and C code
-      generators will be available. The native code generator won't be. LLVM
-      usually offers a substantial performance benefit over the C backend in
-      unregisterised mode.</para>
-
-    <para>Unregisterised compilation can be useful when porting GHC to a new
-      machine, since it reduces the prerequisite tools to
-      <command>gcc</command>, <command>as</command>, and <command>ld</command>
-      and nothing more, and furthermore the amount of platform-specific code
-      that needs to be written in order to get
-    unregisterised compilation going is usually fairly small.</para>
-
-    <para>Unregisterised compilation cannot be selected at compile-time; you
-      have to build GHC with the appropriate options set.  Consult the GHC
-      Building Guide for details.</para>
-
-    <para>You can check if your GHC is unregisterised by calling
-      <link linkend="ghc-info"><literal>ghc --info</literal></link>.</para>
-  </sect2>
-
-</sect1>
-
-<!-- Emacs stuff:
-     ;;; Local Variables: ***
-     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
-     ;;; End: ***
- -->
diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py
new file mode 100644 (file)
index 0000000..eef8f4c
--- /dev/null
@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+#
+# GHC Users Guide documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+import sys
+import os
+
+# Support for :base-ref:, etc.
+sys.path.insert(0, os.path.abspath('.'))
+from ghc_config import extlinks, version
+
+extensions = ['sphinx.ext.extlinks']
+
+templates_path = ['.templates']
+source_suffix = '.rst'
+source_encoding = 'utf-8-sig'
+master_doc = 'index'
+
+# General information about the project.
+project = u'Glasgow Haskell Compiler'
+copyright = u'2015, GHC Team'
+# N.B. version comes from ghc_config
+release = version  # The full version, including alpha/beta/rc tags.
+
+# Syntax highlighting
+highlight_language = 'haskell'
+pygments_style = 'colorful'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['.build', "*.gen.rst"]
+
+# -- Options for HTML output ---------------------------------------------
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "Glasgow Haskell Compiler <release> Users Guide"
+html_short_title = "GHC %s Users Guide" % release
+html_theme_path = ['.']
+html_theme = 'ghc-theme'
+html_logo = None
+html_static_path = ['images']
+# Convert quotes and dashes to typographically correct entities
+html_use_smartypants = True
+html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'GHCUsersGuide'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    'inputenv': '',
+    'utf8extra': '',
+    'preamble': '''
+\usepackage{fontspec}
+\setsansfont{DejaVu Sans}
+\setromanfont{DejaVu Serif}
+\setmonofont{DejaVu Sans Mono}
+''',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  ('index', 'users_guide.tex', u'GHC Users Guide Documentation',
+   u'GHC Team', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+latex_logo = 'images/logo.pdf'
+
+# If true, show page references after internal links.
+latex_show_pagerefs = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('ghc', 'ghc', 'the Glasgow Haskell Compiler', 'The GHC Team', 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'GHCUsersGuide', u'GHC Users Guide',
+   u'GHC Team', 'GHCUsersGuide', 'The Glasgow Haskell Compiler.',
+   'Compilers'),
+]
diff --git a/docs/users_guide/debugging.rst b/docs/users_guide/debugging.rst
new file mode 100644 (file)
index 0000000..9482b8e
--- /dev/null
@@ -0,0 +1,431 @@
+.. _options-debugging:
+
+Debugging the compiler
+======================
+
+.. index::
+   single: debugging options (for GHC)
+
+HACKER TERRITORY. HACKER TERRITORY. (You were warned.)
+
+.. _dumping-output:
+
+Dumping out compiler intermediate structures
+--------------------------------------------
+
+.. index::
+   single: dumping GHC intermediates
+   single: intermediate passes, output
+
+``-ddump-`` ⟨pass⟩
+    .. index::
+       single: -ddump options
+
+    Make a debugging dump after pass ``<pass>`` (may be common enough to
+    need a short form…). You can get all of these at once (*lots* of
+    output) by using ``-v5``, or most of them with ``-v4``. You can
+    prevent them from clogging up your standard output by passing
+    ``-ddump-to-file``. Some of the most useful ones are:
+
+    ``-ddump-parsed``
+        .. index::
+           single: -ddump-parsed
+
+        Dump parser output
+
+    ``-ddump-rn``
+        .. index::
+           single: -ddump-rn
+
+        Dump renamer output
+
+    ``-ddump-tc``
+        .. index::
+           single: -ddump-tc
+
+        Dump typechecker output
+
+    ``-ddump-splices``
+        .. index::
+           single: -ddump-splices
+
+        Dump Template Haskell expressions that we splice in, and what
+        Haskell code the expression evaluates to.
+
+    ``-ddump-types``
+        .. index::
+           single: -ddump-types
+
+        Dump a type signature for each value defined at the top level of
+        the module. The list is sorted alphabetically. Using
+        ``-dppr-debug`` dumps a type signature for all the imported and
+        system-defined things as well; useful for debugging the
+        compiler.
+
+    ``-ddump-deriv``
+        .. index::
+           single: -ddump-deriv
+
+        Dump derived instances
+
+    ``-ddump-ds``
+        .. index::
+           single: -ddump-ds
+
+        Dump desugarer output
+
+    ``-ddump-spec``
+        .. index::
+           single: -ddump-spec
+
+        Dump output of specialisation pass
+
+    ``-ddump-rules``
+        .. index::
+           single: -ddump-rules
+
+        Dumps all rewrite rules specified in this module; see
+        :ref:`controlling-rules`.
+
+    ``-ddump-rule-firings``
+        .. index::
+           single: -ddump-rule-firings
+
+        Dumps the names of all rules that fired in this module
+
+    ``-ddump-rule-rewrites``
+        .. index::
+           single: -ddump-rule-rewrites
+
+        Dumps detailed information about all rules that fired in this
+        module
+
+    ``-ddump-vect``
+        .. index::
+           single: -ddump-vect
+
+        Dumps the output of the vectoriser.
+
+    ``-ddump-simpl``
+        .. index::
+           single: -ddump-simpl
+
+        Dump simplifier output (Core-to-Core passes)
+
+    ``-ddump-inlinings``
+        .. index::
+           single: -ddump-inlinings
+
+        Dumps inlining info from the simplifier
+
+    ``-ddump-stranal``
+        .. index::
+           single: -ddump-stranal
+
+        Dump strictness analyser output
+
+    ``-ddump-strsigs``
+        .. index::
+           single: -ddump-strsigs
+
+        Dump strictness signatures
+
+    ``-ddump-cse``
+        .. index::
+           single: -ddump-cse
+
+        Dump common subexpression elimination (CSE) pass output
+
+    ``-ddump-worker-wrapper``
+        .. index::
+           single: -ddump-worker-wrapper
+
+        Dump worker/wrapper split output
+
+    ``-ddump-occur-anal``
+        .. index::
+           single: -ddump-occur-anal
+
+        Dump "occurrence analysis" output
+
+    ``-ddump-prep``
+        .. index::
+           single: -ddump-prep
+
+        Dump output of Core preparation pass
+
+    ``-ddump-stg``
+        .. index::
+           single: -ddump-stg
+
+        Dump output of STG-to-STG passes
+
+    ``-ddump-cmm``
+        .. index::
+           single: -ddump-cmm
+
+        Print the C-- code out.
+
+    ``-ddump-opt-cmm``
+        .. index::
+           single: -ddump-opt-cmm
+
+        Dump the results of C-- to C-- optimising passes.
+
+    ``-ddump-asm``
+        .. index::
+           single: -ddump-asm
+
+        Dump assembly language produced by the :ref:`native code
+        generator <native-code-gen>`
+
+    ``-ddump-llvm``
+        .. index::
+           single: -ddump-llvm
+
+        LLVM code from the :ref:`LLVM code generator <llvm-code-gen>`
+
+    ``-ddump-bcos``
+        .. index::
+           single: -ddump-bcos
+
+        Dump byte-code compiler output
+
+    ``-ddump-foreign``
+        .. index::
+           single: -ddump-foreign
+
+        dump foreign export stubs
+
+``-ddump-simpl-iterations``
+    .. index::
+       single: -ddump-simpl-iterations
+
+    Show the output of each *iteration* of the simplifier (each run of
+    the simplifier has a maximum number of iterations, normally 4). This
+    outputs even more information than ``-ddump-simpl-phases``.
+
+``-ddump-simpl-stats``
+    .. index::
+       single: -ddump-simpl-stats option
+
+    Dump statistics about how many of each kind of transformation too
+    place. If you add ``-dppr-debug`` you get more detailed information.
+
+``-ddump-if-trace``
+    .. index::
+       single: -ddump-if-trace
+
+    Make the interface loader be *real* chatty about what it is up to.
+
+``-ddump-tc-trace``
+    .. index::
+       single: -ddump-tc-trace
+
+    Make the type checker be *real* chatty about what it is up to.
+
+``-ddump-vt-trace``
+    .. index::
+       single: -ddump-tv-trace
+
+    Make the vectoriser be *real* chatty about what it is up to.
+
+``-ddump-rn-trace``
+    .. index::
+       single: -ddump-rn-trace
+
+    Make the renamer be *real* chatty about what it is up to.
+
+``-ddump-rn-stats``
+    .. index::
+       single: -dshow-rn-stats
+
+    Print out summary of what kind of information the renamer had to
+    bring in.
+
+``-dverbose-core2core``, ``-dverbose-stg2stg``
+    .. index::
+       single: -dverbose-core2core
+       single: -dverbose-stg2stg
+
+    Show the output of the intermediate Core-to-Core and STG-to-STG
+    passes, respectively. (*lots* of output!) So: when we're really
+    desperate:
+
+    ::
+
+        % ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
+
+``-dshow-passes``
+    .. index::
+       single: -dshow-passes
+
+    Print out each pass name as it happens.
+
+``-ddump-core-stats``
+    .. index::
+       single: -ddump-core-stats
+
+    Print a one-line summary of the size of the Core program at the end
+    of the optimisation pipeline.
+
+``-dfaststring-stats``
+    .. index::
+       single: -dfaststring-stats
+
+    Show statistics on the usage of fast strings by the compiler.
+
+``-dppr-debug``
+    .. index::
+       single: -dppr-debug
+
+    Debugging output is in one of several "styles." Take the printing of
+    types, for example. In the "user" style (the default), the
+    compiler's internal ideas about types are presented in Haskell
+    source-level syntax, insofar as possible. In the "debug" style
+    (which is the default for debugging output), the types are printed
+    in with explicit foralls, and variables have their unique-id
+    attached (so you can check for things that look the same but
+    aren't). This flag makes debugging output appear in the more verbose
+    debug style.
+
+.. _formatting dumps:
+
+Formatting dumps
+----------------
+
+.. index::
+   single: formatting dumps
+
+``-dppr-user-length``
+    .. index::
+       single: -dppr-user-length
+
+    In error messages, expressions are printed to a certain "depth",
+    with subexpressions beyond the depth replaced by ellipses. This flag
+    sets the depth. Its default value is 5.
+
+``-dppr-colsNNN``
+    .. index::
+       single: -dppr-colsNNN
+
+    Set the width of debugging output. Use this if your code is wrapping
+    too much. For example: ``-dppr-cols200``.
+
+``-dppr-case-as-let``
+    .. index::
+       single: -dppr-case-as-let
+
+    Print single alternative case expressions as though they were strict
+    let expressions. This is helpful when your code does a lot of
+    unboxing.
+
+``-dno-debug-output``
+    .. index::
+       single: -dno-debug-output
+
+    Suppress any unsolicited debugging output. When GHC has been built
+    with the ``DEBUG`` option it occasionally emits debug output of
+    interest to developers. The extra output can confuse the testing
+    framework and cause bogus test failures, so this flag is provided to
+    turn it off.
+
+.. _suppression:
+
+Suppressing unwanted information
+--------------------------------
+
+.. index::
+   single: suppression; of unwanted dump output
+
+Core dumps contain a large amount of information. Depending on what you
+are doing, not all of it will be useful. Use these flags to suppress the
+parts that you are not interested in.
+
+``-dsuppress-all``
+    .. index::
+       single: -dsuppress-all
+
+    Suppress everything that can be suppressed, except for unique ids as
+    this often makes the printout ambiguous. If you just want to see the
+    overall structure of the code, then start here.
+
+``-dsuppress-uniques``
+    .. index::
+       single: -dsuppress-uniques
+
+    Suppress the printing of uniques. This may make the printout
+    ambiguous (e.g. unclear where an occurrence of 'x' is bound), but it
+    makes the output of two compiler runs have many fewer gratuitous
+    differences, so you can realistically apply ``diff``. Once ``diff``
+    has shown you where to look, you can try again without
+    ``-dsuppress-uniques``
+
+``-dsuppress-idinfo``
+    .. index::
+       single: -dsuppress-idinfo
+
+    Suppress extended information about identifiers where they are
+    bound. This includes strictness information and inliner templates.
+    Using this flag can cut the size of the core dump in half, due to
+    the lack of inliner templates
+
+``-dsuppress-unfoldings``
+    .. index::
+       single: -dsuppress-unfoldings
+
+    Suppress the printing of the stable unfolding of a variable at its
+    binding site.
+
+``-dsuppress-module-prefixes``
+    .. index::
+       single: -dsuppress-module-prefixes
+
+    Suppress the printing of module qualification prefixes. This is the
+    ``Data.List`` in ``Data.List.length``.
+
+``-dsuppress-type-signatures``
+    .. index::
+       single: -dsuppress-type-signatures
+
+    Suppress the printing of type signatures.
+
+``-dsuppress-type-applications``
+    .. index::
+       single: -dsuppress-type-applications
+
+    Suppress the printing of type applications.
+
+``-dsuppress-coercions``
+    .. index::
+       single: -dsuppress-coercions
+
+    Suppress the printing of type coercions.
+
+.. _checking-consistency:
+
+Checking for consistency
+------------------------
+
+.. index::
+   single: consistency checks
+   single: lint
+
+``-dcore-lint``
+    .. index::
+       single: -dcore-lint
+
+    Turn on heavyweight intra-pass sanity-checking within GHC, at Core
+    level. (It checks GHC's sanity, not yours.)
+
+``-dstg-lint``
+    .. index::
+       single: -dstg-lint
+
+    Ditto for STG level. (note: currently doesn't work).
+
+``-dcmm-lint``
+    .. index::
+       single: -dcmm-lint
+
+    Ditto for C-- level.
diff --git a/docs/users_guide/debugging.xml b/docs/users_guide/debugging.xml
deleted file mode 100644 (file)
index fd12e1d..0000000
+++ /dev/null
@@ -1,681 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<sect1 id="options-debugging">
-  <title>Debugging the compiler</title>
-
-  <indexterm><primary>debugging options (for GHC)</primary></indexterm>
-
-  <para>HACKER TERRITORY. HACKER TERRITORY.  (You were warned.)</para>
-
-  <sect2 id="dumping-output">
-    <title>Dumping out compiler intermediate structures</title>
-
-    <indexterm><primary>dumping GHC intermediates</primary></indexterm>
-    <indexterm><primary>intermediate passes, output</primary></indexterm>
-
-    <variablelist>
-      <varlistentry>
-       <term>
-          <option>-ddump-</option><replaceable>pass</replaceable>
-          <indexterm><primary><option>-ddump</option> options</primary></indexterm>
-        </term>
-       <listitem>
-         <para>Make a debugging dump after pass
-        <literal>&lt;pass&gt;</literal> (may be common enough to need
-        a short form&hellip;).  You can get all of these at once
-        (<emphasis>lots</emphasis> of output) by using
-        <option>-v5</option>, or most of them with
-        <option>-v4</option>.  You can prevent them from clogging up
-        your standard output by passing <option>-ddump-to-file</option>.
-        Some of the most useful ones are:</para>
-
-         <variablelist>
-           <varlistentry>
-             <term>
-               <option>-ddump-parsed</option>:
-                <indexterm><primary><option>-ddump-parsed</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>parser output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-rn</option>:
-                <indexterm><primary><option>-ddump-rn</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>renamer output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-tc</option>:
-                <indexterm><primary><option>-ddump-tc</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>typechecker output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-splices</option>:
-                <indexterm><primary><option>-ddump-splices</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>Dump Template Haskell expressions that we splice in,
-                and what Haskell code the expression evaluates to.</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-types</option>:
-                <indexterm><primary><option>-ddump-types</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>Dump a type signature for each value defined at
-              the top level of the module.  The list is sorted
-              alphabetically.  Using <option>-dppr-debug</option>
-              dumps a type signature for all the imported and
-              system-defined things as well; useful for debugging the
-              compiler.</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-deriv</option>:
-                <indexterm><primary><option>-ddump-deriv</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>derived instances</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-ds</option>:
-                <indexterm><primary><option>-ddump-ds</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>desugarer output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-spec</option>:
-                <indexterm><primary><option>-ddump-spec</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>output of specialisation pass</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-rules</option>:
-                <indexterm><primary><option>-ddump-rules</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>dumps all rewrite rules specified in this module;
-                      see <xref linkend="controlling-rules"/>.
-                </para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-rule-firings</option>:
-                <indexterm><primary><option>-ddump-rule-firings</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>dumps the names of all rules that fired in this module</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-rule-rewrites</option>:
-                <indexterm><primary><option>-ddump-rule-rewrites</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>dumps detailed information about all rules that fired in
-                     this module
-               </para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-vect</option>:
-                <indexterm><primary><option>-ddump-vect</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>dumps the output of the vectoriser.
-                </para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-simpl</option>:
-                <indexterm><primary><option>-ddump-simpl</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>simplifier output (Core-to-Core passes)</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-inlinings</option>:
-                <indexterm><primary><option>-ddump-inlinings</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>inlining info from the simplifier</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-stranal</option>:
-                <indexterm><primary><option>-ddump-stranal</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>strictness analyser output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-strsigs</option>:
-                <indexterm><primary><option>-ddump-strsigs</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>strictness signatures</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-cse</option>:
-                <indexterm><primary><option>-ddump-cse</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>CSE pass output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-worker-wrapper</option>:
-                <indexterm><primary><option>-ddump-worker-wrapper</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>worker/wrapper split output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-occur-anal</option>:
-                <indexterm><primary><option>-ddump-occur-anal</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>`occurrence analysis' output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-prep</option>:
-                <indexterm><primary><option>-ddump-prep</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>output of core preparation pass</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-stg</option>:
-                <indexterm><primary><option>-ddump-stg</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>output of STG-to-STG passes</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-cmm</option>:
-                <indexterm><primary><option>-ddump-cmm</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>Print the C-- code out.</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-opt-cmm</option>:
-                <indexterm><primary><option>-ddump-opt-cmm</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>Dump the results of C-- to C-- optimising passes.</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-asm</option>:
-                <indexterm><primary><option>-ddump-asm</option></primary></indexterm>
-             </term>
-             <listitem>
-            <para>assembly language from the
-              <link linkend="native-code-gen">native code generator</link></para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-llvm</option>:
-                <indexterm><primary><option>-ddump-llvm</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>LLVM code from the <link linkend="llvm-code-gen">LLVM code
-                 generator</link></para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-bcos</option>:
-                <indexterm><primary><option>-ddump-bcos</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>byte code compiler output</para>
-             </listitem>
-           </varlistentry>
-
-           <varlistentry>
-             <term>
-               <option>-ddump-foreign</option>:
-                <indexterm><primary><option>-ddump-foreign</option></primary></indexterm>
-             </term>
-             <listitem>
-               <para>dump foreign export stubs</para>
-             </listitem>
-           </varlistentry>
-         </variablelist>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-ddump-simpl-iterations</option>:
-          <indexterm><primary><option>-ddump-simpl-iterations</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Show the output of each <emphasis>iteration</emphasis>
-        of the simplifier (each run of the simplifier has a maximum
-        number of iterations, normally 4).  This outputs even more information
-        than <option>-ddump-simpl-phases</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-ddump-simpl-stats</option>
-          <indexterm><primary><option>-ddump-simpl-stats option</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Dump statistics about how many of each kind of
-        transformation too place.  If you add
-        <option>-dppr-debug</option> you get more detailed
-        information.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-ddump-if-trace</option>
-          <indexterm><primary><option>-ddump-if-trace</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Make the interface loader be *real* chatty about what it is
-       up to.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-  <term>
-          <option>-ddump-tc-trace</option>
-          <indexterm><primary><option>-ddump-tc-trace</option></primary></indexterm>
-        </term>
-  <listitem>
-    <para>Make the type checker be *real* chatty about what it is
-  up to.</para>
-  </listitem>
-      </varlistentry>
-
-      <varlistentry>
-  <term>
-          <option>-ddump-vt-trace</option>
-          <indexterm><primary><option>-ddump-tv-trace</option></primary></indexterm>
-        </term>
-  <listitem>
-    <para>Make the vectoriser be *real* chatty about what it is
-  up to.</para>
-  </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-ddump-rn-trace</option>
-          <indexterm><primary><option>-ddump-rn-trace</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Make the renamer be *real* chatty about what it is
-       up to.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-ddump-rn-stats</option>
-          <indexterm><primary><option>-dshow-rn-stats</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Print out summary of what kind of information the renamer
-        had to bring in.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dverbose-core2core</option>
-          <indexterm><primary><option>-dverbose-core2core</option></primary></indexterm>
-        </term>
-       <term>
-          <option>-dverbose-stg2stg</option>
-          <indexterm><primary><option>-dverbose-stg2stg</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Show the output of the intermediate Core-to-Core and
-        STG-to-STG passes, respectively.  (<emphasis>Lots</emphasis>
-        of output!) So: when we're really desperate:</para>
-
-         <screen>
-% ghc -noC -O -ddump-simpl -dverbose-core2core -dcore-lint Foo.hs
-</screen>
-
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dshow-passes</option>
-          <indexterm><primary><option>-dshow-passes</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Print out each pass name as it happens.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-ddump-core-stats</option>
-          <indexterm><primary><option>-ddump-core-stats</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Print a one-line summary of the size of the Core program
-                     at the end of the optimisation pipeline.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dfaststring-stats</option>
-          <indexterm><primary><option>-dfaststring-stats</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Show statistics for the usage of fast strings by the
-          compiler.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dppr-debug</option>
-          <indexterm><primary><option>-dppr-debug</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Debugging output is in one of several
-          &ldquo;styles.&rdquo; Take the printing of types, for
-          example.  In the &ldquo;user&rdquo; style (the default), the
-          compiler's internal ideas about types are presented in
-          Haskell source-level syntax, insofar as possible.  In the
-          &ldquo;debug&rdquo; style (which is the default for
-          debugging output), the types are printed in with explicit
-          foralls, and variables have their unique-id attached (so you
-          can check for things that look the same but aren't).  This
-          flag makes debugging output appear in the more verbose debug
-          style.</para>
-       </listitem>
-      </varlistentry>
-    </variablelist>
-  </sect2>
-
-  <sect2 id="formatting dumps">
-    <title>Formatting dumps</title>
-
-    <indexterm><primary>formatting dumps</primary></indexterm>
-
-     <variablelist>
-      <varlistentry>
-       <term>
-          <option>-dppr-user-length</option>
-          <indexterm><primary><option>-dppr-user-length</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>In error messages, expressions are printed to a
-         certain &ldquo;depth&rdquo;, with subexpressions beyond the
-         depth replaced by ellipses.  This flag sets the
-         depth.  Its default value is 5.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dppr-colsNNN</option>
-          <indexterm><primary><option>-dppr-colsNNN</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Set the width of debugging output. Use this if your code is wrapping too much.
-               For example: <option>-dppr-cols200</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dppr-case-as-let</option>
-          <indexterm><primary><option>-dppr-case-as-let</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Print single alternative case expressions as though they were strict
-               let expressions. This is helpful when your code does a lot of unboxing.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <option>-dno-debug-output</option>
-          <indexterm><primary><option>-dno-debug-output</option></primary></indexterm>
-        </term>
-        <listitem>
-          <para>Suppress any unsolicited debugging output.  When GHC
-            has been built with the <literal>DEBUG</literal> option it
-            occasionally emits debug output of interest to developers.
-            The extra output can confuse the testing framework and
-            cause bogus test failures, so this flag is provided to
-            turn it off.</para>
-        </listitem>
-      </varlistentry>
-     </variablelist>
-
-  </sect2>
-
-  <sect2 id="suppression">
-    <title>Suppressing unwanted information</title>
-
-    <indexterm><primary>suppression</primary></indexterm>
-
-    Core dumps contain a large amount of information. Depending on what you are doing, not all of it will be useful.
-    Use these flags to suppress the parts that you are not interested in.
-
-    <variablelist>
-      <varlistentry>
-       <term>
-          <option>-dsuppress-all</option>
-          <indexterm><primary><option>-dsuppress-all</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Suppress everything that can be suppressed, except for unique ids as this often
-               makes the printout ambiguous. If you just want to see the overall structure of
-               the code, then start here.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dsuppress-uniques</option>
-          <indexterm><primary><option>-dsuppress-uniques</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Suppress the printing of uniques. This may make
-         the printout ambiguous (e.g. unclear where an occurrence of 'x' is bound), but
-         it makes the output of two compiler runs have many fewer gratuitous differences,
-           so you can realistically apply <command>diff</command>.  Once <command>diff</command>
-         has shown you where to look, you can try again without <option>-dsuppress-uniques</option></para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dsuppress-idinfo</option>
-          <indexterm><primary><option>-dsuppress-idinfo</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Suppress extended information about identifiers where they are bound. This includes
-               strictness information and inliner templates. Using this flag can cut the size
-               of the core dump in half, due to the lack of inliner templates</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dsuppress-unfoldings</option>
-          <indexterm><primary><option>-dsuppress-unfoldings</option></primary></indexterm>
-        </term>
-       <listitem>
-          <para>Suppress the printing of the stable unfolding of a variable at its binding site.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dsuppress-module-prefixes</option>
-          <indexterm><primary><option>-dsuppress-module-prefixes</option></primary></indexterm>
-        </term>
-       <listitem>
-          <para>Suppress the printing of module qualification prefixes.
-               This is the <constant>Data.List</constant> in <constant>Data.List.length</constant>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dsuppress-type-signatures</option>
-          <indexterm><primary><option>-dsuppress-type-signatures</option></primary></indexterm>
-        </term>
-       <listitem>
-          <para>Suppress the printing of type signatures.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dsuppress-type-applications</option>
-          <indexterm><primary><option>-dsuppress-type-applications</option></primary></indexterm>
-        </term>
-       <listitem>
-          <para>Suppress the printing of type applications.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dsuppress-coercions</option>
-          <indexterm><primary><option>-dsuppress-coercions</option></primary></indexterm>
-        </term>
-       <listitem>
-          <para>Suppress the printing of type coercions.</para>
-       </listitem>
-      </varlistentry>
-    </variablelist>
-  </sect2>
-
-  <sect2 id="checking-consistency">
-    <title>Checking for consistency</title>
-
-    <indexterm><primary>consistency checks</primary></indexterm>
-    <indexterm><primary>lint</primary></indexterm>
-
-    <variablelist>
-
-      <varlistentry>
-       <term>
-          <option>-dcore-lint</option>
-          <indexterm><primary><option>-dcore-lint</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Turn on heavyweight intra-pass sanity-checking within
-          GHC, at Core level.  (It checks GHC's sanity, not yours.)</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dstg-lint</option>:
-          <indexterm><primary><option>-dstg-lint</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Ditto for STG level. (NOTE: currently doesn't work).</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-dcmm-lint</option>:
-          <indexterm><primary><option>-dcmm-lint</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Ditto for C-- level.</para>
-       </listitem>
-      </varlistentry>
-
-    </variablelist>
-  </sect2>
-
-</sect1>
-
-<!-- Emacs stuff:
-     ;;; Local Variables: ***
-     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
-     ;;; End: ***
- -->
diff --git a/docs/users_guide/editing-guide.rst b/docs/users_guide/editing-guide.rst
new file mode 100644 (file)
index 0000000..7e973ce
--- /dev/null
@@ -0,0 +1,334 @@
+Care and feeding of your GHC Users Guide
+========================================
+
+The GHC User's Guide is the primary reference documentation
+for the Glasgow Haskell Compiler. Even more than this, it at times serves (for
+better or for worse) as a de-facto language standard, being the sole
+non-academic reference for many widely used language extensions.
+
+Since GHC 8.0, the User's Guide is authored in `ReStructuredText
+<https://en.wikipedia.org/wiki/ReStructuredText>`__ (or ReST or RST, for short)
+a rich but light-weight mark-up language aimed at producing documentation. The
+`Sphinx <http://sphinx-doc.org/>`__ tool is used to produce the final PDF and
+HTML documentation.
+
+This document (also written in ReST) serves as a brief introducion to ReST and to
+document the conventions used in the User's Guide. This document is *not* intended
+to be a thorough guide to ReST. For this see the resources referenced
+`below <#references>`__.
+
+Basics
+------
+
+Unicode characters are allowed in the document.
+
+The basic syntax works largely as one would expect. For instance,
+
+.. code-block:: rest
+
+    This is a paragraph containing a few sentences of text. Purple turtles walk
+    through green fields of lofty maize. Lorem ipsum dolor sit amet, consectetur
+    adipiscing elit. Some lists,
+
+    1. This is a list item
+
+       a. Followed by a sub-item
+       b. And another!
+       c. Now with ``a bit of code`` and some *emphasis*.
+
+    2. Back to the first list
+
+    Or perhaps you are more of a bullet list person,
+
+    * Foo
+    * Fizzle
+
+      - Bar
+      - Blah
+
+    Or perhaps a definition list is in order,
+
+    *Chelonii*
+        The taxonomic order consisting of modern turtles
+    *Meiolaniidae*
+        The taxonomic order of an extinct variety of herbivorous turtles.
+
+Note the blank lines between a list item and its sub-items. Sub-items should be
+on the same indentation level as the content of their parent items. Also note
+that no whitespace is necessary or desirable before the bullet or item number
+(lest the list be indented unnecessarily).
+
+The above would be rendered as,
+
+    This is a paragraph containing a few sentences of text. Purple turtles walk
+    through green fields of lofty maize. Lorem ipsum dolor sit amet, consectetur
+    adipiscing elit. Some lists,
+
+    1. This is a list item
+
+       a. Followed by a sub-item
+       b. And another!
+       c. Now with ``a bit of code`` and some *emphasis*.
+
+    2. Back to the first list
+
+    Or perhaps you are more of a bullet list person,
+
+    * Foo
+    * Fizzle
+
+      - Bar
+      - Blah
+
+    Or perhaps a definition list is in order,
+
+    *Chelonii*
+        The taxonomic order consisting of modern turtles
+    *Meiolaniidae*
+        The taxonomic order of an extinct variety of herbivorous turtles.
+
+
+Headings
+~~~~~~~~
+
+While ReST can accomodate a wide range of heading styles, we have standardized
+on this convention in the User's Guide,
+
+.. code-block:: rest
+
+    Header level 1
+    ==============
+
+    Header level 2
+    --------------
+
+    Header level 3
+    ~~~~~~~~~~~~~~
+
+    Header level 4
+    ^^^^^^^^^^^^^^^
+
+
+Formatting code
+~~~~~~~~~~~~~~~
+
+Haskell
+^^^^^^^
+
+Code snippets can be included as both inline and block elements. Inline
+code is denoted with double-backticks whereas block of code are introduced
+by ending a paragraph with double-colons and indentation,
+
+.. code-block:: rest
+
+    The ``fib`` function is defined as, ::
+
+        fib :: Integer -> Integer
+        fib 1 = 1
+        fib n = n * fib (n - 1)
+
+Which would be rendered as,
+
+    The ``fib`` function is defined as, ::
+
+        fib :: Integer -> Integer
+        fib 1 = 1
+        fib n = n * fib (n - 1)
+
+Other languages
+^^^^^^^^^^^^^^^
+
+Double-colon blocks are syntax-highlighted as Haskell by default. To avoid this
+use a
+``.. code-block`` `directive
+<http://sphinx-doc.org/markup/code.html#directive-code-block>`__ with explicit
+language designation,
+
+.. code-block:: rest
+
+    This is a simple shell script,
+
+    .. code-block:: sh
+
+        #!/bin/bash
+        echo "Hello World!"
+
+
+Links
+~~~~~
+
+Within the Users Guide
+^^^^^^^^^^^^^^^^^^^^^^
+
+Frequently we want to give a name to a section so it can be referred to
+from other points in the document,
+
+.. code-block:: rest
+
+    .. _options-platform:
+
+    Platform-specific Flags
+    -----------------------
+
+    There are lots of platform-specific flags.
+
+    Some other section
+    -------------------
+
+    GHC supports a variety of :ref:`x86 specific features <options-platform>`.
+
+    See :ref:`options-platform` for details.
+
+
+To GHC Trac resources
+^^^^^^^^^^^^^^^^^^^^^
+
+There are special macros for conveniently linking to GHC Trac
+Wiki articles and tickets,
+
+.. code-block:: rest
+
+    See :ghc-wiki:`Commentary/Latedmd` for details on demand analysis.
+
+    See the :ghc-wiki:`coding style <Commentary/CodingStyle>` for guidelines.
+
+    See the :ghc-ticket:`123` for further discussion.
+
+    See the :ghc-ticket:`this bug <123>` for what happens when this fails.
+
+
+To external resources
+^^^^^^^^^^^^^^^^^^^^^
+
+External links can be written in either of these ways,
+
+.. code-block:: rest
+
+    See the `GHC Wiki <http://ghc.haskell.org/wiki>`_ for details.
+
+    See the `GHC Wiki`_ for details.
+
+    .. _GHC Wiki: http://ghc.haskell.org/wiki
+
+
+To core library Haddock documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is often useful to be able to refer to the Haddock documention of the
+libraries shipped with GHC. The users guide's build system provides
+commands for referring to documentation for the following core GHC packages,
+
+* ``base``: ``:base-ref:``
+* ``cabal``: ``:cabal-ref:``
+* ``ghc-prim``: ``:ghc-prim-ref:``
+
+For instance,
+
+.. code-block:: rest
+
+    See the documentation for :base-ref:`Control.Applicative <Control-Applicative.html>`
+    for details.
+
+
+Index entries
+~~~~~~~~~~~~~
+
+Index entries can be included anywhere in the document as a block element.
+They look like,
+    
+.. code-block:: rest
+
+    Here is some discussion on the Strict Haskell extension.
+
+    .. index::
+        single: strict haskell
+        single: language extensions; StrictData
+
+This would produce two entries in the index referring to the "Strict Haskell"
+section. One would be a simple "strict haskell" heading whereas the other would
+be a "StrictData" subheading under "language extensions".
+
+Sadly it is not possible to use inline elements (e.g. monotype inlines) inside
+index headings.
+
+Citations
+---------
+
+Citations can be marked-up like this,
+
+.. code-block:: rest
+
+    See the original paper [Doe2008]_
+
+    .. [Doe2008] John Doe and Leslie Conway.
+                 "This is the title of our paper" (2008)
+
+
+Admonitions
+-----------
+
+`Admonitions`_ are block elements used to draw the readers attention to a point.
+They should not be over-used for the sake of readability but they can be quite
+effective in separating and drawing attention to points of importance,
+
+.. code-block:: rest
+
+    .. important::
+
+        Be friendly and supportive to your fellow contributors.
+
+Would be rendered as,
+
+    .. important::
+
+        Be friendly and supportive to your fellow contributors.
+
+There are a number of admonitions types,
+
+.. hlist::
+
+    * attention
+    * caution
+    * danger
+    * error
+    * hint
+    * important
+    * note
+    * tip
+    * warning
+
+
+.. _Admonitions: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
+
+Style Conventions
+-----------------
+
+When describing user commands and the like it is common to need to denote
+user-substitutable tokens. In this document we use the convention, ``⟨subst⟩``
+(note that these are angle brackets, ``U+27E8`` and ``U+27E9``, not
+less-than/greater-than signs).
+
+
+.. _references:
+
+GHC command-line options reference
+----------------------------------
+
+The tabular nature of GHC flags reference (``flags.rst``) makes it very
+difficult to maintain as ReST. For this reason it is generated by
+``utils/mkUserGuidePart``. Any command-line options added to GHC should
+be added to the appropriate file in ``utils/mkUserGuidePart/Options``.
+
+
+ReST reference materials
+------------------------
+
+* `Sphinx ReST Primer`_: A great place to start.
+* `Sphinx extensions`_: How Sphinx extends ReST
+* `ReST reference`_: When you really need the details.
+* `Directives reference`_
+
+.. _Sphinx ReST Primer: http://sphinx-doc.org/rest.html
+.. _ReST reference: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
+.. _Sphinx extensions: http://sphinx-doc.org/markup/index.html
+.. _Directives reference: http://docutils.sourceforge.net/docs/ref/rst/directives.html#code
diff --git a/docs/users_guide/extending_ghc.rst b/docs/users_guide/extending_ghc.rst
new file mode 100644 (file)
index 0000000..efe18b0
--- /dev/null
@@ -0,0 +1,535 @@
+.. _extending-ghc:
+
+Extending and using GHC as a Library
+====================================
+
+GHC exposes its internal APIs to users through the built-in ghc package.
+It allows you to write programs that leverage GHC's entire compilation
+driver, in order to analyze or compile Haskell code programmatically.
+Furthermore, GHC gives users the ability to load compiler plugins during
+compilation - modules which are allowed to view and change GHC's
+internal intermediate representation, Core. Plugins are suitable for
+things like experimental optimizations or analysis, and offer a lower
+barrier of entry to compiler development for many common cases.
+
+Furthermore, GHC offers a lightweight annotation mechanism that you can
+use to annotate your source code with metadata, which you can later
+inspect with either the compiler API or a compiler plugin.
+
+.. _annotation-pragmas:
+
+Source annotations
+------------------
+
+Annotations are small pragmas that allow you to attach data to
+identifiers in source code, which are persisted when compiled. These
+pieces of data can then inspected and utilized when using GHC as a
+library or writing a compiler plugin.
+
+.. _ann-pragma:
+
+Annotating values
+~~~~~~~~~~~~~~~~~
+
+.. index::
+   single: ANN pragma
+   single: pragma; ANN
+   single: source annotations
+
+Any expression that has both ``Typeable`` and ``Data`` instances may be
+attached to a top-level value binding using an ``ANN`` pragma. In
+particular, this means you can use ``ANN`` to annotate data constructors
+(e.g. ``Just``) as well as normal values (e.g. ``take``). By way of
+example, to annotate the function ``foo`` with the annotation
+``Just "Hello"`` you would do this:
+
+::
+
+    {-# ANN foo (Just "Hello") #-}
+    foo = ...
+
+A number of restrictions apply to use of annotations:
+
+-  The binder being annotated must be at the top level (i.e. no nested
+   binders)
+
+-  The binder being annotated must be declared in the current module
+
+-  The expression you are annotating with must have a type with
+   ``Typeable`` and ``Data`` instances
+
+-  The `Template Haskell staging restrictions <>`__ apply to the
+   expression being annotated with, so for example you cannot run a
+   function from the module being compiled.
+
+   To be precise, the annotation ``{-# ANN x e #-}`` is well staged if
+   and only if ``$(e)`` would be (disregarding the usual type
+   restrictions of the splice syntax, and the usual restriction on
+   splicing inside a splice - ``$([|1|])`` is fine as an annotation,
+   albeit redundant).
+
+If you feel strongly that any of these restrictions are too onerous,
+:ghc-wiki:`please give the GHC team a shout <MailingListsAndIRC>`.
+
+However, apart from these restrictions, many things are allowed,
+including expressions which are not fully evaluated! Annotation
+expressions will be evaluated by the compiler just like Template Haskell
+splices are. So, this annotation is fine:
+
+::
+
+    {-# ANN f SillyAnnotation { foo = (id 10) + $([| 20 |]), bar = 'f } #-}
+    f = ...
+
+.. _typeann-pragma:
+
+Annotating types
+~~~~~~~~~~~~~~~~
+
+.. index::
+   single: ANN pragma; on types
+
+You can annotate types with the ``ANN`` pragma by using the ``type``
+keyword. For example:
+
+::
+
+    {-# ANN type Foo (Just "A `Maybe String' annotation") #-}
+    data Foo = ...
+
+.. _modann-pragma:
+
+Annotating modules
+~~~~~~~~~~~~~~~~~~
+
+.. index::
+   single: ANN pragma; on modules
+
+You can annotate modules with the ``ANN`` pragma by using the ``module``
+keyword. For example:
+
+::
+
+    {-# ANN module (Just "A `Maybe String' annotation") #-}
+
+.. _ghc-as-a-library:
+
+Using GHC as a Library
+----------------------
+
+The ``ghc`` package exposes most of GHC's frontend to users, and thus
+allows you to write programs that leverage it. This library is actually
+the same library used by GHC's internal, frontend compilation driver,
+and thus allows you to write tools that programmatically compile source
+code and inspect it. Such functionality is useful in order to write
+things like IDE or refactoring tools. As a simple example, here's a
+program which compiles a module, much like ghc itself does by default
+when invoked:
+
+::
+
+    import GHC
+    import GHC.Paths ( libdir )
+    import DynFlags ( defaultLogAction )
+     
+    main = 
+        defaultErrorHandler defaultLogAction $ do
+          runGhc (Just libdir) $ do
+            dflags <- getSessionDynFlags
+            setSessionDynFlags dflags
+            target <- guessTarget "test_main.hs" Nothing
+            setTargets [target]
+            load LoadAllTargets
+
+The argument to ``runGhc`` is a bit tricky. GHC needs this to find its
+libraries, so the argument must refer to the directory that is printed
+by ``ghc --print-libdir`` for the same version of GHC that the program
+is being compiled with. Above we therefore use the ``ghc-paths`` package
+which provides this for us.
+
+Compiling it results in:
+
+::
+
+    $ cat test_main.hs
+    main = putStrLn "hi"
+    $ ghc -package ghc simple_ghc_api.hs
+    [1 of 1] Compiling Main             ( simple_ghc_api.hs, simple_ghc_api.o )
+    Linking simple_ghc_api ...
+    $ ./simple_ghc_api
+    $ ./test_main 
+    hi
+    $
+
+For more information on using the API, as well as more samples and
+references, please see `this Haskell.org wiki
+page <http://haskell.org/haskellwiki/GHC/As_a_library>`__.
+
+.. _compiler-plugins:
+
+Compiler Plugins
+----------------
+
+GHC has the ability to load compiler plugins at compile time. The
+feature is similar to the one provided by
+`GCC <http://gcc.gnu.org/wiki/plugins>`__, and allows users to write
+plugins that can adjust the behaviour of the constraint solver, inspect
+and modify the compilation pipeline, as well as transform and inspect
+GHC's intermediate language, Core. Plugins are suitable for experimental
+analysis or optimization, and require no changes to GHC's source code to
+use.
+
+Plugins cannot optimize/inspect C--, nor can they implement things like
+parser/front-end modifications like GCC, apart from limited changes to
+the constraint solver. If you feel strongly that any of these
+restrictions are too onerous,
+:ghc-wiki:`please give the GHC team a shout <MailingListsAndIRC>`.
+
+.. _using-compiler-plugins:
+
+Using compiler plugins
+~~~~~~~~~~~~~~~~~~~~~~
+
+Plugins can be specified on the command line with the option
+``-fplugin=module`` where ⟨module⟩ is a module in a registered package
+that exports a plugin. Arguments can be given to plugins with the
+command line option ``-fplugin-opt=module:args``, where ⟨args⟩ are
+arguments interpreted by the plugin provided by ⟨module⟩.
+
+As an example, in order to load the plugin exported by ``Foo.Plugin`` in
+the package ``foo-ghc-plugin``, and give it the parameter "baz", we
+would invoke GHC like this:
+
+::
+
+    $ ghc -fplugin Foo.Plugin -fplugin-opt Foo.Plugin:baz Test.hs
+    [1 of 1] Compiling Main             ( Test.hs, Test.o )
+    Loading package ghc-prim ... linking ... done.
+    Loading package integer-gmp ... linking ... done.
+    Loading package base ... linking ... done.
+    Loading package ffi-1.0 ... linking ... done.
+    Loading package foo-ghc-plugin-0.1 ... linking ... done.
+    ...
+    Linking Test ...
+    $
+
+Since plugins are exported by registered packages, it's safe to put
+dependencies on them in cabal for example, and specify plugin arguments
+to GHC through the ``ghc-options`` field.
+
+.. _writing-compiler-plugins:
+
+Writing compiler plugins
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Plugins are modules that export at least a single identifier,
+``plugin``, of type ``GhcPlugins.Plugin``. All plugins should
+``import GhcPlugins`` as it defines the interface to the compilation
+pipeline.
+
+A ``Plugin`` effectively holds a function which installs a compilation
+pass into the compiler pipeline. By default there is the empty plugin
+which does nothing, ``GhcPlugins.defaultPlugin``, which you should
+override with record syntax to specify your installation function. Since
+the exact fields of the ``Plugin`` type are open to change, this is the
+best way to ensure your plugins will continue to work in the future with
+minimal interface impact.
+
+``Plugin`` exports a field, ``installCoreToDos`` which is a function of
+type ``[CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]``. A
+``CommandLineOption`` is effectively just ``String``, and a ``CoreToDo``
+is basically a function of type ``Core -> Core``. A ``CoreToDo`` gives
+your pass a name and runs it over every compiled module when you invoke
+GHC.
+
+As a quick example, here is a simple plugin that just does nothing and
+just returns the original compilation pipeline, unmodified, and says
+'Hello':
+
+::
+
+    module DoNothing.Plugin (plugin) where
+    import GhcPlugins
+
+    plugin :: Plugin
+    plugin = defaultPlugin {
+      installCoreToDos = install
+      }
+
+    install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
+    install _ todo = do
+      reinitializeGlobals
+      putMsgS "Hello!"
+      return todo
+
+Provided you compiled this plugin and registered it in a package (with
+cabal for instance,) you can then use it by just specifying
+``-fplugin=DoNothing.Plugin`` on the command line, and during the
+compilation you should see GHC say 'Hello'.
+
+Note carefully the ``reinitializeGlobals`` call at the beginning of the
+installation function. Due to bugs in the windows linker dealing with
+``libghc``, this call is necessary to properly ensure compiler plugins
+have the same global state as GHC at the time of invocation. Without
+``reinitializeGlobals``, compiler plugins can crash at runtime because
+they may require state that hasn't otherwise been initialized.
+
+In the future, when the linking bugs are fixed, ``reinitializeGlobals``
+will be deprecated with a warning, and changed to do nothing.
+
+.. _core-plugins-in-more-detail:
+
+Core plugins in more detail
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``CoreToDo`` is effectively a data type that describes all the kinds of
+optimization passes GHC does on Core. There are passes for
+simplification, CSE, vectorisation, etc. There is a specific case for
+plugins, ``CoreDoPluginPass :: String -> PluginPass -> CoreToDo`` which
+should be what you always use when inserting your own pass into the
+pipeline. The first parameter is the name of the plugin, and the second
+is the pass you wish to insert.
+
+``CoreM`` is a monad that all of the Core optimizations live and operate
+inside of.
+
+A plugin's installation function (``install`` in the above example)
+takes a list of ``CoreToDo``\ s and returns a list of ``CoreToDo``.
+Before GHC begins compiling modules, it enumerates all the needed
+plugins you tell it to load, and runs all of their installation
+functions, initially on a list of passes that GHC specifies itself.
+After doing this for every plugin, the final list of passes is given to
+the optimizer, and are run by simply going over the list in order.
+
+You should be careful with your installation function, because the list
+of passes you give back isn't questioned or double checked by GHC at the
+time of this writing. An installation function like the following:
+
+::
+
+    install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
+    install _ _ = return []
+
+is certainly valid, but also certainly not what anyone really wants.
+
+.. _manipulating-bindings:
+
+Manipulating bindings
+^^^^^^^^^^^^^^^^^^^^^
+
+In the last section we saw that besides a name, a ``CoreDoPluginPass``
+takes a pass of type ``PluginPass``. A ``PluginPass`` is a synonym for
+``(ModGuts -> CoreM ModGuts)``. ``ModGuts`` is a type that represents
+the one module being compiled by GHC at any given time.
+
+A ``ModGuts`` holds all of the module's top level bindings which we can
+examine. These bindings are of type ``CoreBind`` and effectively
+represent the binding of a name to body of code. Top-level module
+bindings are part of a ``ModGuts`` in the field ``mg_binds``.
+Implementing a pass that manipulates the top level bindings merely needs
+to iterate over this field, and return a new ``ModGuts`` with an updated
+``mg_binds`` field. Because this is such a common case, there is a
+function provided named ``bindsOnlyPass`` which lifts a function of type
+``([CoreBind] -> CoreM [CoreBind])`` to type
+``(ModGuts -> CoreM ModGuts)``.
+
+Continuing with our example from the last section, we can write a simple
+plugin that just prints out the name of all the non-recursive bindings
+in a module it compiles:
+
+::
+
+    module SayNames.Plugin (plugin) where
+    import GhcPlugins
+
+    plugin :: Plugin
+    plugin = defaultPlugin {
+      installCoreToDos = install
+      }
+
+    install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
+    install _ todo = do
+      reinitializeGlobals
+      return (CoreDoPluginPass "Say name" pass : todo)
+
+    pass :: ModGuts -> CoreM ModGuts
+    pass guts = do dflags <- getDynFlags
+                   bindsOnlyPass (mapM (printBind dflags)) guts
+      where printBind :: DynFlags -> CoreBind -> CoreM CoreBind
+            printBind dflags bndr@(NonRec b _) = do
+              putMsgS $ "Non-recursive binding named " ++ showSDoc dflags (ppr b)
+              return bndr 
+            printBind _ bndr = return bndr
+
+.. _getting-annotations:
+
+Using Annotations
+^^^^^^^^^^^^^^^^^
+
+Previously we discussed annotation pragmas (:ref:`annotation-pragmas`),
+which we mentioned could be used to give compiler plugins extra guidance
+or information. Annotations for a module can be retrieved by a plugin,
+but you must go through the modules ``ModGuts`` in order to get it.
+Because annotations can be arbitrary instances of ``Data`` and
+``Typeable``, you need to give a type annotation specifying the proper
+type of data to retrieve from the interface file, and you need to make
+sure the annotation type used by your users is the same one your plugin
+uses. For this reason, we advise distributing annotations as part of the
+package which also provides compiler plugins if possible.
+
+To get the annotations of a single binder, you can use
+``getAnnotations`` and specify the proper type. Here's an example that
+will print out the name of any top-level non-recursive binding with the
+``SomeAnn`` annotation:
+
+::
+
+    {-# LANGUAGE DeriveDataTypeable #-}
+    module SayAnnNames.Plugin (plugin, SomeAnn(..)) where
+    import GhcPlugins
+    import Control.Monad (unless)
+    import Data.Data
+
+    data SomeAnn = SomeAnn deriving (Data, Typeable)
+
+    plugin :: Plugin
+    plugin = defaultPlugin {
+      installCoreToDos = install
+      }
+
+    install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
+    install _ todo = do
+      reinitializeGlobals
+      return (CoreDoPluginPass "Say name" pass : todo)
+
+    pass :: ModGuts -> CoreM ModGuts
+    pass g = do
+              dflags <- getDynFlags
+              mapM_ (printAnn dflags g) (mg_binds g) >> return g
+      where printAnn :: DynFlags -> ModGuts -> CoreBind -> CoreM CoreBind
+            printAnn dflags guts bndr@(NonRec b _) = do
+              anns <- annotationsOn guts b :: CoreM [SomeAnn]
+              unless (null anns) $ putMsgS $ "Annotated binding found: " ++  showSDoc dflags (ppr b)
+              return bndr
+            printAnn _ _ bndr = return bndr
+
+    annotationsOn :: Data a => ModGuts -> CoreBndr -> CoreM [a]
+    annotationsOn guts bndr = do
+      anns <- getAnnotations deserializeWithData guts
+      return $ lookupWithDefaultUFM anns [] (varUnique bndr)
+
+Please see the GHC API documentation for more about how to use internal
+APIs, etc.
+
+.. _typechecker-plugins:
+
+Typechecker plugins
+~~~~~~~~~~~~~~~~~~~
+
+In addition to Core plugins, GHC has experimental support for
+typechecker plugins, which allow the behaviour of the constraint solver
+to be modified. For example, they make it possible to interface the
+compiler to an SMT solver, in order to support a richer theory of
+type-level arithmetic expressions than the theory built into GHC (see
+:ref:`typelit-tyfuns`).
+
+The ``Plugin`` type has a field ``tcPlugin`` of type
+``[CommandLineOption] -> Maybe TcPlugin``, where the ``TcPlugin`` type
+is defined thus:
+
+::
+
+    data TcPlugin = forall s . TcPlugin
+      { tcPluginInit  :: TcPluginM s
+      , tcPluginSolve :: s -> TcPluginSolver
+      , tcPluginStop  :: s -> TcPluginM ()
+      }
+
+    type TcPluginSolver = [Ct] -> [Ct] -> [Ct] -> TcPluginM TcPluginResult
+
+    data TcPluginResult = TcPluginContradiction [Ct] | TcPluginOk [(EvTerm,Ct)] [Ct]
+
+(The details of this representation are subject to change as we gain
+more experience writing typechecker plugins. It should not be assumed to
+be stable between GHC releases.)
+
+The basic idea is as follows:
+
+-  When type checking a module, GHC calls ``tcPluginInit`` once before
+   constraint solving starts. This allows the plugin to look things up
+   in the context, initialise mutable state or open a connection to an
+   external process (e.g. an external SMT solver). The plugin can return
+   a result of any type it likes, and the result will be passed to the
+   other two fields.
+
+-  During constraint solving, GHC repeatedly calls ``tcPluginSolve``.
+   This function is provided with the current set of constraints, and
+   should return a ``TcPluginResult`` that indicates whether a
+   contradiction was found or progress was made. If the plugin solver
+   makes progress, GHC will re-start the constraint solving pipeline,
+   looping until a fixed point is reached.
+
+-  Finally, GHC calls ``tcPluginStop`` after constraint solving is
+   finished, allowing the plugin to dispose of any resources it has
+   allocated (e.g. terminating the SMT solver process).
+
+Plugin code runs in the ``TcPluginM`` monad, which provides a restricted
+interface to GHC API functionality that is relevant for typechecker
+plugins, including ``IO`` and reading the environment. If you need
+functionality that is not exposed in the ``TcPluginM`` module, you can
+use ``unsafeTcPluginTcM :: TcM a -> TcPluginM a``, but are encouraged to
+contact the GHC team to suggest additions to the interface. Note that
+``TcPluginM`` can perform arbitrary IO via
+``tcPluginIO :: IO a -> TcPluginM a``, although some care must be taken
+with side effects (particularly in ``tcPluginSolve``). In general, it is
+up to the plugin author to make sure that any IO they do is safe.
+
+.. _constraint-solving-with-plugins:
+
+Constraint solving with plugins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The key component of a typechecker plugin is a function of type
+``TcPluginSolver``, like this:
+
+::
+
+    solve :: [Ct] -> [Ct] -> [Ct] -> TcPluginM TcPluginResult
+    solve givens deriveds wanteds = ...
+
+This function will be invoked at two points in the constraint solving
+process: after simplification of given constraints, and after
+unflattening of wanted constraints. The two phases can be distinguished
+because the deriveds and wanteds will be empty in the first case. In
+each case, the plugin should either
+
+-  return ``TcPluginContradiction`` with a list of impossible
+   constraints (which must be a subset of those passed in), so they can
+   be turned into errors; or
+
+-  return ``TcPluginOk`` with lists of solved and new constraints (the
+   former must be a subset of those passed in and must be supplied with
+   corresponding evidence terms).
+
+If the plugin cannot make any progress, it should return
+``TcPluginOk [] []``. Otherwise, if there were any new constraints, the
+main constraint solver will be re-invoked to simplify them, then the
+plugin will be invoked again. The plugin is responsible for making sure
+that this process eventually terminates.
+
+Plugins are provided with all available constraints (including
+equalities and typeclass constraints), but it is easy for them to
+discard those that are not relevant to their domain, because they need
+return only those constraints for which they have made progress (either
+by solving or contradicting them).
+
+Constraints that have been solved by the plugin must be provided with
+evidence in the form of an ``EvTerm`` of the type of the constraint.
+This evidence is ignored for given and derived constraints, which GHC
+"solves" simply by discarding them; typically this is used when they are
+uninformative (e.g. reflexive equations). For wanted constraints, the
+evidence will form part of the Core term that is generated after
+typechecking, and can be checked by ``-dcore-lint``. It is possible for
+the plugin to create equality axioms for use in evidence terms, but GHC
+does not check their consistency, and inconsistent axiom sets may lead
+to segfaults or other runtime misbehaviour.
diff --git a/docs/users_guide/extending_ghc.xml b/docs/users_guide/extending_ghc.xml
deleted file mode 100644 (file)
index c7b062b..0000000
+++ /dev/null
@@ -1,350 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<chapter id="extending-ghc">
-  <title>Extending and using GHC as a Library</title>
-
-  <para>GHC exposes its internal APIs to users through the built-in ghc package. It allows you to write programs that leverage GHC's entire compilation driver, in order to analyze or compile Haskell code programmatically. Furthermore, GHC gives users the ability to load compiler plugins during compilation - modules which are allowed to view and change GHC's internal intermediate representation, Core. Plugins are suitable for things like experimental optimizations or analysis, and offer a lower barrier of entry to compiler development for many common cases.</para>
-
-  <para>Furthermore, GHC offers a lightweight annotation mechanism that you can use to annotate your source code with metadata, which you can later inspect with either the compiler API or a compiler plugin.</para>
-
-  <sect1 id="annotation-pragmas">
-    <title>Source annotations</title>
-
-    <para>Annotations are small pragmas that allow you to attach data to identifiers in source code, which are persisted when compiled. These pieces of data can then inspected and utilized when using GHC as a library or writing a compiler plugin.</para>
-
-    <sect2 id="ann-pragma">
-      <title>Annotating values</title>
-
-      <indexterm><primary>ANN</primary></indexterm>
-
-      <para>Any expression that has both <literal>Typeable</literal> and <literal>Data</literal> instances may be attached to a top-level value
-      binding using an <literal>ANN</literal> pragma. In particular, this means you can use <literal>ANN</literal>
-      to annotate data constructors (e.g. <literal>Just</literal>) as well as normal values (e.g. <literal>take</literal>).
-      By way of example, to annotate the function <literal>foo</literal> with the annotation <literal>Just "Hello"</literal>
-      you would do this:</para>
-
-<programlisting>
-{-# ANN foo (Just "Hello") #-}
-foo = ...
-</programlisting>
-
-      <para>
-        A number of restrictions apply to use of annotations:
-        <itemizedlist>
-          <listitem><para>The binder being annotated must be at the top level (i.e. no nested binders)</para></listitem>
-          <listitem><para>The binder being annotated must be declared in the current module</para></listitem>
-          <listitem><para>The expression you are annotating with must have a type with <literal>Typeable</literal> and <literal>Data</literal> instances</para></listitem>
-          <listitem><para>The <ulink linkend="using-template-haskell">Template Haskell staging restrictions</ulink> apply to the
-          expression being annotated with, so for example you cannot run a function from the module being compiled.</para>
-
-          <para>To be precise, the annotation <literal>{-# ANN x e #-}</literal> is well staged if and only if <literal>$(e)</literal> would be
-          (disregarding the usual type restrictions of the splice syntax, and the usual restriction on splicing inside a splice - <literal>$([|1|])</literal> is fine as an annotation, albeit redundant).</para></listitem>
-        </itemizedlist>
-
-        If you feel strongly that any of these restrictions are too onerous, <ulink url="http://ghc.haskell.org/trac/ghc/wiki/MailingListsAndIRC">
-        please give the GHC team a shout</ulink>.
-      </para>
-
-      <para>However, apart from these restrictions, many things are allowed, including expressions which are not fully evaluated!
-      Annotation expressions will be evaluated by the compiler just like Template Haskell splices are. So, this annotation is fine:</para>
-
-<programlisting>
-{-# ANN f SillyAnnotation { foo = (id 10) + $([| 20 |]), bar = 'f } #-}
-f = ...
-</programlisting>
-    </sect2>
-
-    <sect2 id="typeann-pragma">
-      <title>Annotating types</title>
-
-      <indexterm><primary>ANN type</primary></indexterm>
-      <indexterm><primary>ANN</primary></indexterm>
-
-      <para>You can annotate types with the <literal>ANN</literal> pragma by using the <literal>type</literal> keyword. For example:</para>
-
-<programlisting>
-{-# ANN type Foo (Just "A `Maybe String' annotation") #-}
-data Foo = ...
-</programlisting>
-    </sect2>
-
-    <sect2 id="modann-pragma">
-      <title>Annotating modules</title>
-
-      <indexterm><primary>ANN module</primary></indexterm>
-      <indexterm><primary>ANN</primary></indexterm>
-
-      <para>You can annotate modules with the <literal>ANN</literal> pragma by using the <literal>module</literal> keyword. For example:</para>
-
-<programlisting>
-{-# ANN module (Just "A `Maybe String' annotation") #-}
-</programlisting>
-    </sect2>
-
-  </sect1>
-
-  <sect1 id="ghc-as-a-library">
-    <title>Using GHC as a Library</title>
-
-    <para>The <literal>ghc</literal> package exposes most of GHC's frontend to users, and thus allows you to write programs that leverage it. This library is actually the same library used by GHC's internal, frontend compilation driver, and thus allows you to write tools that programmatically compile source code and inspect it. Such functionality is useful in order to write things like IDE or refactoring tools. As a simple example, here's a program which compiles a module, much like ghc itself does by default when invoked:</para>
-
-<programlisting>
-import GHC
-import GHC.Paths ( libdir )
-import DynFlags ( defaultLogAction )
-main = 
-    defaultErrorHandler defaultLogAction $ do
-      runGhc (Just libdir) $ do
-        dflags &lt;- getSessionDynFlags
-        setSessionDynFlags dflags
-        target &lt;- guessTarget "test_main.hs" Nothing
-        setTargets [target]
-        load LoadAllTargets
-</programlisting>
-
-    <para>The argument to <literal>runGhc</literal> is a bit tricky. GHC needs this to find its libraries, so the argument must refer to the directory that is printed by <literal>ghc --print-libdir</literal> for the same version of GHC that the program is being compiled with. Above we therefore use the <literal>ghc-paths</literal> package which provides this for us. </para>
-
-    <para>Compiling it results in:</para>
-
-<programlisting>
-$ cat test_main.hs
-main = putStrLn "hi"
-$ ghc -package ghc simple_ghc_api.hs
-[1 of 1] Compiling Main             ( simple_ghc_api.hs, simple_ghc_api.o )
-Linking simple_ghc_api ...
-$ ./simple_ghc_api
-$ ./test_main 
-hi
-$ 
-</programlisting>
-
-    <para>For more information on using the API, as well as more samples and references, please see <ulink url="http://haskell.org/haskellwiki/GHC/As_a_library">this Haskell.org wiki page</ulink>.</para>
-  </sect1>
-
-  <sect1 id="compiler-plugins">
-    <title>Compiler Plugins</title>
-
-    <para>GHC has the ability to load compiler plugins at compile time. The feature is similar to the one provided by <ulink url="http://gcc.gnu.org/wiki/plugins">GCC</ulink>, and allows users to write plugins that can adjust the behaviour of the constraint solver, inspect and modify the compilation pipeline, as well as transform and inspect GHC's intermediate language, Core. Plugins are suitable for experimental analysis or optimization, and require no changes to GHC's source code to use.</para>
-
-    <para>Plugins cannot optimize/inspect C--, nor can they implement things like parser/front-end modifications like GCC, apart from limited changes to the constraint solver. If you feel strongly that any of these restrictions are too onerous, <ulink url="http://ghc.haskell.org/trac/ghc/wiki/MailingListsAndIRC"> please give the GHC team a shout</ulink>.</para>
-
-    <sect2 id="using-compiler-plugins">
-      <title>Using compiler plugins</title>
-
-      <para>Plugins can be specified on the command line with the option <literal>-fplugin=<replaceable>module</replaceable></literal> where <replaceable>module</replaceable> is a module in a registered package that exports a plugin. Arguments can be given to plugins with the command line option <literal>-fplugin-opt=<replaceable>module</replaceable>:<replaceable>args</replaceable></literal>, where <replaceable>args</replaceable> are arguments interpreted by the plugin provided by <replaceable>module</replaceable>.</para>
-
-      <para>As an example, in order to load the plugin exported by <literal>Foo.Plugin</literal> in the package <literal>foo-ghc-plugin</literal>, and give it the parameter "baz", we would invoke GHC like this:</para>
-
-<programlisting>
-$ ghc -fplugin Foo.Plugin -fplugin-opt Foo.Plugin:baz Test.hs
-[1 of 1] Compiling Main             ( Test.hs, Test.o )
-Loading package ghc-prim ... linking ... done.
-Loading package integer-gmp ... linking ... done.
-Loading package base ... linking ... done.
-Loading package ffi-1.0 ... linking ... done.
-Loading package foo-ghc-plugin-0.1 ... linking ... done.
-...
-Linking Test ...
-$ 
-</programlisting>
-
-      <para>Since plugins are exported by registered packages, it's safe to put dependencies on them in cabal for example, and specify plugin arguments to GHC through the <literal>ghc-options</literal> field.</para>
-    </sect2>
-
-    <sect2 id="writing-compiler-plugins">
-      <title>Writing compiler plugins</title>
-
-      <para>Plugins are modules that export at least a single identifier, <literal>plugin</literal>, of type <literal>GhcPlugins.Plugin</literal>. All plugins should <literal>import GhcPlugins</literal> as it defines the interface to the compilation pipeline.</para>
-
-      <para>A <literal>Plugin</literal> effectively holds a function which installs a compilation pass into the compiler pipeline. By default there is the empty plugin which does nothing, <literal>GhcPlugins.defaultPlugin</literal>, which you should override with record syntax to specify your installation function. Since the exact fields of the <literal>Plugin</literal> type are open to change, this is the best way to ensure your plugins will continue to work in the future with minimal interface impact.</para>
-
-      <para><literal>Plugin</literal> exports a field, <literal>installCoreToDos</literal> which is a function of type <literal>[CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]</literal>. A <literal>CommandLineOption</literal> is effectively just <literal>String</literal>, and a <literal>CoreToDo</literal> is basically a function of type <literal>Core -> Core</literal>. A <literal>CoreToDo</literal> gives your pass a name and runs it over every compiled module when you invoke GHC.</para>
-
-      <para>As a quick example, here is a simple plugin that just does nothing and just returns the original compilation pipeline, unmodified, and says 'Hello':</para>
-
-<programlisting>
-module DoNothing.Plugin (plugin) where
-import GhcPlugins
-
-plugin :: Plugin
-plugin = defaultPlugin {
-  installCoreToDos = install
-  }
-
-install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
-install _ todo = do
-  reinitializeGlobals
-  putMsgS "Hello!"
-  return todo
-</programlisting>
-
-      <para>Provided you compiled this plugin and registered it in a package (with cabal for instance,) you can then use it by just specifying <literal>-fplugin=DoNothing.Plugin</literal> on the command line, and during the compilation you should see GHC say 'Hello'.</para>
-
-      <para>Note carefully the <literal>reinitializeGlobals</literal> call at the beginning of the installation function. Due to bugs in the windows linker dealing with <literal>libghc</literal>, this call is necessary to properly ensure compiler plugins have the same global state as GHC at the time of invocation. Without <literal>reinitializeGlobals</literal>, compiler plugins can crash at runtime because they may require state that hasn't otherwise been initialized.</para>
-
-      <para>In the future, when the linking bugs are fixed, <literal>reinitializeGlobals</literal> will be deprecated with a warning, and changed to do nothing.</para>
-    </sect2>
-
-    <sect2 id="core-plugins-in-more-detail">
-        <title>Core plugins in more detail</title>
-
-        <para><literal>CoreToDo</literal> is effectively a data type that describes all the kinds of optimization passes GHC does on Core. There are passes for simplification, CSE, vectorisation, etc. There is a specific case for plugins, <literal>CoreDoPluginPass :: String -> PluginPass -> CoreToDo</literal> which should be what you always use when inserting your own pass into the pipeline. The first parameter is the name of the plugin, and the second is the pass you wish to insert.</para>
-
-        <para><literal>CoreM</literal> is a monad that all of the Core optimizations live and operate inside of.</para>
-
-        <para>A plugin's installation function (<literal>install</literal> in the above example) takes a list of <literal>CoreToDo</literal>s and returns a list of <literal>CoreToDo</literal>. Before GHC begins compiling modules, it enumerates all the needed plugins you tell it to load, and runs all of their installation functions, initially on a list of passes that GHC specifies itself. After doing this for every plugin, the final list of passes is given to the optimizer, and are run by simply going over the list in order.</para>
-
-        <para>You should be careful with your installation function, because the list of passes you give back isn't questioned or double checked by GHC at the time of this writing. An installation function like the following:</para>
-
-<programlisting>
-install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
-install _ _ = return []
-</programlisting>
-
-        <para>is certainly valid, but also certainly not what anyone really wants.</para>
-
-      <sect3 id="manipulating-bindings">
-        <title>Manipulating bindings</title>
-
-        <para>In the last section we saw that besides a name, a <literal>CoreDoPluginPass</literal> takes a pass of type <literal>PluginPass</literal>. A <literal>PluginPass</literal> is a synonym for <literal>(ModGuts -> CoreM ModGuts)</literal>. <literal>ModGuts</literal> is a type that represents the one module being compiled by GHC at any given time.</para>
-
-        <para>A <literal>ModGuts</literal> holds all of the module's top level bindings which we can examine. These bindings are of type <literal>CoreBind</literal> and effectively represent the binding of a name to body of code. Top-level module bindings are part of a <literal>ModGuts</literal> in the field <literal>mg_binds</literal>. Implementing a pass that manipulates the top level bindings merely needs to iterate over this field, and return a new <literal>ModGuts</literal> with an updated <literal>mg_binds</literal> field. Because this is such a common case, there is a function provided named <literal>bindsOnlyPass</literal> which lifts a function of type <literal>([CoreBind] -> CoreM [CoreBind])</literal> to type <literal>(ModGuts -> CoreM ModGuts)</literal>. </para>
-
-        <para>Continuing with our example from the last section, we can write a simple plugin that just prints out the name of all the non-recursive bindings in a module it compiles:</para>
-
-<programlisting>
-module SayNames.Plugin (plugin) where
-import GhcPlugins
-
-plugin :: Plugin
-plugin = defaultPlugin {
-  installCoreToDos = install
-  }
-
-install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
-install _ todo = do
-  reinitializeGlobals
-  return (CoreDoPluginPass "Say name" pass : todo)
-
-pass :: ModGuts -> CoreM ModGuts
-pass guts = do dflags &lt;- getDynFlags
-               bindsOnlyPass (mapM (printBind dflags)) guts
-  where printBind :: DynFlags -> CoreBind -> CoreM CoreBind
-        printBind dflags bndr@(NonRec b _) = do
-          putMsgS $ "Non-recursive binding named " ++ showSDoc dflags (ppr b)
-          return bndr 
-        printBind _ bndr = return bndr
-</programlisting>
-      </sect3>
-
-      <sect3 id="getting-annotations">
-        <title>Using Annotations</title>
-        
-        <para>Previously we discussed annotation pragmas (<xref linkend="annotation-pragmas"/>), which we mentioned could be used to give compiler plugins extra guidance or information. Annotations for a module can be retrieved by a plugin, but you must go through the modules <literal>ModGuts</literal> in order to get it. Because annotations can be arbitrary instances of <literal>Data</literal> and <literal>Typeable</literal>, you need to give a type annotation specifying the proper type of data to retrieve from the interface file, and you need to make sure the annotation type used by your users is the same one your plugin uses. For this reason, we advise distributing annotations as part of the package which also provides compiler plugins if possible.</para>
-
-        <para>To get the annotations of a single binder, you can use `getAnnotations` and specify the proper type. Here's an example that will print out the name of any top-level non-recursive binding with the <literal>SomeAnn</literal> annotation:</para>
-
-<programlisting>
-{-# LANGUAGE DeriveDataTypeable #-}
-module SayAnnNames.Plugin (plugin, SomeAnn(..)) where
-import GhcPlugins
-import Control.Monad (unless)
-import Data.Data
-
-data SomeAnn = SomeAnn deriving (Data, Typeable)
-
-plugin :: Plugin
-plugin = defaultPlugin {
-  installCoreToDos = install
-  }
-
-install :: [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
-install _ todo = do
-  reinitializeGlobals
-  return (CoreDoPluginPass "Say name" pass : todo)
-
-pass :: ModGuts -> CoreM ModGuts
-pass g = do
-          dflags &lt;- getDynFlags
-          mapM_ (printAnn dflags g) (mg_binds g) >> return g
-  where printAnn :: DynFlags -> ModGuts -> CoreBind -> CoreM CoreBind
-        printAnn dflags guts bndr@(NonRec b _) = do
-          anns &lt;- annotationsOn guts b :: CoreM [SomeAnn]
-          unless (null anns) $ putMsgS $ "Annotated binding found: " ++  showSDoc dflags (ppr b)
-          return bndr
-        printAnn _ _ bndr = return bndr
-
-annotationsOn :: Data a => ModGuts -> CoreBndr -> CoreM [a]
-annotationsOn guts bndr = do
-  anns &lt;- getAnnotations deserializeWithData guts
-  return $ lookupWithDefaultUFM anns [] (varUnique bndr)
-</programlisting>
-
-        <para>Please see the GHC API documentation for more about how to use internal APIs, etc.</para>
-      </sect3>
-    </sect2>
-
-    <sect2 id="typechecker-plugins">
-      <title>Typechecker plugins</title>
-
-      <para>In addition to Core plugins, GHC has experimental support for typechecker plugins, which allow the behaviour of the constraint solver to be modified. For example, they make it possible to interface the compiler to an SMT solver, in order to support a richer theory of type-level arithmetic expressions than the theory built into GHC (see <xref linkend="typelit-tyfuns"/>).</para>
-
-      <para>The <literal>Plugin</literal> type has a field <literal>tcPlugin</literal> of type <literal>[CommandLineOption] -> Maybe TcPlugin</literal>, where the <literal>TcPlugin</literal> type is defined thus:</para>
-
-<programlisting>
-data TcPlugin = forall s . TcPlugin
-  { tcPluginInit  :: TcPluginM s
-  , tcPluginSolve :: s -> TcPluginSolver
-  , tcPluginStop  :: s -> TcPluginM ()
-  }
-
-type TcPluginSolver = [Ct] -> [Ct] -> [Ct] -> TcPluginM TcPluginResult
-
-data TcPluginResult = TcPluginContradiction [Ct] | TcPluginOk [(EvTerm,Ct)] [Ct]
-</programlisting>
-
-      <para>(The details of this representation are subject to change as we gain more experience writing typechecker plugins. It should not be assumed to be stable between GHC releases.)</para>
-
-      <para>The basic idea is as follows:
-      <itemizedlist>
-        <listitem><para>When type checking a module, GHC calls <literal>tcPluginInit</literal> once before constraint solving starts. This allows the plugin to look things up in the context, initialise mutable state or open a connection to an external process (e.g. an external SMT solver). The plugin can return a result of any type it likes, and the result will be passed to the other two fields.</para></listitem>
-        <listitem><para>During constraint solving, GHC repeatedly calls <literal>tcPluginSolve</literal>. This function is provided with the current set of constraints, and should return a <literal>TcPluginResult</literal> that indicates whether a contradiction was found or progress was made. If the plugin solver makes progress, GHC will re-start the constraint solving pipeline, looping until a fixed point is reached.</para></listitem>
-        <listitem><para>Finally, GHC calls <literal>tcPluginStop</literal> after constraint solving is finished, allowing the plugin to dispose of any resources it has allocated (e.g. terminating the SMT solver process).</para></listitem>
-      </itemizedlist>
-      </para>
-
-      <para>Plugin code runs in the <literal>TcPluginM</literal> monad, which provides a restricted interface to GHC API functionality that is relevant for typechecker plugins, including <literal>IO</literal> and reading the environment. If you need functionality that is not exposed in the <literal>TcPluginM</literal> module, you can use <literal>unsafeTcPluginTcM :: TcM a -> TcPluginM a</literal>, but are encouraged to contact the GHC team to suggest additions to the interface. Note that <literal>TcPluginM</literal> can perform arbitrary IO via <literal>tcPluginIO :: IO a -> TcPluginM a</literal>, although some care must be taken with side effects (particularly in <literal>tcPluginSolve</literal>). In general, it is up to the plugin author to make sure that any IO they do is safe.</para>
-
-      <sect3 id="constraint-solving-with-plugins">
-
-        <title>Constraint solving with plugins</title>
-
-        <para>The key component of a typechecker plugin is a function of type <literal>TcPluginSolver</literal>, like this:</para>
-
-<programlisting>
-solve :: [Ct] -> [Ct] -> [Ct] -> TcPluginM TcPluginResult
-solve givens deriveds wanteds = ...
-</programlisting>
-
-        <para>This function will be invoked at two points in the constraint solving process: after simplification of given constraints, and after unflattening of wanted constraints. The two phases can be distinguished because the deriveds and wanteds will be empty in the first case. In each case, the plugin should either
-        <itemizedlist>
-          <listitem><para>return <literal>TcPluginContradiction</literal> with a list of impossible constraints (which must be a subset of those passed in), so they can be turned into errors; or</para></listitem>
-          <listitem><para>return <literal>TcPluginOk</literal> with lists of solved and new constraints (the former must be a subset of those passed in and must be supplied with corresponding evidence terms).</para></listitem>
-        </itemizedlist>
-        If the plugin cannot make any progress, it should return <literal>TcPluginOk [] []</literal>. Otherwise, if there were any new constraints, the main constraint solver will be re-invoked to simplify them, then the plugin will be invoked again. The plugin is responsible for making sure that this process eventually terminates.</para>
-
-        <para>Plugins are provided with all available constraints (including equalities and typeclass constraints), but it is easy for them to discard those that are not relevant to their domain, because they need return only those constraints for which they have made progress (either by solving or contradicting them).</para>
-
-        <para>Constraints that have been solved by the plugin must be provided with evidence in the form of an <literal>EvTerm</literal> of the type of the constraint. This evidence is ignored for given and derived constraints, which GHC "solves" simply by discarding them; typically this is used when they are uninformative (e.g. reflexive equations). For wanted constraints, the evidence will form part of the Core term that is generated after typechecking, and can be checked by <option>-dcore-lint</option>. It is possible for the plugin to create equality axioms for use in evidence terms, but GHC does not check their consistency, and inconsistent axiom sets may lead to segfaults or other runtime misbehaviour.</para>
-      </sect3>
-    </sect2>
-  </sect1>
-
-</chapter>
-
-<!-- Emacs stuff:
-     ;;; Local Variables: ***
-     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
-     ;;; ispell-local-dictionary: "british" ***
-     ;;; End: ***
- -->
diff --git a/docs/users_guide/ffi-chap.rst b/docs/users_guide/ffi-chap.rst
new file mode 100644 (file)
index 0000000..f9ebe5a
--- /dev/null
@@ -0,0 +1,658 @@
+.. _ffi:
+
+Foreign function interface (FFI)
+================================
+
+.. index::
+   single: -XForeignFunctionInterface
+   single: Foreign function interface
+   single: interfacing with native code
+
+GHC (mostly) conforms to the Haskell Foreign Function Interface, whose
+definition is part of the Haskell Report on
+```http://www.haskell.org/`` <http://www.haskell.org/>`__.
+
+FFI support is enabled by default, but can be enabled or disabled
+explicitly with the ``-XForeignFunctionInterface`` flag.
+
+GHC implements a number of GHC-specific extensions to the FFI Addendum.
+These extensions are described in :ref:`ffi-ghcexts`, but please note
+that programs using these features are not portable. Hence, these
+features should be avoided where possible.
+
+The FFI libraries are documented in the accompanying library
+documentation; see for example the :base-ref:`Foreign` module.
+
+.. _ffi-ghcexts:
+
+GHC extensions to the FFI Addendum
+----------------------------------
+
+The FFI features that are described in this section are specific to GHC.
+Your code will not be portable to other compilers if you use them.
+
+Unboxed types
+~~~~~~~~~~~~~
+
+The following unboxed types may be used as basic foreign types (see FFI
+Addendum, Section 3.2): ``Int#``, ``Word#``, ``Char#``, ``Float#``,
+``Double#``, ``Addr#``, ``StablePtr# a``, ``MutableByteArray#``,
+``ForeignObj#``, and ``ByteArray#``.
+
+.. _ffi-newtype-io:
+
+Newtype wrapping of the IO monad
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The FFI spec requires the IO monad to appear in various places, but it
+can sometimes be convenient to wrap the IO monad in a ``newtype``, thus:
+
+::
+
+      newtype MyIO a = MIO (IO a)
+
+(A reason for doing so might be to prevent the programmer from calling
+arbitrary IO procedures in some part of the program.)
+
+The Haskell FFI already specifies that arguments and results of foreign
+imports and exports will be automatically unwrapped if they are newtypes
+(Section 3.2 of the FFI addendum). GHC extends the FFI by automatically
+unwrapping any newtypes that wrap the IO monad itself. More precisely,
+wherever the FFI specification requires an ``IO`` type, GHC will accept any
+newtype-wrapping of an ``IO`` type. For example, these declarations are OK:
+
+::
+
+       foreign import foo :: Int -> MyIO Int
+       foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
+
+.. _ffi-prim:
+
+Primitive imports
+~~~~~~~~~~~~~~~~~
+
+GHC extends the FFI with an additional calling convention ``prim``,
+e.g.:
+
+::
+
+       foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #)
+
+This is used to import functions written in Cmm code that follow an
+internal GHC calling convention. The arguments and results must be
+unboxed types, except that an argument may be of type ``Any`` (by way of
+``unsafeCoerce#``) and the result type is allowed to be an unboxed tuple
+or the type ``Any``.
+
+This feature is not intended for use outside of the core libraries that
+come with GHC. For more details see the
+:ghc-wiki:`GHC developer wiki <Commentary/PrimOps>`.
+
+.. _ffi-interruptible:
+
+Interruptible foreign calls
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This concerns the interaction of foreign calls with
+``Control.Concurrent.throwTo``. Normally when the target of a
+``throwTo`` is involved in a foreign call, the exception is not raised
+until the call returns, and in the meantime the caller is blocked. This
+can result in unresponsiveness, which is particularly undesirable in the
+case of user interrupt (e.g. Control-C). The default behaviour when a
+Control-C signal is received (``SIGINT`` on Unix) is to raise the
+``UserInterrupt`` exception in the main thread; if the main thread is
+blocked in a foreign call at the time, then the program will not respond
+to the user interrupt.
+
+The problem is that it is not possible in general to interrupt a foreign
+call safely. However, GHC does provide a way to interrupt blocking
+system calls which works for most system calls on both Unix and Windows.
+When the ``InterruptibleFFI`` extension is enabled, a foreign call can
+be annotated with ``interruptible`` instead of ``safe`` or ``unsafe``:
+
+::
+
+    foreign import ccall interruptible
+       "sleep" sleepBlock :: CUint -> IO CUint
+
+``interruptible`` behaves exactly as ``safe``, except that when a
+``throwTo`` is directed at a thread in an interruptible foreign call, an
+OS-specific mechanism will be used to attempt to cause the foreign call
+to return:
+
+Unix systems
+    The thread making the foreign call is sent a ``SIGPIPE`` signal
+    using ``pthread_kill()``. This is usually enough to cause a blocking
+    system call to return with ``EINTR`` (GHC by default installs an
+    empty signal handler for ``SIGPIPE``, to override the default
+    behaviour which is to terminate the process immediately).
+
+Windows systems
+    [Vista and later only] The RTS calls the Win32 function
+    ``CancelSynchronousIO``, which will cause a blocking I/O operation
+    to return with the error ``ERROR_OPERATION_ABORTED``.
+
+If the system call is successfully interrupted, it will return to
+Haskell whereupon the exception can be raised. Be especially careful
+when using ``interruptible`` that the caller of the foreign function is
+prepared to deal with the consequences of the call being interrupted; on
+Unix it is good practice to check for ``EINTR`` always, but on Windows
+it is not typically necessary to handle ``ERROR_OPERATION_ABORTED``.
+
+.. _ffi-capi:
+
+The CAPI calling convention
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``CApiFFI`` extension allows a calling convention of ``capi`` to be
+used in foreign declarations, e.g.
+
+::
+
+    foreign import capi "header.h f" f :: CInt -> IO CInt
+
+Rather than generating code to call ``f`` according to the platform's
+ABI, we instead call ``f`` using the C API defined in the header
+``header.h``. Thus ``f`` can be called even if it may be defined as a
+CPP ``#define`` rather than a proper function.
+
+When using ``capi``, it is also possible to import values, rather than
+functions. For example,
+
+::
+
+    foreign import capi "pi.h value pi" c_pi :: CDouble
+
+will work regardless of whether ``pi`` is defined as
+
+::
+
+    const double pi = 3.14;
+
+or with
+
+::
+
+    #define pi 3.14
+
+In order to tell GHC the C type that a Haskell type corresponds to when
+it is used with the CAPI, a ``CTYPE`` pragma can be used on the type
+definition. The header which defines the type can optionally also be
+specified. The syntax looks like:
+
+::
+
+    data    {-# CTYPE "unistd.h" "useconds_t" #-} T = ...
+    newtype {-# CTYPE            "useconds_t" #-} T = ...
+
+``hs_thread_done()``
+~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    void hs_thread_done(void);
+
+GHC allocates a small amount of thread-local memory when a thread calls
+a Haskell function via a ``foreign export``. This memory is not normally
+freed until ``hs_exit()``; the memory is cached so that subsequent calls
+into Haskell are fast. However, if your application is long-running and
+repeatedly creates new threads that call into Haskell, you probably want
+to arrange that this memory is freed in those threads that have finished
+calling Haskell functions. To do this, call ``hs_thread_done()`` from
+the thread whose memory you want to free.
+
+Calling ``hs_thread_done()`` is entirely optional. You can call it as
+often or as little as you like. It is safe to call it from a thread that
+has never called any Haskell functions, or one that never will. If you
+forget to call it, the worst that can happen is that some memory remains
+allocated until ``hs_exit()`` is called. If you call it too often, the
+worst that can happen is that the next call to a Haskell function incurs
+some extra overhead.
+
+.. _ffi-ghc:
+
+Using the FFI with GHC
+----------------------
+
+The following sections also give some hints and tips on the use of the
+foreign function interface in GHC.
+
+.. _foreign-export-ghc:
+
+Using ``foreign export`` and ``foreign import ccall "wrapper"`` with GHC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. index::
+   single: foreign export; with GHC
+
+When GHC compiles a module (say ``M.hs``) which uses ``foreign export``
+or ``foreign import "wrapper"``, it generates a ``M_stub.h`` for use by
+C programs.
+
+For a plain ``foreign export``, the file ``M_stub.h`` contains a C
+prototype for the foreign exported function. For example, if we compile
+the following module:
+
+::
+
+    module Foo where
+
+    foreign export ccall foo :: Int -> IO Int
+
+    foo :: Int -> IO Int
+    foo n = return (length (f n))
+
+    f :: Int -> [Int]
+    f 0 = []
+    f n = n:(f (n-1))
+
+Then ``Foo_stub.h`` will contain something like this:
+
+::
+
+    #include "HsFFI.h"
+    extern HsInt foo(HsInt a0);
+
+To invoke ``foo()`` from C, just ``#include "Foo_stub.h"`` and call
+``foo()``.
+
+The ``Foo_stub.h`` file can be redirected using the ``-stubdir`` option;
+see :ref:`options-output`.
+
+.. _using-own-main:
+
+Using your own ``main()``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Normally, GHC's runtime system provides a ``main()``, which arranges to
+invoke ``Main.main`` in the Haskell program. However, you might want to
+link some Haskell code into a program which has a main function written
+in another language, say C. In order to do this, you have to initialize
+the Haskell runtime system explicitly.
+
+Let's take the example from above, and invoke it from a standalone C
+program. Here's the C code:
+
+::
+
+    #include <stdio.h>
+    #include "HsFFI.h"
+
+    #ifdef __GLASGOW_HASKELL__
+    #include "Foo_stub.h"
+    #endif
+
+    int main(int argc, char *argv[])
+    {
+      int i;
+
+      hs_init(&argc, &argv);
+
+      for (i = 0; i < 5; i++) {
+        printf("%d\n", foo(2500));
+      }
+
+      hs_exit();
+      return 0;
+    }
+
+We've surrounded the GHC-specific bits with
+``#ifdef __GLASGOW_HASKELL__``; the rest of the code should be portable
+across Haskell implementations that support the FFI standard.
+
+The call to ``hs_init()`` initializes GHC's runtime system. Do NOT try
+to invoke any Haskell functions before calling ``hs_init()``: bad things
+will undoubtedly happen.
+
+We pass references to ``argc`` and ``argv`` to ``hs_init()`` so that it
+can separate out any arguments for the RTS (i.e. those arguments between
+``+RTS...-RTS``).
+
+After we've finished invoking our Haskell functions, we can call
+``hs_exit()``, which terminates the RTS.
+
+There can be multiple calls to ``hs_init()``, but each one should be
+matched by one (and only one) call to ``hs_exit()`` [1]_.
+
+.. note::
+    When linking the final program, it is normally easiest to do the
+    link using GHC, although this isn't essential. If you do use GHC, then
+    don't forget the flag ``-no-hs-main``\ ``-no-hs-main``, otherwise GHC
+    will try to link to the ``Main`` Haskell module.
+
+.. [1]
+   The outermost ``hs_exit()`` will actually de-initialise the system.
+   NOTE that currently GHC's runtime cannot reliably re-initialise after
+   this has happened, see :ref:`infelicities-ffi`.
+
+To use ``+RTS`` flags with ``hs_init()``, we have to modify the example
+slightly. By default, GHC's RTS will only accept "safe" ``+RTS`` flags
+(see :ref:`options-linker`), and the ``-rtsopts``\ ``-rtsopts``
+link-time flag overrides this. However, ``-rtsopts`` has no effect when
+``-no-hs-main`` is in use (and the same goes for ``-with-rtsopts``). To
+set these options we have to call a GHC-specific API instead of
+``hs_init()``:
+
+::
+
+    #include <stdio.h>
+    #include "HsFFI.h"
+
+    #ifdef __GLASGOW_HASKELL__
+    #include "Foo_stub.h"
+    #include "Rts.h"
+    #endif
+
+    int main(int argc, char *argv[])
+    {
+      int i;
+
+    #if __GLASGOW_HASKELL__ >= 703
+      {
+          RtsConfig conf = defaultRtsConfig;
+          conf.rts_opts_enabled = RtsOptsAll;
+          hs_init_ghc(&argc, &argv, conf);
+      }
+    #else
+      hs_init(&argc, &argv);
+    #endif
+
+      for (i = 0; i < 5; i++) {
+        printf("%d\n", foo(2500));
+      }
+
+      hs_exit();
+      return 0;
+    }
+
+Note two changes: we included ``Rts.h``, which defines the GHC-specific
+external RTS interface, and we called ``hs_init_ghc()`` instead of
+``hs_init()``, passing an argument of type ``RtsConfig``. ``RtsConfig``
+is a struct with various fields that affect the behaviour of the runtime
+system. Its definition is:
+
+::
+
+    typedef struct {
+        RtsOptsEnabledEnum rts_opts_enabled;
+        const char *rts_opts;
+    } RtsConfig;
+
+    extern const RtsConfig defaultRtsConfig;
+
+    typedef enum {
+        RtsOptsNone,         // +RTS causes an error
+        RtsOptsSafeOnly,     // safe RTS options allowed; others cause an error
+        RtsOptsAll           // all RTS options allowed
+      } RtsOptsEnabledEnum;
+
+There is a default value ``defaultRtsConfig`` that should be used to
+initialise variables of type ``RtsConfig``. More fields will undoubtedly
+be added to ``RtsConfig`` in the future, so in order to keep your code
+forwards-compatible it is best to initialise with ``defaultRtsConfig``
+and then modify the required fields, as in the code sample above.
+
+.. _ffi-library:
+
+Making a Haskell library that can be called from foreign code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The scenario here is much like in :ref:`using-own-main`, except that the
+aim is not to link a complete program, but to make a library from
+Haskell code that can be deployed in the same way that you would deploy
+a library of C code.
+
+The main requirement here is that the runtime needs to be initialized
+before any Haskell code can be called, so your library should provide
+initialisation and deinitialisation entry points, implemented in C or
+C++. For example:
+
+::
+
+    #include <stdlib.h>
+    #include "HsFFI.h"
+
+    HsBool mylib_init(void){
+      int argc = 2;
+      char *argv[] = { "+RTS", "-A32m", NULL };
+      char **pargv = argv;
+
+      // Initialize Haskell runtime
+      hs_init(&argc, &pargv);
+
+      // do any other initialization here and
+      // return false if there was a problem
+      return HS_BOOL_TRUE;
+    }
+
+    void mylib_end(void){
+      hs_exit();
+    }
+
+The initialisation routine, ``mylib_init``, calls ``hs_init()`` as
+normal to initialise the Haskell runtime, and the corresponding
+deinitialisation function ``mylib_end()`` calls ``hs_exit()`` to shut
+down the runtime.
+
+.. _glasgow-foreign-headers:
+
+Using header files
+~~~~~~~~~~~~~~~~~~
+
+.. index::
+   single: C calls, function headers
+
+C functions are normally declared using prototypes in a C header file.
+Earlier versions of GHC (6.8.3 and earlier) ``#include``\ d the header
+file in the C source file generated from the Haskell code, and the C
+compiler could therefore check that the C function being called via the
+FFI was being called at the right type.
+
+GHC no longer includes external header files when compiling via C, so
+this checking is not performed. The change was made for compatibility
+with the :ref:`native code generator <native-code-gen>` (``-fasm``) and to
+comply strictly with the FFI specification, which requires that FFI calls are
+not subject to macro expansion and other CPP conversions that may be applied
+when using C header files. This approach also simplifies the inlining of foreign
+calls across module and package boundaries: there's no need for the header file
+to be available when compiling an inlined version of a foreign call, so the
+compiler is free to inline foreign calls in any context.
+
+The ``-#include`` option is now deprecated, and the ``include-files``
+field in a Cabal package specification is ignored.
+
+Memory Allocation
+~~~~~~~~~~~~~~~~~
+
+The FFI libraries provide several ways to allocate memory for use with
+the FFI, and it isn't always clear which way is the best. This decision
+may be affected by how efficient a particular kind of allocation is on a
+given compiler/platform, so this section aims to shed some light on how
+the different kinds of allocation perform with GHC.
+
+``alloca``
+    Useful for short-term allocation when the allocation is intended to
+    scope over a given ``IO`` computation. This kind of allocation is
+    commonly used when marshalling data to and from FFI functions.
+
+    In GHC, ``alloca`` is implemented using ``MutableByteArray#``, so
+    allocation and deallocation are fast: much faster than C's
+    ``malloc/free``, but not quite as fast as stack allocation in C. Use
+    ``alloca`` whenever you can.
+
+``mallocForeignPtr``
+    Useful for longer-term allocation which requires garbage collection.
+    If you intend to store the pointer to the memory in a foreign data
+    structure, then ``mallocForeignPtr`` is *not* a good choice,
+    however.
+
+    In GHC, ``mallocForeignPtr`` is also implemented using
+    ``MutableByteArray#``. Although the memory is pointed to by a
+    ``ForeignPtr``, there are no actual finalizers involved (unless you
+    add one with ``addForeignPtrFinalizer``), and the deallocation is
+    done using GC, so ``mallocForeignPtr`` is normally very cheap.
+
+``malloc/free``
+    If all else fails, then you need to resort to ``Foreign.malloc`` and
+    ``Foreign.free``. These are just wrappers around the C functions of
+    the same name, and their efficiency will depend ultimately on the
+    implementations of these functions in your platform's C library. We
+    usually find ``malloc`` and ``free`` to be significantly slower than
+    the other forms of allocation above.
+
+``Foreign.Marshal.Pool``
+    Pools are currently implemented using ``malloc/free``, so while they
+    might be a more convenient way to structure your memory allocation
+    than using one of the other forms of allocation, they won't be any
+    more efficient. We do plan to provide an improved-performance
+    implementation of Pools in the future, however.
+
+.. _ffi-threads:
+
+Multi-threading and the FFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to use the FFI in a multi-threaded setting, you must use the
+``-threaded`` option (see :ref:`options-linker`).
+
+Foreign imports and multi-threading
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When you call a ``foreign import``\ ed function that is annotated as
+``safe`` (the default), and the program was linked using ``-threaded``,
+then the call will run concurrently with other running Haskell threads.
+If the program was linked without ``-threaded``, then the other Haskell
+threads will be blocked until the call returns.
+
+This means that if you need to make a foreign call to a function that
+takes a long time or blocks indefinitely, then you should mark it
+``safe`` and use ``-threaded``. Some library functions make such calls
+internally; their documentation should indicate when this is the case.
+
+If you are making foreign calls from multiple Haskell threads and using
+``-threaded``, make sure that the foreign code you are calling is
+thread-safe. In particularly, some GUI libraries are not thread-safe and
+require that the caller only invokes GUI methods from a single thread.
+If this is the case, you may need to restrict your GUI operations to a
+single Haskell thread, and possibly also use a bound thread (see
+:ref:`haskell-threads-and-os-threads`).
+
+Note that foreign calls made by different Haskell threads may execute in
+*parallel*, even when the ``+RTS -N`` flag is not being used
+(:ref:`parallel-options`). The ``+RTS -N`` flag controls parallel
+execution of Haskell threads, but there may be an arbitrary number of
+foreign calls in progress at any one time, regardless of the ``+RTS -N``
+value.
+
+If a call is annotated as ``interruptible`` and the program was
+multithreaded, the call may be interrupted in the event that the Haskell
+thread receives an exception. The mechanism by which the interrupt
+occurs is platform dependent, but is intended to cause blocking system
+calls to return immediately with an interrupted error code. The
+underlying operating system thread is not to be destroyed. See
+:ref:`ffi-interruptible` for more details.
+
+.. _haskell-threads-and-os-threads:
+
+The relationship between Haskell threads and OS threads
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Normally there is no fixed relationship between Haskell threads and OS
+threads. This means that when you make a foreign call, that call may
+take place in an unspecified OS thread. Furthermore, there is no
+guarantee that multiple calls made by one Haskell thread will be made by
+the same OS thread.
+
+This usually isn't a problem, and it allows the GHC runtime system to
+make efficient use of OS thread resources. However, there are cases
+where it is useful to have more control over which OS thread is used,
+for example when calling foreign code that makes use of thread-local
+state. For cases like this, we provide *bound threads*, which are
+Haskell threads tied to a particular OS thread. For information on bound
+threads, see the documentation for the :base-ref:`Control.Concurrent` module.
+
+Foreign exports and multi-threading
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the program is linked with ``-threaded``, then you may invoke
+``foreign export``\ ed functions from multiple OS threads concurrently.
+The runtime system must be initialised as usual by calling
+``hs_init()``, and this call must complete before invoking any
+``foreign export``\ ed functions.
+
+.. _hs-exit:
+
+On the use of ``hs_exit()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``hs_exit()`` normally causes the termination of any running Haskell
+threads in the system, and when ``hs_exit()`` returns, there will be no
+more Haskell threads running. The runtime will then shut down the system
+in an orderly way, generating profiling output and statistics if
+necessary, and freeing all the memory it owns.
+
+It isn't always possible to terminate a Haskell thread forcibly: for
+example, the thread might be currently executing a foreign call, and we
+have no way to force the foreign call to complete. What's more, the
+runtime must assume that in the worst case the Haskell code and runtime
+are about to be removed from memory (e.g. if this is a
+:ref:`Windows DLL <win32-dlls>`, ``hs_exit()`` is normally called before unloading
+the DLL). So ``hs_exit()`` *must* wait until all outstanding foreign
+calls return before it can return itself.
+
+The upshot of this is that if you have Haskell threads that are blocked
+in foreign calls, then ``hs_exit()`` may hang (or possibly busy-wait)
+until the calls return. Therefore it's a good idea to make sure you
+don't have any such threads in the system when calling ``hs_exit()``.
+This includes any threads doing I/O, because I/O may (or may not,
+depending on the type of I/O and the platform) be implemented using
+blocking foreign calls.
+
+The GHC runtime treats program exit as a special case, to avoid the need
+to wait for blocked threads when a standalone executable exits. Since
+the program and all its threads are about to terminate at the same time
+that the code is removed from memory, it isn't necessary to ensure that
+the threads have exited first. (Unofficially, if you want to use this
+fast and loose version of ``hs_exit()``, then call
+``shutdownHaskellAndExit()`` instead).
+
+.. _ffi-floating-point:
+
+Floating point and the FFI
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. index::
+   single: Floating point; and the FFI
+
+The standard C99 ``fenv.h`` header provides operations for inspecting
+and modifying the state of the floating point unit. In particular, the
+rounding mode used by floating point operations can be changed, and the
+exception flags can be tested.
+
+In Haskell, floating-point operations have pure types, and the
+evaluation order is unspecified. So strictly speaking, since the
+``fenv.h`` functions let you change the results of, or observe the
+effects of floating point operations, use of ``fenv.h`` renders the
+behaviour of floating-point operations anywhere in the program
+undefined.
+
+Having said that, we *can* document exactly what GHC does with respect
+to the floating point state, so that if you really need to use
+``fenv.h`` then you can do so with full knowledge of the pitfalls:
+
+-  GHC completely ignores the floating-point environment, the runtime
+   neither modifies nor reads it.
+
+-  The floating-point environment is not saved over a normal thread
+   context-switch. So if you modify the floating-point state in one
+   thread, those changes may be visible in other threads. Furthermore,
+   testing the exception state is not reliable, because a context switch
+   may change it. If you need to modify or test the floating point state
+   and use threads, then you must use bound threads
+   (``Control.Concurrent.forkOS``), because a bound thread has its own
+   OS thread, and OS threads do save and restore the floating-point
+   state.
+
+-  It is safe to modify the floating-point unit state temporarily during
+   a foreign call, because foreign calls are never pre-empted by GHC.
+
diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml
deleted file mode 100644 (file)
index 8417ef5..0000000
+++ /dev/null
@@ -1,818 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- FFI docs as a chapter -->
-
-<chapter id="ffi">
- <title>
-Foreign function interface (FFI)
- </title>
-
-  <para>GHC (mostly) conforms to the Haskell Foreign Function Interface,
-  whose definition is part of the Haskell Report on <ulink url="http://www.haskell.org/"><literal>http://www.haskell.org/</literal></ulink>.</para>
-
-  <para>FFI support is enabled by default, but can be enabled or disabled explicitly with the <option>-XForeignFunctionInterface</option><indexterm><primary><option>-XForeignFunctionInterface</option></primary>
-    </indexterm> flag.</para>
-
-  <para>GHC implements a number of GHC-specific extensions to the FFI
-    Addendum.  These extensions are described in <xref linkend="ffi-ghcexts" />, but please note that programs using
-    these features are not portable.  Hence, these features should be
-    avoided where possible.</para>
-
-  <para>The FFI libraries are documented in the accompanying library
-  documentation; see for example the
-    <ulink url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Foreign</literal></ulink> module.</para>
-
-  <sect1 id="ffi-ghcexts">
-    <title>GHC extensions to the FFI Addendum</title>
-
-    <para>The FFI features that are described in this section are specific to
-    GHC.  Your code will not be portable to other compilers if you use them.</para>
-
-    <sect2>
-      <title>Unboxed types</title>
-
-      <para>The following unboxed types may be used as basic foreign types
-      (see FFI Addendum, Section 3.2): <literal>Int#</literal>,
-      <literal>Word#</literal>, <literal>Char#</literal>,
-      <literal>Float#</literal>, <literal>Double#</literal>,
-      <literal>Addr#</literal>, <literal>StablePtr# a</literal>,
-      <literal>MutableByteArray#</literal>, <literal>ForeignObj#</literal>,
-      and <literal>ByteArray#</literal>.</para>
-    </sect2>
-
-    <sect2 id="ffi-newtype-io">
-      <title>Newtype wrapping of the IO monad</title>
-      <para>The FFI spec requires the IO monad to appear in various  places,
-      but it can sometimes be convenient to wrap the IO monad in a
-      <literal>newtype</literal>, thus:
-<programlisting>
-  newtype MyIO a = MIO (IO a)
-</programlisting>
-     (A reason for doing so might be to prevent the programmer from
-       calling arbitrary IO procedures in some part of the program.)
-</para>
-<para>The Haskell FFI already specifies that arguments and results of
-foreign imports and exports will be automatically unwrapped if they are
-newtypes (Section 3.2 of the FFI addendum).  GHC extends the FFI by automatically unwrapping any newtypes that
-wrap the IO monad itself.
-More precisely, wherever the FFI specification requires an IO type, GHC will
-accept any newtype-wrapping of an IO type.  For example, these declarations are
-OK:
-<programlisting>
-   foreign import foo :: Int -> MyIO Int
-   foreign import "dynamic" baz :: (Int -> MyIO Int) -> CInt -> MyIO Int
-</programlisting>
-</para>
-      </sect2>
-
-      <sect2 id="ffi-prim">
-        <title>Primitive imports</title>
-       <para>
-         GHC extends the FFI with an additional calling convention
-         <literal>prim</literal>, e.g.:
-<programlisting>
-   foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #)
-</programlisting>
-         This is used to import functions written in Cmm code that follow an
-         internal GHC calling convention.  The arguments and results must
-         be unboxed types, except that an argument may be of type
-         <literal>Any</literal> (by way of <literal>unsafeCoerce#</literal>)
-         and the result type is allowed to be an unboxed tuple or the
-         type <literal>Any</literal>.
-       </para>
-       <para>
-         This feature is not intended for
-         use outside of the core libraries that come with GHC. For more
-         details see the <ulink linkend="http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps">
-          GHC developer wiki</ulink>.
-       </para>
-      </sect2>
-
-      <sect2 id="ffi-interruptible">
-        <title>Interruptible foreign calls</title>
-        <para>
-          This concerns the interaction of foreign calls
-          with <literal>Control.Concurrent.throwTo</literal>.
-          Normally when the target of a <literal>throwTo</literal> is
-          involved in a foreign call, the exception is not raised
-          until the call returns, and in the meantime the caller is
-          blocked.  This can result in unresponsiveness, which is
-          particularly undesirable in the case of user interrupt
-          (e.g. Control-C).  The default behaviour when a Control-C
-          signal is received (<literal>SIGINT</literal> on Unix) is to raise
-          the <literal>UserInterrupt</literal> exception in the main
-          thread; if the main thread is blocked in a foreign call at
-          the time, then the program will not respond to the user
-          interrupt.
-        </para>
-
-        <para>
-          The problem is that it is not possible in general to
-          interrupt a foreign call safely.  However, GHC does provide
-          a way to interrupt blocking system calls which works for
-          most system calls on both Unix and Windows.  When the
-          <literal>InterruptibleFFI</literal> extension is enabled,
-          a foreign call
-          can be annotated with <literal>interruptible</literal> instead
-          of <literal>safe</literal> or <literal>unsafe</literal>:
-
-<programlisting>
-foreign import ccall interruptible
-   "sleep" sleepBlock :: CUint -> IO CUint
-</programlisting>
-
-          <literal>interruptible</literal> behaves exactly as
-          <literal>safe</literal>, except that when
-          a <literal>throwTo</literal> is directed at a thread in an
-          interruptible foreign call, an OS-specific mechanism will be
-          used to attempt to cause the foreign call to return:
-
-          <variablelist>
-            <varlistentry>
-              <term>Unix systems</term>
-              <listitem>
-                <para>
-                  The thread making the foreign call is sent
-                  a <literal>SIGPIPE</literal> signal
-                  using <literal>pthread_kill()</literal>.  This is
-                  usually enough to cause a blocking system call to
-                  return with <literal>EINTR</literal> (GHC by default
-                  installs an empty signal handler
-                  for <literal>SIGPIPE</literal>, to override the
-                  default behaviour which is to terminate the process
-                  immediately).
-                </para>
-              </listitem>
-            </varlistentry>
-            <varlistentry>
-              <term>Windows systems</term>
-              <listitem>
-                <para>
-                  [Vista and later only] The RTS calls the Win32
-                  function <literal>CancelSynchronousIO</literal>,
-                  which will cause a blocking I/O operation to return
-                  with the
-                  error <literal>ERROR_OPERATION_ABORTED</literal>.
-                </para>
-              </listitem>
-            </varlistentry>
-          </variablelist>
-
-          If the system call is successfully interrupted, it will
-          return to Haskell whereupon the exception can be raised.  Be
-          especially careful when
-          using <literal>interruptible</literal> that the caller of
-          the foreign function is prepared to deal with the
-          consequences of the call being interrupted; on Unix it is
-          good practice to check for <literal>EINTR</literal> always,
-          but on Windows it is not typically necessary to
-          handle <literal>ERROR_OPERATION_ABORTED</literal>.
-        </para>
-      </sect2>
-
-      <sect2 id="ffi-capi">
-        <title>The CAPI calling convention</title>
-        <para>
-          The <literal>CApiFFI</literal> extension allows a calling
-          convention of <literal>capi</literal> to be used in foreign
-          declarations, e.g.
-
-<programlisting>
-foreign import capi "header.h f" f :: CInt -> IO CInt
-</programlisting>
-
-          Rather than generating code to call <literal>f</literal>
-          according to the platform's ABI, we instead call
-          <literal>f</literal> using the C API defined in the header
-          <literal>header.h</literal>. Thus <literal>f</literal> can be
-          called even if it may be defined as a CPP
-          <literal>#define</literal> rather than a proper function.
-        </para>
-
-        <para>
-          When using <literal>capi</literal>, it is also possible to
-          import values, rather than functions. For example,
-
-<programlisting>
-foreign import capi "pi.h value pi" c_pi :: CDouble
-</programlisting>
-
-          will work regardless of whether <literal>pi</literal> is
-          defined as
-<programlisting>
-const double pi = 3.14;
-</programlisting>
-          or with
-<programlisting>
-#define pi 3.14
-</programlisting>
-        </para>
-
-        <para>
-          In order to tell GHC the C type that a Haskell type
-          corresponds to when it is used with the CAPI, a
-          <literal>CTYPE</literal> pragma can be used on the type
-          definition. The header which defines the type can optionally
-          also be specified. The syntax looks like:
-
-<programlisting>
-data    {-# CTYPE "unistd.h" "useconds_t" #-} T = ...
-newtype {-# CTYPE            "useconds_t" #-} T = ...
-</programlisting>
-        </para>
-      </sect2>
-
-      <sect2>
-        <title><literal>hs_thread_done()</literal></title>
-
-<programlisting>
-void hs_thread_done(void);
-</programlisting>
-
-        <para>
-          GHC allocates a small amount of thread-local memory when a
-          thread calls a Haskell function via a <literal>foreign
-          export</literal>.  This memory is not normally freed until
-          <literal>hs_exit()</literal>; the memory is cached so that
-          subsequent calls into Haskell are fast.  However, if your
-          application is long-running and repeatedly creates new
-          threads that call into Haskell, you probably want to arrange
-          that this memory is freed in those threads that have
-          finished calling Haskell functions.  To do this, call
-          <literal>hs_thread_done()</literal> from the thread whose
-          memory you want to free.
-        </para>
-
-        <para>
-          Calling <literal>hs_thread_done()</literal> is entirely
-          optional.  You can call it as often or as little as you
-          like.  It is safe to call it from a thread that has never
-          called any Haskell functions, or one that never will.  If
-          you forget to call it, the worst that can happen is that
-          some memory remains allocated until
-          <literal>hs_exit()</literal> is called.  If you call it too
-          often, the worst that can happen is that the next call to a
-          Haskell function incurs some extra overhead.
-        </para>
-      </sect2>
-  </sect1>
-
-  <sect1 id="ffi-ghc">
-    <title>Using the FFI with GHC</title>
-
-    <para>The following sections also give some hints and tips on the
-    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>
-
-      <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
-      a <filename>M_stub.h</filename> for use by C programs.</para>
-
-      <para>For a plain <literal>foreign export</literal>, the file
-      <filename>M_stub.h</filename> contains a C prototype for the
-      foreign exported function.  For example, if we compile the
-      following module:</para>
-
-<programlisting>
-module Foo where
-
-foreign export ccall foo :: Int -> IO Int
-
-foo :: Int -> IO Int
-foo n = return (length (f n))
-
-f :: Int -> [Int]
-f 0 = []
-f n = n:(f (n-1))</programlisting>
-
-      <para>Then <filename>Foo_stub.h</filename> will contain
-      something like this:</para>
-
-<programlisting>
-#include "HsFFI.h"
-extern HsInt foo(HsInt a0);</programlisting>
-
-      <para>To invoke <literal>foo()</literal> from C, just <literal>#include
-      "Foo_stub.h"</literal> and call <literal>foo()</literal>.</para>
-
-      <para>The
-       <filename>Foo_stub.h</filename> file can be redirected using the
-       <option>-stubdir</option> option; see <xref linkend="options-output"
-         />.</para>
-
-      <sect3 id="using-own-main">
-       <title>Using your own <literal>main()</literal></title>
-
-       <para>Normally, GHC's runtime system provides a
-       <literal>main()</literal>, which arranges to invoke
-       <literal>Main.main</literal> in the Haskell program.  However,
-       you might want to link some Haskell code into a program which
-       has a main function written in another language, say C.  In
-       order to do this, you have to initialize the Haskell runtime
-       system explicitly.</para>
-
-       <para>Let's take the example from above, and invoke it from a
-       standalone C program.  Here's the C code:</para>
-
-<programlisting>
-#include &lt;stdio.h&gt;
-#include "HsFFI.h"
-
-#ifdef __GLASGOW_HASKELL__
-#include "Foo_stub.h"
-#endif
-
-int main(int argc, char *argv[])
-{
-  int i;
-
-  hs_init(&amp;argc, &amp;argv);
-
-  for (i = 0; i &lt; 5; i++) {
-    printf("%d\n", foo(2500));
-  }
-
-  hs_exit();
-  return 0;
-}</programlisting>
-
-       <para>We've surrounded the GHC-specific bits with
-       <literal>#ifdef __GLASGOW_HASKELL__</literal>; the rest of the
-       code should be portable across Haskell implementations that
-       support the FFI standard.</para>
-
-       <para>The call to <literal>hs_init()</literal>
-       initializes GHC's runtime system.  Do NOT try to invoke any
-       Haskell functions before calling
-       <literal>hs_init()</literal>: bad things will
-       undoubtedly happen.</para>
-
-       <para>We pass references to <literal>argc</literal> and
-       <literal>argv</literal> to <literal>hs_init()</literal>
-       so that it can separate out any arguments for the RTS
-       (i.e. those arguments between
-       <literal>+RTS...-RTS</literal>).</para>
-
-        <para>After we've finished invoking our Haskell functions, we
-       can call <literal>hs_exit()</literal>, which terminates the
-       RTS.</para>
-
-       <para>There can be multiple calls to
-       <literal>hs_init()</literal>, but each one should be matched
-       by one (and only one) call to
-       <literal>hs_exit()</literal><footnote><para>The outermost
-       <literal>hs_exit()</literal> will actually de-initialise the
-       system.  NOTE that currently GHC's runtime cannot reliably
-       re-initialise after this has happened,
-        see <xref linkend="infelicities-ffi" />.</para>
-       </footnote>.</para>
-
-       <para>NOTE: when linking the final program, it is normally
-       easiest to do the link using GHC, although this isn't
-       essential.  If you do use GHC, then don't forget the flag
-       <option>-no-hs-main</option><indexterm><primary><option>-no-hs-main</option></primary>
-         </indexterm>, otherwise GHC will try to link
-       to the <literal>Main</literal> Haskell module.</para>
-
-        <para>To use <literal>+RTS</literal> flags
-          with <literal>hs_init()</literal>, we have to modify the
-          example slightly.  By default, GHC's RTS will only accept
-          "safe"
-          <literal>+RTS</literal> flags (see
-          <xref linkend="options-linker" />), and
-          the <option>-rtsopts</option><indexterm><primary><option>-rtsopts</option></primary></indexterm> link-time flag overrides this.
-          However, <option>-rtsopts</option> has no effect
-          when <option>-no-hs-main</option> is in use (and the same
-          goes for <option>-with-rtsopts</option>).  To set these
-          options we have to call a GHC-specific API instead
-          of <option>hs_init()</option>:</para>
-
-<programlisting>
-#include &lt;stdio.h&gt;
-#include "HsFFI.h"
-
-#ifdef __GLASGOW_HASKELL__
-#include "Foo_stub.h"
-#include "Rts.h"
-#endif
-
-int main(int argc, char *argv[])
-{
-  int i;
-
-#if __GLASGOW_HASKELL__ >= 703
-  {
-      RtsConfig conf = defaultRtsConfig;
-      conf.rts_opts_enabled = RtsOptsAll;
-      hs_init_ghc(&amp;argc, &amp;argv, conf);
-  }
-#else
-  hs_init(&amp;argc, &amp;argv);
-#endif
-
-  for (i = 0; i &lt; 5; i++) {
-    printf("%d\n", foo(2500));
-  }
-
-  hs_exit();
-  return 0;
-}</programlisting>
-
-      <para>Note two changes: we included <literal>Rts.h</literal>,
-        which defines the GHC-specific external RTS interface, and we
-        called <literal>hs_init_ghc()</literal> instead
-        of <literal>hs_init()</literal>, passing an argument of
-        type <literal>RtsConfig</literal>.
-        <literal>RtsConfig</literal> is a struct with various fields
-        that affect the behaviour of the runtime system.  Its
-        definition is:</para>
-
-<programlisting>
-typedef struct {
-    RtsOptsEnabledEnum rts_opts_enabled;
-    const char *rts_opts;
-} RtsConfig;
-
-extern const RtsConfig defaultRtsConfig;
-
-typedef enum {
-    RtsOptsNone,         // +RTS causes an error
-    RtsOptsSafeOnly,     // safe RTS options allowed; others cause an error
-    RtsOptsAll           // all RTS options allowed
-  } RtsOptsEnabledEnum;
-</programlisting>
-
-      <para>There is a default
-        value <literal>defaultRtsConfig</literal> that should be used
-        to initialise variables of type <literal>RtsConfig</literal>.
-        More fields will undoubtedly be added
-        to <literal>RtsConfig</literal> in the future, so in order to
-        keep your code forwards-compatible it is best to initialise
-        with <literal>defaultRtsConfig</literal> and then modify the
-        required fields, as in the code sample above.</para>
-
-
-      </sect3>
-
-      <sect3 id="ffi-library">
-        <title>Making a Haskell library that can be called from foreign
-          code</title>
-
-        <para>The scenario here is much like in <xref linkend="using-own-main"
-            />, except that the aim is not to link a complete program, but to
-          make a library from Haskell code that can be deployed in the same
-          way that you would deploy a library of C code.</para>
-
-        <para>The main requirement here is that the runtime needs to be
-          initialized before any Haskell code can be called, so your library
-          should provide initialisation and deinitialisation entry points,
-          implemented in C or C++.  For example:</para>
-
-<programlisting>
-#include &lt;stdlib.h&gt;
-#include "HsFFI.h"
-
-HsBool mylib_init(void){
-  int argc = 2;
-  char *argv[] = { "+RTS", "-A32m", NULL };
-  char **pargv = argv;
-
-  // Initialize Haskell runtime
-  hs_init(&amp;argc, &amp;pargv);
-
-  // do any other initialization here and
-  // return false if there was a problem
-  return HS_BOOL_TRUE;
-}
-
-void mylib_end(void){
-  hs_exit();
-}
-</programlisting>
-
-        <para>The initialisation routine, <literal>mylib_init</literal>, calls
-          <literal>hs_init()</literal> as
-          normal to initialise the Haskell runtime, and the corresponding
-          deinitialisation function <literal>mylib_end()</literal> calls
-          <literal>hs_exit()</literal> to shut down the runtime.</para>
-      </sect3>
-
-    </sect2>
-
-    <sect2 id="glasgow-foreign-headers">
-      <title>Using header files</title>
-
-      <indexterm><primary>C calls, function headers</primary></indexterm>
-
-      <para>C functions are normally declared using prototypes in a C
-        header file.  Earlier versions of GHC (6.8.3 and
-        earlier) <literal>&num;include</literal>d the header file in
-        the C source file generated from the Haskell code, and the C
-        compiler could therefore check that the C function being
-        called via the FFI was being called at the right type.</para>
-
-      <para>GHC no longer includes external header files when
-        compiling via C, so this checking is not performed.  The
-        change was made for compatibility with the
-        <ulink linkend="native-code-gen">native code generator</ulink>
-        (<literal>-fasm</literal>) and to comply strictly with the FFI
-        specification, which requires that FFI calls are not subject
-        to macro expansion and other CPP conversions that may be
-        applied when using C header files.  This approach also
-        simplifies the inlining of foreign calls across module and
-        package boundaries: there's no need for the header file to be
-        available when compiling an inlined version of a foreign call,
-        so the compiler is free to inline foreign calls in any
-        context.</para>
-
-      <para>The <literal>-&num;include</literal> option is now
-        deprecated, and the <literal>include-files</literal> field
-        in a Cabal package specification is ignored.</para>
-
-    </sect2>
-
-    <sect2>
-      <title>Memory Allocation</title>
-
-      <para>The FFI libraries provide several ways to allocate memory
-      for use with the FFI, and it isn't always clear which way is the
-      best.  This decision may be affected by how efficient a
-      particular kind of allocation is on a given compiler/platform,
-      so this section aims to shed some light on how the different
-      kinds of allocation perform with GHC.</para>
-
-      <variablelist>
-       <varlistentry>
-         <term><literal>alloca</literal> and friends</term>
-         <listitem>
-           <para>Useful for short-term allocation when the allocation
-           is intended to scope over a given <literal>IO</literal>
-           computation.  This kind of allocation is commonly used
-           when marshalling data to and from FFI functions.</para>
-
-           <para>In GHC, <literal>alloca</literal> is implemented
-           using <literal>MutableByteArray#</literal>, so allocation
-           and deallocation are fast: much faster than C's
-           <literal>malloc/free</literal>, but not quite as fast as
-           stack allocation in C.  Use <literal>alloca</literal>
-           whenever you can.</para>
-         </listitem>
-       </varlistentry>
-
-       <varlistentry>
-         <term><literal>mallocForeignPtr</literal></term>
-         <listitem>
-           <para>Useful for longer-term allocation which requires
-           garbage collection.  If you intend to store the pointer to
-           the memory in a foreign data structure, then
-           <literal>mallocForeignPtr</literal> is
-           <emphasis>not</emphasis> a good choice, however.</para>
-
-           <para>In GHC, <literal>mallocForeignPtr</literal> is also
-           implemented using <literal>MutableByteArray#</literal>.
-           Although the memory is pointed to by a
-           <literal>ForeignPtr</literal>, there are no actual
-           finalizers involved (unless you add one with
-           <literal>addForeignPtrFinalizer</literal>), and the
-           deallocation is done using GC, so
-           <literal>mallocForeignPtr</literal> is normally very
-           cheap.</para>
-         </listitem>
-       </varlistentry>
-
-       <varlistentry>
-         <term><literal>malloc/free</literal></term>
-         <listitem>
-           <para>If all else fails, then you need to resort to
-           <literal>Foreign.malloc</literal> and
-           <literal>Foreign.free</literal>.  These are just wrappers
-           around the C functions of the same name, and their
-           efficiency will depend ultimately on the implementations
-           of these functions in your platform's C library.  We
-           usually find <literal>malloc</literal> and
-           <literal>free</literal> to be significantly slower than
-           the other forms of allocation above.</para>
-         </listitem>
-       </varlistentry>
-
-       <varlistentry>
-         <term><literal>Foreign.Marshal.Pool</literal></term>
-         <listitem>
-           <para>Pools are currently implemented using
-           <literal>malloc/free</literal>, so while they might be a
-           more convenient way to structure your memory allocation
-           than using one of the other forms of allocation, they
-           won't be any more efficient.  We do plan to provide an
-           improved-performance implementation of Pools in the
-           future, however.</para>
-         </listitem>
-       </varlistentry>
-      </variablelist>
-    </sect2>
-
-    <sect2 id="ffi-threads">
-      <title>Multi-threading and the FFI</title>
-
-      <para>In order to use the FFI in a multi-threaded setting, you must
-        use the <option>-threaded</option> option
-        (see <xref linkend="options-linker" />).</para>
-
-      <sect3>
-        <title>Foreign imports and multi-threading</title>
-
-        <para>When you call a <literal>foreign import</literal>ed
-          function that is annotated as <literal>safe</literal> (the
-          default), and the program was linked
-          using <option>-threaded</option>, then the call will run
-          concurrently with other running Haskell threads.  If the
-          program was linked without <option>-threaded</option>,
-          then the other Haskell threads will be blocked until the
-          call returns.</para>
-
-        <para>This means that if you need to make a foreign call to
-          a function that takes a long time or blocks indefinitely,
-          then you should mark it <literal>safe</literal> and
-          use <option>-threaded</option>.  Some library functions
-          make such calls internally; their documentation should
-          indicate when this is the case.</para>
-
-        <para>If you are making foreign calls from multiple Haskell
-          threads and using <option>-threaded</option>, make sure that
-          the foreign code you are calling is thread-safe.  In
-          particularly, some GUI libraries are not thread-safe and
-          require that the caller only invokes GUI methods from a
-          single thread.  If this is the case, you may need to
-          restrict your GUI operations to a single Haskell thread,
-          and possibly also use a bound thread (see
-          <xref linkend="haskell-threads-and-os-threads" />).</para>
-
-        <para>Note that foreign calls made by different Haskell
-          threads may execute in <emphasis>parallel</emphasis>, even
-          when the <literal>+RTS -N</literal> flag is not being used
-          (<xref linkend="parallel-options" />).  The <literal>+RTS
-          -N</literal> flag controls parallel execution of Haskell
-          threads, but there may be an arbitrary number of foreign
-          calls in progress at any one time, regardless of
-          the <literal>+RTS -N</literal> value.</para>
-
-        <para>If a call is annotated as <literal>interruptible</literal>
-          and the program was multithreaded, the call may be
-          interrupted in the event that the Haskell thread receives an
-          exception.  The mechanism by which the interrupt occurs
-          is platform dependent, but is intended to cause blocking
-          system calls to return immediately with an interrupted error
-          code.  The underlying operating system thread is not to be
-          destroyed.  See <xref linkend="ffi-interruptible"/> for more details.</para>
-      </sect3>
-
-      <sect3 id="haskell-threads-and-os-threads">
-        <title>The relationship between Haskell threads and OS
-          threads</title>
-
-        <para>Normally there is no fixed relationship between Haskell
-          threads and OS threads.  This means that when you make a
-          foreign call, that call may take place in an unspecified OS
-          thread.  Furthermore, there is no guarantee that multiple
-          calls made by one Haskell thread will be made by the same OS
-          thread.</para>
-
-        <para>This usually isn't a problem, and it allows the GHC
-          runtime system to make efficient use of OS thread resources.
-          However, there are cases where it is useful to have more
-          control over which OS thread is used, for example when
-          calling foreign code that makes use of thread-local state.
-          For cases like this, we provide <emphasis>bound
-          threads</emphasis>, which are Haskell threads tied to a
-          particular OS thread.  For information on bound threads, see
-          the documentation
-          for the <ulink url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>
-          module.</para>
-      </sect3>
-
-      <sect3>
-        <title>Foreign exports and multi-threading</title>
-
-        <para>When the program is linked
-          with <option>-threaded</option>, then you may
-          invoke <literal>foreign export</literal>ed functions from
-          multiple OS threads concurrently.  The runtime system must
-          be initialised as usual by
-          calling <literal>hs_init()</literal>, and this call must
-          complete before invoking any <literal>foreign
-          export</literal>ed functions.</para>
-      </sect3>
-
-      <sect3 id="hs-exit">
-        <title>On the use of <literal>hs_exit()</literal></title>
-
-        <para><literal>hs_exit()</literal> normally causes the termination of
-          any running Haskell threads in the system, and when
-          <literal>hs_exit()</literal> returns, there will be no more Haskell
-          threads running.  The runtime will then shut down the system in an
-          orderly way, generating profiling
-          output and statistics if necessary, and freeing all the memory it
-          owns.</para>
-
-        <para>It isn't always possible to terminate a Haskell thread forcibly:
-          for example, the thread might be currently executing a foreign call,
-          and we have no way to force the foreign call to complete.  What's
-          more, the runtime must
-          assume that in the worst case the Haskell code and runtime are about
-          to be removed from memory (e.g. if this is a <link linkend="win32-dlls">Windows DLL</link>,
-          <literal>hs_exit()</literal> is normally called before unloading the
-          DLL).  So <literal>hs_exit()</literal> <emphasis>must</emphasis> wait
-          until all outstanding foreign calls return before it can return
-          itself.</para>
-
-        <para>The upshot of this is that if you have Haskell threads that are
-          blocked in foreign calls, then <literal>hs_exit()</literal> may hang
-          (or possibly busy-wait) until the calls return.  Therefore it's a
-          good idea to make sure you don't have any such threads in the system
-          when calling <literal>hs_exit()</literal>.  This includes any threads
-          doing I/O, because I/O may (or may not, depending on the
-          type of I/O and the platform) be implemented using blocking foreign
-          calls.</para>
-
-        <para>The GHC runtime treats program exit as a special case, to avoid
-          the need to wait for blocked threads when a standalone
-          executable exits.  Since the program and all its threads are about to
-          terminate at the same time that the code is removed from memory, it
-          isn't necessary to ensure that the threads have exited first.
-          (Unofficially, if you want to use this fast and loose version of
-          <literal>hs_exit()</literal>, then call
-          <literal>shutdownHaskellAndExit()</literal> instead).</para>
-      </sect3>
-    </sect2>
-
-    <sect2 id="ffi-floating-point">
-      <title>Floating point and the FFI</title>
-
-      <para>
-        The standard C99 <literal>fenv.h</literal> header
-        provides operations for inspecting and modifying the state of
-        the floating point unit.  In particular, the rounding mode
-        used by floating point operations can be changed, and the
-        exception flags can be tested.
-      </para>
-
-      <para>
-        In Haskell, floating-point operations have pure types, and the
-        evaluation order is unspecified.  So strictly speaking, since
-        the <literal>fenv.h</literal> functions let you change the
-        results of, or observe the effects of floating point
-        operations, use of <literal>fenv.h</literal> renders the
-        behaviour of floating-point operations anywhere in the program
-        undefined.
-      </para>
-
-      <para>
-        Having said that, we <emphasis>can</emphasis> document exactly
-        what GHC does with respect to the floating point state, so
-        that if you really need to use <literal>fenv.h</literal> then
-        you can do so with full knowledge of the pitfalls:
-        <itemizedlist>
-          <listitem>
-            <para>
-              GHC completely ignores the floating-point
-              environment, the runtime neither modifies nor reads it.
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              The floating-point environment is not saved over a
-              normal thread context-switch.  So if you modify the
-              floating-point state in one thread, those changes may be
-              visible in other threads.  Furthermore, testing the
-              exception state is not reliable, because a context
-              switch may change it.  If you need to modify or test the
-              floating point state and use threads, then you must use
-              bound threads
-              (<literal>Control.Concurrent.forkOS</literal>), because
-              a bound thread has its own OS thread, and OS threads do
-              save and restore the floating-point state.
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              It is safe to modify the floating-point unit state
-              temporarily during a foreign call, because foreign calls
-              are never pre-empted by GHC.
-            </para>
-          </listitem>
-        </itemizedlist>
-      </para>
-    </sect2>
-  </sect1>
-</chapter>
-
-<!-- Emacs stuff:
-     ;;; Local Variables: ***
-     ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
-     ;;; End: ***
- -->
diff --git a/docs/users_guide/flags.rst b/docs/users_guide/flags.rst
new file mode 100644 (file)
index 0000000..4064f46
--- /dev/null
@@ -0,0 +1,212 @@
+.. _flag-reference:
+
+Flag reference
+==============
+
+This section is a quick-reference for GHC's command-line flags. For each
+flag, we also list its static/dynamic status (see
+:ref:`static-dynamic-flags`), and the flag's opposite (if available).
+
+Verbosity options
+-----------------
+
+More details in :ref:`options-help`
+
+.. include:: flags-verbosity.gen.rst
+
+Alternative modes of operation
+------------------------------
+
+More details in :ref:`modes`
+
+.. include:: flags-modes.gen.rst
+
+Which phases to run
+-------------------
+
+More details in :ref:`options-order`
+
+.. include:: flags-phases.gen.rst
+
+Redirecting output
+------------------
+
+More details in :ref:`options-output`
+
+.. include:: flags-redirecting-output.gen.rst
+
+Keeping intermediate files
+--------------------------
+
+More details in :ref:`keeping-intermediates`
+
+.. include:: flags-keeping-intermediates.gen.rst
+
+Temporary files
+---------------
+
+More details in :ref:`temp-files`
+
+.. include:: flags-temporary-files.gen.rst
+
+Finding imports
+---------------
+
+More details in :ref:`search-path`
+
+.. include:: flags-finding-imports.gen.rst
+
+Interface file options
+----------------------
+
+More details in :ref:`hi-options`
+
+.. include:: flags-interface-files.gen.rst
+
+Recompilation checking
+----------------------
+
+More details in :ref:`recomp`
+
+.. include:: flags-recompilation-checking.gen.rst
+
+.. _interactive-mode-options:
+
+Interactive-mode options
+------------------------
+
+More details in :ref:`ghci-dot-files`
+
+.. include:: flags-interactive.gen.rst
+
+Packages
+--------
+
+More details in :ref:`packages`
+
+.. include:: flags-packages.gen.rst
+
+Language options
+----------------
+
+Language options can be enabled either by a command-line option
+``-Xblah``, or by a ``{-# LANGUAGE blah #-}`` pragma in the file itself.
+See :ref:`options-language`. Some options are enabled using ``-f*``
+flags.
+
+.. include:: flags-language.gen.rst
+
+Warnings
+--------
+
+More details in :ref:`options-sanity`
+
+.. include:: flags-warnings.gen.rst
+
+Optimisation levels
+-------------------
+
+These options are described in more detail in :ref:`options-optimise`.
+
+See :ref:`options-f-compact` for a list of optimisations enabled on
+level 1 and level 2.
+
+.. include:: flags-optimization-levels.gen.rst
+
+.. _options-f-compact:
+
+Individual optimisations
+------------------------
+
+These options are described in more detail in :ref:`options-f`. If a
+flag is implied by ``-O`` then it is also implied by ``-O2`` (unless
+flag description explicitly says otherwise). If a flag is implied by
+``-O0`` only then the flag is not implied by ``-O`` and ``-O2``.
+
+.. include:: flags-optimization.gen.rst
+
+Profiling options
+-----------------
+
+More details in :ref:`profiling`
+
+.. include:: flags-profiling.gen.rst
+
+Program coverage options
+------------------------
+
+More details in :ref:`hpc`
+
+.. include:: flags-program-coverage.gen.rst
+
+C pre-processor options
+-----------------------
+
+More details in :ref:`c-pre-processor`
+
+.. include:: flags-cpp.gen.rst
+
+Code generation options
+-----------------------
+
+More details in :ref:`options-codegen`
+
+.. include:: flags-codegen.gen.rst
+
+Linking options
+---------------
+
+More details in :ref:`options-linker`
+
+.. include:: flags-linking.gen.rst
+
+Plugin options
+--------------
+
+More details in :ref:`compiler-plugins`
+
+.. include:: flags-plugin.gen.rst
+
+Replacing phases
+----------------
+
+More details in :ref:`replacing-phases`
+
+.. include:: flags-phase-programs.gen.rst
+
+.. index::
+   single: -pgmL
+   single: -pgmP
+   single: -pgmc
+   single: -pgmlo
+   single: -pgmlc
+   single: -pgma
+   single: -pgml
+   single: -pgmdll
+   single: -pgmF
+
+Forcing options to particular phases
+------------------------------------
+
+More details in :ref:`forcing-options-through`
+
+.. include:: flags-phase-specific.gen.rst
+
+Platform-specific options
+-------------------------
+
+More details in :ref:`options-platform`
+
+.. include:: flags-platform-specific.gen.rst
+
+Compiler debugging options
+--------------------------
+
+More details in :ref:`options-debugging`
+
+.. include:: flags-compiler-debugging.gen.rst
+
+Miscellaneous compiler options
+------------------------------
+
+.. include:: flags-misc.gen.rst
diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
deleted file mode 100644 (file)
index 7bf8246..0000000
+++ /dev/null
@@ -1,3564 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<sect1 id="flag-reference">
-  <title>Flag reference</title>
-
-  <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
-    (if available).</para>
-
-  <sect2>
-    <title>Verbosity options</title>
-
-    <para>More details in <xref linkend="options-help"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-v</option></entry>
-            <entry>verbose mode (equivalent to <option>-v3</option>)</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-v</option><replaceable>n</replaceable></entry>
-            <entry>set verbosity level</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-fprint-potential-instances</option></entry>
-            <entry>display all available instances in type error messages</entry>
-            <entry>dynamic</entry>
-            <entry>-fno-print-potential-instances</entry>
-          </row>
-          <row>
-            <entry><option>-fprint-explicit-foralls</option></entry>
-            <entry>Print explicit <literal>forall</literal> quantification in types. See also <option>-XExplicitForAll</option></entry>
-            <entry>dynamic</entry>
-            <entry>-fno-print-explicit-foralls</entry>
-          </row>
-          <row>
-            <entry><option>-fprint-explicit-kinds</option></entry>
-            <entry>Print explicit kind foralls and kind arguments in types. See also <option>-XKindSignature</option></entry>
-            <entry>dynamic</entry>
-            <entry>-fno-print-explicit-kinds</entry>
-          </row>
-          <row>
-            <entry><option>-fprint-unicode-syntax</option></entry>
-            <entry>Use unicode syntax when printing expressions, types and kinds. See also <option>-XUnicodeSyntax</option></entry>
-            <entry>dynamic</entry>
-            <entry>-fno-print-unicode-syntax</entry>
-          </row>
-          <row>
-            <entry><option>-fprint-expanded-synonyms</option></entry>
-            <entry>In type errors, also print type-synonym-expanded types.</entry>
-            <entry>dynamic</entry>
-            <entry>-fno-print-expanded-synonyms</entry>
-          </row>
-          <row>
-            <entry><option>-ferror-spans</option></entry>
-            <entry>output full span in error messages</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-H</option><replaceable>size</replaceable></entry>
-            <entry>Set the minimum heap size to <replaceable>size</replaceable></entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-Rghc-timing</option></entry>
-            <entry>Summarise timing stats for GHC (same as <literal>+RTS -tstderr</literal>)</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-
-  </sect2>
-  <sect2>
-    <title>Alternative modes of operation</title>
-
-    <para>More details in <xref linkend="modes"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>--help</option>,<option>-?</option></entry>
-            <entry>Display help</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-
-          <row>
-            <entry><option>--interactive</option></entry>
-            <entry>Interactive mode - normally used by just running <command>ghci</command>;
-              see <xref linkend="ghci"/> for details.</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--make</option></entry>
-            <entry>Build a multi-module Haskell program, automatically figuring out dependencies. Likely to be much easier, and faster, than using <command>make</command>;
-              see <xref linkend="make-mode"/> for details..</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-e <replaceable>expr</replaceable></option></entry>
-            <entry>Evaluate <replaceable>expr</replaceable>;
-              see <xref linkend="eval-mode"/> for details.</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-
-          <row>
-            <entry><option>--show-iface</option></entry>
-            <entry>Display the contents of an interface file.</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-
-          <row>
-            <entry><option>-M</option></entry>
-            <entry>Generate dependency information suitable for use in a <filename>Makefile</filename>;
-              see <xref linkend="makefile-dependencies"/> for details.</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-
-
-          <row>
-            <entry><option>--supported-extensions</option>, <option>--supported-languages</option></entry>
-            <entry>display the supported language extensions</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--show-options</option></entry>
-            <entry>display the supported command line options</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--info</option></entry>
-            <entry>display information about the compiler</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--version, -V</option></entry>
-            <entry>display GHC version</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--numeric-version</option></entry>
-            <entry>display GHC version (numeric only)</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--print-libdir</option></entry>
-            <entry>display GHC library directory</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Which phases to run</title>
-
-    <para><xref linkend="options-order"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-E</option></entry>
-            <entry>Stop after preprocessing (<literal>.hspp</literal> file)</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-C</option></entry>
-            <entry>Stop after generating C (<literal>.hc</literal> file)</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-S</option></entry>
-            <entry>Stop after generating assembly (<literal>.s</literal> file)</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-c</option></entry>
-            <entry>Stop after generating object (<literal>.o</literal>) file</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-x</option> <replaceable>suffix</replaceable></entry>
-            <entry>Override default behaviour for source files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Redirecting output</title>
-
-    <para><xref linkend="options-output"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-hcsuf</option> <replaceable>suffix</replaceable></entry>
-            <entry>set the suffix to use for intermediate C files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-hidir</option> <replaceable>dir</replaceable></entry>
-            <entry>set directory for interface files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-hisuf</option> <replaceable>suffix</replaceable></entry>
-            <entry>set the suffix to use for interface files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-o</option> <replaceable>filename</replaceable></entry>
-            <entry>set output filename</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-odir</option> <replaceable>dir</replaceable></entry>
-            <entry>set directory for object files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-ohi</option> <replaceable>filename</replaceable></entry>
-            <entry>set the filename in which to put the interface</entry>
-            <entry>dynamic</entry>
-            <entry></entry>
-          </row>
-          <row>
-            <entry><option>-osuf</option> <replaceable>suffix</replaceable></entry>
-            <entry>set the output file suffix</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-stubdir</option> <replaceable>dir</replaceable></entry>
-            <entry>redirect FFI stub files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-dumpdir</option> <replaceable>dir</replaceable></entry>
-            <entry>redirect dump files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-outputdir</option> <replaceable>dir</replaceable></entry>
-            <entry>set output directory</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Keeping intermediate files</title>
-
-    <para><xref linkend="keeping-intermediates"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-keep-hc-file</option> or
-              <option>-keep-hc-files</option></entry>
-            <entry>retain intermediate <literal>.hc</literal> files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-keep-llvm-file</option> or
-              <option>-keep-llvm-files</option></entry>
-            <entry>retain intermediate LLVM <literal>.ll</literal> files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-keep-s-file</option> or
-              <option>-keep-s-files</option></entry>
-            <entry>retain intermediate <literal>.s</literal> files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-keep-tmp-files</option></entry>
-            <entry>retain all intermediate temporary files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Temporary files</title>
-
-    <para><xref linkend="temp-files"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-tmpdir</option></entry>
-            <entry>set the directory for temporary files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Finding imports</title>
-
-    <para><xref linkend="search-path"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-i</option><replaceable>dir1</replaceable>:<replaceable>dir2</replaceable>:...</entry>
-            <entry>add <replaceable>dir</replaceable>,
-              <replaceable>dir2</replaceable>, etc. to import path</entry>
-            <entry>dynamic/<literal>:set</literal></entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-i</option></entry>
-            <entry>Empty the import directory list</entry>
-            <entry>dynamic/<literal>:set</literal></entry>
-            <entry>-</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Interface file options</title>
-
-    <para><xref linkend="hi-options"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-ddump-hi</option></entry>
-            <entry>Dump the new interface to stdout</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-ddump-hi-diffs</option></entry>
-            <entry>Show the differences vs. the old interface</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-ddump-minimal-imports</option></entry>
-            <entry>Dump a minimal set of imports</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--show-iface</option> <replaceable>file</replaceable></entry>
-            <entry>See <xref linkend="modes"/>.</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Recompilation checking</title>
-
-    <para><xref linkend="recomp"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-fforce-recomp</option></entry>
-            <entry>Turn off recompilation checking. This is implied by any
-              <option>-ddump-X</option> option when compiling a single
-              file (i.e. when using <literal>-c</literal>).</entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-force-recomp</option></entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2 id="interactive-mode-options">
-    <title>Interactive-mode options</title>
-
-    <para><xref linkend="ghci-dot-files"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-ignore-dot-ghci</option></entry>
-            <entry>Disable reading of <filename>.ghci</filename> files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-ghci-script</option></entry>
-            <entry>Read additional <filename>.ghci</filename> files</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-fbreak-on-error</option></entry>
-            <entry><link linkend="ghci-debugger-exceptions">Break on uncaught exceptions and errors</link></entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-break-on-error</option></entry>
-          </row>
-          <row>
-            <entry><option>-fbreak-on-exception</option></entry>
-            <entry><link linkend="ghci-debugger-exceptions">Break on any exception thrown</link></entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-break-on-exception</option></entry>
-          </row>
-          <row>
-            <entry><option>-fghci-hist-size=<replaceable>n</replaceable></option></entry>
-            <entry><link linkend="ghci-debugger">Set the number of entries GHCi keeps for <literal>:history</literal></link></entry>
-            <entry>dynamic</entry>
-            <entry><option>(default is 50)</option></entry>
-          </row>
-          <row>
-            <entry><option>-fprint-evld-with-show</option></entry>
-            <entry><link linkend="breakpoints">Enable usage of Show instances in <literal>:print</literal></link></entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-print-evld-with-show</option></entry>
-          </row>
-          <row>
-            <entry><option>-fprint-bind-result</option></entry>
-            <entry><link linkend="ghci-stmts">Turn on printing of binding results in GHCi</link></entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-print-bind-result</option></entry>
-          </row>
-          <row>
-            <entry><option>-fno-print-bind-contents</option></entry>
-            <entry><link linkend="breakpoints">Turn off printing of binding contents in GHCi</link></entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-fno-implicit-import-qualified</option></entry>
-            <entry><link linkend="ghci-import-qualified">Turn off
-                implicit qualified import of everything in GHCi</link></entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-interactive-print</option></entry>
-            <entry><link linkend="ghci-interactive-print">Select the function
-                    to use for printing evaluated expressions in GHCi</link></entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Packages</title>
-
-    <para><xref linkend="packages"/></para>
-
-    <informaltable>
-      <tgroup cols="4" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-this-package-key</option> <replaceable>P</replaceable></entry>
-            <entry>Compile to be part of package <replaceable>P</replaceable></entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-package</option> <replaceable>P</replaceable></entry>
-            <entry>Expose package <replaceable>P</replaceable></entry>
-            <entry>dynamic/<literal>:set</literal></entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-hide-all-packages</option></entry>
-            <entry>Hide all packages by default</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-hide-package</option> <replaceable>name</replaceable></entry>
-            <entry>Hide package <replaceable>P</replaceable></entry>
-            <entry>dynamic/<literal>:set</literal></entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-ignore-package</option> <replaceable>name</replaceable></entry>
-            <entry>Ignore package <replaceable>P</replaceable></entry>
-            <entry>dynamic/<literal>:set</literal></entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-package-db</option> <replaceable>file</replaceable></entry>
-            <entry>Add <replaceable>file</replaceable> to the package db stack.</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-clear-package-db</option></entry>
-            <entry>Clear the package db stack.</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-no-global-package-db</option></entry>
-            <entry>Remove the global package db from the stack.</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-global-package-db</option></entry>
-            <entry>Add the global package db to the stack.</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-no-user-package-db</option></entry>
-            <entry>Remove the user's package db from the stack.</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-user-package-db</option></entry>
-            <entry>Add the user's package db to the stack.</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-no-auto-link-packages</option></entry>
-            <entry>Don't automatically link in the base and rts packages.</entry>
-            <entry>dynamic</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-trust</option> <replaceable>P</replaceable></entry>
-            <entry>Expose package <replaceable>P</replaceable> and set it to be
-              trusted</entry>
-            <entry>dynamic/<literal>:set</literal></entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-distrust</option> <replaceable>P</replaceable></entry>
-            <entry>Expose package <replaceable>P</replaceable> and set it to be
-              distrusted</entry>
-            <entry>dynamic/<literal>:set</literal></entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>-distrust-all</option> </entry>
-            <entry>Distrust all packages by default</entry>
-            <entry>dynamic/<literal>:set</literal></entry>
-            <entry>-</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </informaltable>
-  </sect2>
-
-  <sect2>
-    <title>Language options</title>
-
-    <para>Language options can be enabled either by a command-line option
-      <option>-Xblah</option>, or by a <literal>{-# LANGUAGE blah #-}</literal>
-      pragma in the file itself.  See <xref linkend="options-language"/>. Some
-      options are enabled using <option>-f*</option> flags.</para>
-
-    <informaltable>
-      <tgroup cols="5" align="left" colsep="1" rowsep="1">
-        <thead>
-          <row>
-            <entry>Flag</entry>
-            <entry>Description</entry>
-            <entry>Static/Dynamic</entry>
-            <entry>Reverse</entry>
-            <entry>Since</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry><option>-fconstraint-solver-iterations=</option><replaceable>n</replaceable></entry>
-            <entry>Set the iteration limit for the type-constraint solver.
-                   The default limit is 4. Typically one iteration
-                   suffices; so please yell if you find you need to set
-                   it higher than the default. Zero means infinity. </entry>
-           <entry>dynamic</entry>
-           <entry></entry>
-         </row>
-          <row>
-            <entry><option>-freduction-depth=</option><replaceable>n</replaceable></entry>
-           <entry>Set the <link linkend="undecidable-instances">limit for type simplification</link>.
-                   Default is 200; zero means infinity.</entry>
-           <entry>dynamic</entry>
-           <entry></entry>
-         </row>
-         <row>
-            <entry><option>-fcontext-stack=</option><replaceable>n</replaceable></entry>
-            <entry>Deprecated. Use <option>-freduction-depth=</option><replaceable>n</replaceable> instead.</entry>
-            <entry>dynamic</entry>
-            <entry></entry>
-            <entry></entry>
-          </row>
-          <row>
-            <entry><option>-fglasgow-exts</option></entry>
-            <entry>Deprecated. Enable most language extensions; see <xref linkend="options-language"/> for exactly which ones.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-glasgow-exts</option></entry>
-            <entry></entry>
-          </row>
-          <row>
-            <entry><option>-firrefutable-tuples</option></entry>
-            <entry>Make tuple pattern matching irrefutable</entry>
-            <entry>dynamic</entry>
-            <entry><option>-fno-irrefutable-tuples</option></entry>
-            <entry></entry>
-          </row>
-          <row>
-            <entry><option>-fpackage-trust</option></entry>
-            <entry>Enable <link linkend="safe-haskell">Safe Haskell</link> trusted package requirement for trustworthy modules.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-</option></entry>
-            <entry></entry>
-          </row>
-          <row>
-            <entry><option>-ftype-function-depth=</option><replaceable>n</replaceable></entry>
-            <entry>Deprecated. Use <option>-freduction-depth=</option><replaceable>n</replaceable> instead.</entry>
-            <entry>dynamic</entry>
-            <entry></entry>
-            <entry></entry>
-          </row>
-          <row>
-            <entry><option>-XAllowAmbiguousTypes</option></entry>
-            <entry>Allow the user to write <link linkend="ambiguity">ambiguous types</link>,
-                   and the type inference engine to infer them.
-                </entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoAllowAmbiguousTypes</option></entry>
-            <entry>7.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XArrows</option></entry>
-            <entry>Enable <link linkend="arrow-notation">arrow
-                notation</link> extension</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoArrows</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XApplicativeDo</option></entry>
-            <entry>Enable <link linkend="applicative-do">Applicative
-            do-notation desugaring</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoApplicativeDo</option></entry>
-            <entry>7.12.1</entry>
-          </row>
-          <row>
-            <entry><option>-XAutoDeriveTypeable</option></entry>
-            <entry>As of GHC 7.10, this option is not needed, and should
-                   not be used.  Automatically <link linkend="deriving-typeable">derive Typeable instances for every datatype and type class declaration</link>.
-            Implies <option>-XDeriveDataTypeable</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoAutoDeriveTypeable</option></entry>
-            <entry>7.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XBangPatterns</option></entry>
-            <entry>Enable <link linkend="bang-patterns">bang patterns</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoBangPatterns</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XBinaryLiterals</option></entry>
-            <entry>Enable support for <link linkend="binary-literals">binary literals</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoBinaryLiterals</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XCApiFFI</option></entry>
-            <entry>Enable <link linkend="ffi-capi">the CAPI calling convention</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoCAPIFFI</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XConstrainedClassMethods</option></entry>
-            <entry>Enable <link linkend="class-method-types">constrained class methods</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoConstrainedClassMethods</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XConstraintKinds</option></entry>
-            <entry>Enable a <link linkend="constraint-kind">kind of constraints</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoConstraintKinds</option></entry>
-            <entry>7.4.1</entry>
-          </row>
-          <row>
-            <entry><option>-XCPP</option></entry>
-            <entry>Enable the <link linkend="c-pre-processor">C preprocessor</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoCPP</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDataKinds</option></entry>
-            <entry>Enable <link linkend="promotion">datatype promotion</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDataKinds</option></entry>
-            <entry>7.4.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDefaultSignatures</option></entry>
-            <entry>Enable <link linkend="class-default-signatures">default signatures</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDefaultSignatures</option></entry>
-            <entry>7.2.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDeriveAnyClass</option></entry>
-            <entry>Enable <link linkend="derive-any-class">deriving for any
-                   class</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDeriveAnyClass</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDeriveDataTypeable</option></entry>
-            <entry>Enable <link linkend="deriving-typeable">deriving for the Data class</link>.
-              Implied by <option>-XAutoDeriveTypeable</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDeriveDataTypeable</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDeriveFunctor</option></entry>
-            <entry>Enable <link linkend="deriving-extra">deriving for the Functor class</link>.
-              Implied by <option>-XDeriveTraversable</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDeriveFunctor</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDeriveFoldable</option></entry>
-            <entry>Enable <link linkend="deriving-extra">deriving for the Foldable class</link>.
-              Implied by <option>-XDeriveTraversable</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDeriveFoldable</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDeriveGeneric</option></entry>
-            <entry>Enable <link linkend="deriving-typeable">deriving for the Generic class</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDeriveGeneric</option></entry>
-            <entry>7.2.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDeriveLift</option></entry>
-            <entry>Enable <link linkend="deriving-lift">deriving for the Lift class</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDeriveLift</option></entry>
-          </row>
-          <row>
-            <entry><option>-XDeriveTraversable</option></entry>
-            <entry>Enable <link linkend="deriving-extra">deriving for the Traversable class</link>.
-              Implies <option>-XDeriveFunctor</option> and <option>-XDeriveFoldable</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDeriveTraversable</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XDisambiguateRecordFields</option></entry>
-            <entry>Enable <link linkend="disambiguate-fields">record field disambiguation</link>.
-              Implied by <option>-XRecordWildCards</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoDisambiguateRecordFields</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XEmptyCase</option></entry>
-            <entry>Allow <link linkend="empty-case">empty case alternatives</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoEmptyCase</option></entry>
-            <entry>7.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XEmptyDataDecls</option></entry>
-            <entry>Enable empty data declarations.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoEmptyDataDecls</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XExistentialQuantification</option></entry>
-            <entry>Enable <link linkend="existential-quantification">existential quantification</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoExistentialQuantification</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XExplicitForAll</option></entry>
-            <entry>Enable <link linkend="explicit-foralls">explicit universal quantification</link>.
-              Implied by <option>-XScopedTypeVariables</option>,
-              <option>-XLiberalTypeSynonyms</option>,
-              <option>-XRankNTypes</option> and
-              <option>-XExistentialQuantification</option>.
-            </entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoExplicitForAll</option></entry>
-            <entry>6.12.1</entry>
-          </row>
-          <row>
-            <entry><option>-XExplicitNamespaces</option></entry>
-            <entry>Enable using the keyword <literal>type</literal> to specify the namespace of
-                   entries in imports and exports (<xref linkend="explicit-namespaces"/>).
-                   Implied by <option>-XTypeOperators</option> and <option>-XTypeFamilies</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoExplicitNamespaces</option></entry>
-            <entry>7.6.1</entry>
-          </row>
-          <row>
-            <entry><option>-XExtendedDefaultRules</option></entry>
-            <entry>Use GHCi's <link linkend="extended-default-rules">extended default rules</link> in a normal module.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoExtendedDefaultRules</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XFlexibleContexts</option></entry>
-            <entry>Enable <link linkend="flexible-contexts">flexible contexts</link>.
-              Implied by <option>-XImplicitParams</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoFlexibleContexts</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XFlexibleInstances</option></entry>
-            <entry>Enable <link linkend="instance-rules">flexible instances</link>.
-              Implies <option>-XTypeSynonymInstances</option>. Implied by <option>-XImplicitParams</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoFlexibleInstances</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XForeignFunctionInterface</option></entry>
-            <entry>Enable <link linkend="ffi">foreign function interface</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoForeignFunctionInterface</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XFunctionalDependencies</option></entry>
-            <entry>Enable <link linkend="functional-dependencies">functional dependencies</link>.
-              Implies <option>-XMultiParamTypeClasses</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoFunctionalDependencies</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XGADTs</option></entry>
-            <entry>Enable <link linkend="gadt">generalised algebraic data types</link>.
-              Implies <option>-XGADTSyntax</option> and <option>-XMonoLocalBinds</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoGADTs</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XGADTSyntax</option></entry>
-            <entry>Enable <link linkend="gadt-style">generalised algebraic data type syntax</link>.
-            </entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoGADTSyntax</option></entry>
-            <entry>7.2.1</entry>
-          </row>
-          <row>
-            <entry><option>-XGeneralizedNewtypeDeriving</option></entry>
-            <entry>Enable <link linkend="newtype-deriving">newtype deriving</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoGeneralizedNewtypeDeriving</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XGenerics</option></entry>
-            <entry>Deprecated, does nothing. No longer enables <link linkend="generic-classes">generic classes</link>.
-              See also GHC's support for
-              <link linkend="generic-programming">generic programming</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoGenerics</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XImplicitParams</option></entry>
-            <entry>Enable <link linkend="implicit-parameters">Implicit Parameters</link>.
-              Implies <option>-XFlexibleContexts</option> and <option>-XFlexibleInstances</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoImplicitParams</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XNoImplicitPrelude</option></entry>
-            <entry>Don't implicitly <literal>import Prelude</literal>.
-              Implied by <option>-XRebindableSyntax</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XImplicitPrelude</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XImpredicativeTypes</option></entry>
-            <entry>Enable <link linkend="impredicative-polymorphism">impredicative types</link>.
-              Implies <option>-XRankNTypes</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoImpredicativeTypes</option></entry>
-            <entry>6.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XIncoherentInstances</option></entry>
-            <entry>Enable <link linkend="instance-overlap">incoherent instances</link>.
-              Implies <option>-XOverlappingInstances</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoIncoherentInstances</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XInstanceSigs</option></entry>
-            <entry>Enable <link linkend="instance-sigs">instance signatures</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoInstanceSigs</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XInterruptibleFFI</option></entry>
-            <entry>Enable interruptible FFI.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoInterruptibleFFI</option></entry>
-            <entry>7.2.1</entry>
-          </row>
-          <row>
-            <entry><option>-XKindSignatures</option></entry>
-            <entry>Enable <link linkend="kinding">kind signatures</link>.
-              Implied by <option>-XTypeFamilies</option> and <option>-XPolyKinds</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoKindSignatures</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XLambdaCase</option></entry>
-            <entry>Enable <link linkend="lambda-case">lambda-case expressions</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoLambdaCase</option></entry>
-            <entry>7.6.1</entry>
-          </row>
-          <row>
-            <entry><option>-XLiberalTypeSynonyms</option></entry>
-            <entry>Enable <link linkend="type-synonyms">liberalised type synonyms</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoLiberalTypeSynonyms</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XMagicHash</option></entry>
-            <entry>Allow "#" as a <link linkend="magic-hash">postfix modifier on identifiers</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoMagicHash</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XMonadComprehensions</option></entry>
-            <entry>Enable <link linkend="monad-comprehensions">monad comprehensions</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoMonadComprehensions</option></entry>
-            <entry>7.2.1</entry>
-          </row>
-          <row>
-            <entry><option>-XMonoLocalBinds</option></entry>
-            <entry>Enable <link linkend="mono-local-binds">do not generalise local bindings</link>.
-              Implied by <option>-XTypeFamilies</option> and <option>-XGADTs</option>.
-            </entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoMonoLocalBinds</option></entry>
-            <entry>6.12.1</entry>
-          </row>
-          <row>
-            <entry><option>-XNoMonomorphismRestriction</option></entry>
-            <entry>Disable the <link linkend="monomorphism">monomorphism restriction</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XMonomorphismRestriction</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XMultiParamTypeClasses</option></entry>
-            <entry>Enable <link linkend="multi-param-type-classes">multi parameter type classes</link>.
-              Implied by <option>-XFunctionalDependencies</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoMultiParamTypeClasses</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XMultiWayIf</option></entry>
-            <entry>Enable <link linkend="multi-way-if">multi-way if-expressions</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoMultiWayIf</option></entry>
-            <entry>7.6.1</entry>
-          </row>
-          <row>
-            <entry><option>-XNamedFieldPuns</option></entry>
-            <entry>Enable <link linkend="record-puns">record puns</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoNamedFieldPuns</option></entry>
-            <entry>6.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XNamedWildCards</option></entry>
-            <entry>Enable <link linkend="named-wildcards">named wildcards</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoNamedWildCards</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XNegativeLiterals</option></entry>
-            <entry>Enable support for <link linkend="negative-literals">negative literals</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoNegativeLiterals</option></entry>
-            <entry>7.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XNoNPlusKPatterns</option></entry>
-            <entry>Disable support for <literal>n+k</literal> patterns.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNPlusKPatterns</option></entry>
-            <entry>6.12.1</entry>
-          </row>
-          <row>
-            <entry><option>-XNullaryTypeClasses</option></entry>
-            <entry>Deprecated, does nothing. <link linkend="nullary-type-classes">nullary (no parameter) type classes</link> are now enabled using <option>-XMultiParamTypeClasses</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoNullaryTypeClasses</option></entry>
-            <entry>7.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XNumDecimals</option></entry>
-            <entry>Enable support for 'fractional' integer literals.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoNumDecimals</option></entry>
-            <entry>7.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XOverlappingInstances</option></entry>
-            <entry>Enable <link linkend="instance-overlap">overlapping instances</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoOverlappingInstances</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XOverloadedLists</option></entry>
-            <entry>Enable <link linkend="overloaded-lists">overloaded lists</link>.
-            </entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoOverloadedLists</option></entry>
-            <entry>7.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XOverloadedStrings</option></entry>
-            <entry>Enable <link linkend="overloaded-strings">overloaded string literals</link>.
-            </entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoOverloadedStrings</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XPackageImports</option></entry>
-            <entry>Enable <link linkend="package-imports">package-qualified imports</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoPackageImports</option></entry>
-            <entry>6.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XParallelArrays</option></entry>
-            <entry>Enable parallel arrays.
-              Implies <option>-XParallelListComp</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoParallelArrays</option></entry>
-            <entry>7.4.1</entry>
-          </row>
-          <row>
-            <entry><option>-XParallelListComp</option></entry>
-            <entry>Enable <link linkend="parallel-list-comprehensions">parallel list comprehensions</link>.
-              Implied by <option>-XParallelArrays</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoParallelListComp</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XPartialTypeSignatures</option></entry>
-            <entry>Enable <link linkend="partial-type-signatures">partial type signatures</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoPartialTypeSignatures</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XPatternGuards</option></entry>
-            <entry>Enable <link linkend="pattern-guards">pattern guards</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoPatternGuards</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XPatternSynonyms</option></entry>
-            <entry>Enable <link linkend="pattern-synonyms">pattern synonyms</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoPatternSynonyms</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XPolyKinds</option></entry>
-            <entry>Enable <link linkend="kind-polymorphism">kind polymorphism</link>.
-                   Implies <option>-XKindSignatures</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoPolyKinds</option></entry>
-            <entry>7.4.1</entry>
-          </row>
-          <row>
-            <entry><option>-XPolymorphicComponents</option></entry>
-            <entry>Enable <link linkend="universal-quantification">polymorphic components for data constructors</link>.</entry>
-            <entry>dynamic, synonym for <option>-XRankNTypes</option></entry>
-            <entry><option>-XNoPolymorphicComponents</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XPostfixOperators</option></entry>
-            <entry>Enable <link linkend="postfix-operators">postfix operators</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoPostfixOperators</option></entry>
-            <entry>7.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XQuasiQuotes</option></entry>
-            <entry>Enable <link linkend="th-quasiquotation">quasiquotation</link>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoQuasiQuotes</option></entry>
-            <entry>6.10.1</entry>
-          </row>
-          <row>
-            <entry><option>-XRank2Types</option></entry>
-            <entry>Enable <link linkend="universal-quantification">rank-2 types</link>.</entry>
-            <entry>dynamic, synonym for <option>-XRankNTypes</option></entry>
-            <entry><option>-XNoRank2Types</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-          <row>
-            <entry><option>-XRankNTypes</option></entry>
-            <entry>Enable <link linkend="universal-quantification">rank-N types</link>.
-              Implied by <option>-XImpredicativeTypes</option>.</entry>
-            <entry>dynamic</entry>
-            <entry><option>-XNoRankNTypes</option></entry>
-            <entry>6.8.1</entry>
-          </row>
-        &