Permalink
Browse files

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).
  • Loading branch information...
1 parent 69e8c25 commit 40851255dcb18095b453ea175faacccbc7bed3e6 @rickard-green rickard-green committed with Erlang/OTP Feb 18, 2010
Showing with 114 additions and 46 deletions.
  1. +73 −21 INSTALL.md
  2. +19 −14 Makefile.in
  3. +14 −10 configure.in
  4. +8 −1 xcomp/README.md
View
@@ -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)
-------------------
View
@@ -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 =
# ----------------------------------------------------------------------
View
@@ -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],
View
@@ -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).

0 comments on commit 4085125

Please sign in to comment.