make validate happy

For the 100th time: Fixed the DocBook XML. >:-( Please, please, please:
Everybody should do a "make validate" before checking in any XML stuff!

identify "mode" as a class of flags, in addition to "static" and "dyanmic"

Document the -x flag

Document a few more options

Mention not to use comments on the same line as OPTIONS_GHC

Rename OPTIONS to OPTIONS_GHC.

--------------------------
	Add -fwarn-orphans flag
	--------------------------

This gives a decent report for modules that contain 'orphan' instance and
rule declarations.  These are to be avoided, because GHC has to proactively
read the interface file every single time, just in case the instance/rule is
needed.

The flag just gives a convenient way of identifying the culprits.

Implement -fwarn-incomplete-record-updates

Use XML mode, not SGML

Document -ferror-spans

spelling

Correct DocBook XML now

Started to convert the users guide to DocBook XML. Not yet finished, there are
still *tons* of misplaced indexterms, but some sensible documentation can
already be generated.

DocBook XML is case-sensitive. Note that this is still not correct DocBook, tons
of indexterm elements within varlistentries are still misplaced.

xmlize sgml docbooks

Clarify words about the -package flag

Clarify warn-unused-bindings documention

Document UNPACK pragma

Some wibbles to the optimisation section.

- Document -e

- Rearrange the documentation on "modes".  I've moved the list of
  modes from the beginning of "Using GHC", to a subsection a little
  later, and the sections describing make-mode and batch-mode are now
  further subsections of this.

- Add missing modes to the list: -M and --mk-dll.

Added short option -V for long option --version

Update the documentation for filenames and related options to reflect
the new story.  Now we talk about hierarchical modules from the
outset, and hopefully the whole description is somewhat clearer than
before.

* Remove -ffoldr-build-on
  Add -rrules-off
  Document the change

* Document -fwarn-simple-patterns more

Document external core a bit more

Document {-# CORE #-} pragma (thanks to Hal Daume)

Document warning suppression with leading underscore on variable names

Update the documentation on --make mode to indicate that multiple
sources/modules can be given on the command line, as well as multiple
object files.

MERGE TO STABLE

-----------------------------------------------
	Add -Werror flag, which makes warnings fatal
	-----------------------------------------------

-Werror is standard gcc-ism; it makes warnings into fatal errors
so you don't miss them in a batch compile.

Fairly easy to implement, by modifying ErrUtils.errorsFound

Suggested by Ashley Yakeley

Add an example about -osuf etc

Notes on .exe files

Improve the documentation for hierarchical libraries.

Various hacking on the User's Guide to knock it into shape for the release.

Committers: please take a look at the 5.04 release notes and feel free
to tweak or embelish the description for your favourite new feature.

Replace all instances of '--' with '––' since '--' gets
interpreted by JadeTeX to mean a single dash.

Nuke -O2-for-C, since it can cause gcc to generate incorrect code, and
doesn't seem to help much.  Add a comment about this in the 5.02
release notes, saying you can still use -optc-O2 if you really want
to.

(merged from rev. 1.47.2.3)

- document --print-libdir
- replace some <literal>s with <option>s where appropriate

merge rev 1.47.2.1:

* typo ('-help' -> '--help')

document -fext-core flag and set pointers to ext-core docs/tools (MERGE to STABLE pleeeeeease.)

markup fixes

Put a big flashing warning sign next to the description of -O2-for-C,
and don't endorse it by claiming that we actually use it (we don't).