OTP-8449 Documentation improvements.

          The most important "readme" files now use Markdown notation. HTML
          versions of these files are now also automatically generated and
          included in the HTML documentation.

          - Building and Installing Erlang/OTP - $ERL_TOP/INSTALL.md
          (previously known as $ERL_TOP/README).

          - Cross Compiling Erlang/OTP - $ERL_TOP/INSTALL-CROSS.md.

          - How to Build Erlang/OTP on Windows - $ERL_TOP/INSTALL-WIN32.md
          (previously known as $ERL_TOP/README.win32).

4 files changed, 114 insertions, 46 deletions

diff --git a/INSTALL.md b/INSTALL.md
index 1bc0df9fd8..10071ca844 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -146,6 +146,14 @@ If you are building in a Git working directory you also have to have a GNU
 `autoconf` of at least version 2.59. Autoconf is however not needed if you
 build an unmodified version of the released source.
 
+#### Building Documentation ####
+
+*   `xsltproc` -- XSLT processor.
+*   `fop` -- Apache FOP (requires Java).
+*   `Markdown.pl` -- Optional. This is a `perl` script that generates an
+    HTML version of a document written in Markdown notation. It can be
+    downloaded at <http://daringfireball.net/projects/markdown>.
+
 ### Installing ###
 
 *   An `install` program that can take multiple file names.
@@ -191,8 +199,8 @@ Step 4: Run the following commands to configure the build:
 
     $ ./configure  [ options ]
 
-By default, Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang,man/man1}`.
-To instead install in `<BaseDir>/{bin,lib/erlang,man/man1}`, use the
+By default, Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`.
+To instead install in `<BaseDir>/{bin,lib/erlang}`, use the
 `--prefix=<BaseDir>` option.
 
 If you upgraded the source with some patch you may need to clean up
@@ -226,7 +234,7 @@ type `./configure --help` or `./configure --help=recursive` for details.
 all applications.
 
 One of the things you can specify is where Erlang/OTP should be installed: by
-default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang,man/man1}`;
+default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`;
 to keep the same structure but install in a different place, `<Dir>` say,
 use the `--prefix` argument like this: `./configure --prefix=<Dir>`.
 
@@ -241,8 +249,6 @@ Some of the available `configure` options are:
     if possible)
   * `--{enable,disable}-hipe`: HiPE support (enabled by default on supported
     platforms)
-  * `--disable-erlang-mandir`: No private Erlang mandir, i.e., the common
-    mandir under `--prefix`, or `--mandir` will be used
   * `--enable-darwin-universal`: Build universal binaries on darwin i386.
   * `--enable-darwin-64bit`: Build 64bit binaries on darwin
   * `--enable-m64-build`: Build 64bit binaries using the -m64 flag to (g)cc
@@ -427,6 +433,68 @@ want to rebuild the application `STDLIB`, then you could do:
 where `<Dir>` would be what you find `ERL_TOP` is set to in the top level
 Makefile.
 
+How to Build the Erlang/OTP Documentation
+-----------------------------------------
+
+    $ cd $ERL_TOP
+
+If you have just built Erlang/OTP in the current source tree, you have
+already ran `configure` and do not need to do this again; otherwise, run
+`configure`.
+
+    $ ./configure [Configure Args]
+
+When building the documentation you need a full Erlang/OTP-R13B04 system in
+the `$PATH`.
+
+    $ export PATH=<Erlang/OTP-R13B04 bin dir>:$PATH     # Assuming bash/sh
+
+This document as well as some other documents have been written using
+Markdown notation. HTML versions of these documents are created and included
+in the HTML documentation if the environment variable `MD2HTML` is set to a
+command that generates HTML on `stdout` for a Markdown document passed as
+argument. This is a last minute hack, which will be handled in a better way
+in the future. We currently set `MD2HTML` as follows.
+
+    $ export MD2HTML="perl <path to script>/Markdown.pl --html4tags"
+
+Build the documentation.
+
+    $ make docs
+
+The documentation can be installed either using the `install-docs` target,
+or using the `release_docs` target.
+
+*   If you have installed Erlang/OTP using the `install` target, install
+    the documentation using the `install-docs` target. Install locations
+    determined by `configure` will be used.
+
+        $ make install-docs
+
+*   If you have installed Erlang/OTP using the `release` target, install
+    the documentation using the `release_docs` target. You typically want
+    to use the same RELEASE_ROOT as when invoking `make release`.
+
+        $ make release_docs RELEASE_ROOT=<release dir>
+
+How to Install the Pre-formatted Erlang/OTP documentation
+---------------------------------------------------------
+
+Pre-formatted documentation can be downloaded at
+<http://www.erlang.org/download.html>.
+
+For some graphical tools to find the on-line help you have to install
+the HTML documentation on top of the installed OTP applications, i.e.
+
+    $ cd <PrefixDir>/lib/erlang
+    $ gunzip -c otp_html_R13B04.tar.gz | tar xf -
+
+For `erl -man <page>` to work the Unix manual pages have to be
+installed in the same way, i.e.
+
+    $ cd <PrefixDir>/lib/erlang
+    $ gunzip -c otp_man_R13B04.tar.gz | tar xf -
+
 Support for SMP (Symmetric Multi Processing)
 --------------------------------------------
 
@@ -449,22 +517,6 @@ of the emulator with SMP support by passing `-smp enable` as
 command line arguments to erl, and you can force a start of the
 emulator without SMP support by passing `-smp disable`.
 
