Commit 4fd6207e authored by Ben Gamari's avatar Ben Gamari 🐢

Move user's guide to ReStructuredText

parent 9ed700bb
......@@ -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
......
......@@ -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
......
......@@ -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:
......
......@@ -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:
......
......@@ -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
......
......@@ -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 ["----------------------------------------------------------------------
"]
......
#!/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
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