Move user's guide to ReStructuredText

.gitignore

@@ -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

.travis.yml

@@ -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

INSTALL.md

@@ -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:
 

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:
 

aclocal.m4

@@ -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

configure.ac

@@ -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 ["----------------------------------------------------------------------
 "]