-How to install the Erlang/OTP documentation
--------------------------------------------
-
-For some graphical tools to find the on-line help you have to install
-the HTML documentation on top of the installed OTP applications, i.e.
-
-    $ cd <PrefixDir>/lib/erlang
-    $ gunzip -c otp_html_R<XY>B-<Z>.tar.gz | tar xf -
-
-For `erl -man <page>` to work the Unix manual pages have to be
-installed in the same way, i.e.
-
-    $ cd <PrefixDir>/lib/erlang
-    $gunzip -c otp_man_R<XY>B-<Z>.tar.gz | tar xf -
-
-
 GS (Graphic System)
 -------------------
 
diff --git a/Makefile.in b/Makefile.in
index be49761490..12e485754f 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -130,20 +130,25 @@ ERLANG_INST_BINDIR= $(ERLANG_INST_LIBDIR)/bin
 # during installation. If DESTDIR != "", it cannot be run from this location.
 ERLANG_LIBDIR     = $(DESTDIR)$(ERLANG_INST_LIBDIR)
 
-# The directory in which man pages for above executables are put
-ERL_MAN1DIR      = $(DESTDIR)$(EXTRA_PREFIX)@mandir@/man1
-ERL_MAN1EXT      = 1
-
-# The directory in which Erlang private man pages are put. In order
-# not to clutter up the man namespace these are by default put in the
-# Erlang private directory $(ERLANG_LIBDIR)/man (\@erl_mandir\@ is set
-# to $(erlang_libdir)/man). If you want to install the man pages
-# together with the rest give the argument "--disable-erlang-mandir"
-# when you run configure, which will set \@erl_mandir\@ to \@mandir\@.
-#   If you want a special suffix on the manpages set ERL_MANEXT to
-# this suffix, e.g. "erl"
-ERL_MANDIR       = $(DESTDIR)$(EXTRA_PREFIX)@erl_mandir@
-ERL_MANEXT       =
+# ----------------------------------------------------------------------
+# This functionality has been lost along the way... :(
+# It could perhaps be nice to reintroduce some day; therefore,
+# it is not removed just commented out.
+
+## # The directory in which man pages for above executables are put
+## ERL_MAN1DIR      = $(DESTDIR)$(EXTRA_PREFIX)@mandir@/man1
+## ERL_MAN1EXT      = 1
+
+## # The directory in which Erlang private man pages are put. In order
+## # not to clutter up the man namespace these are by default put in the
+## # Erlang private directory $(ERLANG_LIBDIR)/man (\@erl_mandir\@ is set
+## # to $(erlang_libdir)/man). If you want to install the man pages
+## # together with the rest give the argument "--disable-erlang-mandir"
+## # when you run configure, which will set \@erl_mandir\@ to \@mandir\@.
+## #   If you want a special suffix on the manpages set ERL_MANEXT to
+## # this suffix, e.g. "erl"
+## ERL_MANDIR       = $(DESTDIR)$(EXTRA_PREFIX)@erl_mandir@
+## ERL_MANEXT       =
 
 # ----------------------------------------------------------------------
 
diff --git a/configure.in b/configure.in
index 2a9a2c50b2..21f9a640ff 100644
--- a/configure.in
+++ b/configure.in
@@ -236,16 +236,20 @@ AC_ARG_ENABLE(shared-zlib,
 [  --enable-shared-zlib        enable using shared zlib library
   --disable-shared-zlib       disable shared zlib, compile own zlib source (default)])
 
-#
-# Set Erlang man page directory
-#
-AC_ARG_ENABLE(erlang-mandir,
-[  --disable-erlang-mandir do not install Erlang man pages in a private directory],
-[ case "$enableval" in
-    no) erl_mandir=$mandir ;;
-    *)  erl_mandir='$(erlang_libdir)/man' ;;
-  esac ], erl_mandir='$(erlang_libdir)/man')
-AC_SUBST(erl_mandir)
+dnl This functionality has been lost along the way... :(
+dnl It could perhaps be nice to reintroduce some day; therefore,
+dnl it is not removed just commented out.
+dnl
+dnl #
+dnl # Set Erlang man page directory
+dnl #
+dnl AC_ARG_ENABLE(erlang-mandir,
+dnl [  --disable-erlang-mandir do not install Erlang man pages in a private directory],
+dnl [ case "$enableval" in
+dnl     no) erl_mandir=$mandir ;;
+dnl     *)  erl_mandir='$(erlang_libdir)/man' ;;
+dnl   esac ], erl_mandir='$(erlang_libdir)/man')
+dnl AC_SUBST(erl_mandir)
 
 AC_ARG_ENABLE(darwin-universal,
 [  --enable-darwin-universal    build universal binaries on darwin i386],
diff --git a/xcomp/README.md b/xcomp/README.md
index bc2696c046..9f638f46d7 100644
--- a/xcomp/README.md
+++ b/xcomp/README.md
@@ -14,7 +14,7 @@ compile Erlang/OTP. Before reading this document you should read the
 general. `$ERL_TOP` is the top directory in the source tree.
 
 `otp_build` Versus `configure`/`make`
-------------------------------------
+-------------------------------------
 
 Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build`
 script, or by invoking `$ERL_TOP/configure` and `make` directly. Building using
@@ -111,6 +111,13 @@ has to be provided in the `$PATH`. The Erlang/OTP for the target system will
 be built using this Erlang system, together with the cross compilation tools
 provided.
 
+If you want to build the documentation out of the same source tree as you are
+cross compiling in, you currently need a full Erlang/OTP system of the same
+release as the one being built for the build machine. If this is the case,
+build and install one for the build machine (or use one already built) and add
+it to the `$PATH` before cross building, and building the documentation. See
+[`$ERL_TOP/INSTALL.md`] [1] for information on building the documentation.
+
 If you want to build using a compatible Erlang/OTP system in the `$PATH`,
 jump to (3).