Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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...
commit 40851255dcb18095b453ea175faacccbc7bed3e6 1 parent 69e8c25
Rickard Green authored February 18, 2010 Erlang/OTP committed February 18, 2010
94  INSTALL.md
Source Rendered
@@ -146,6 +146,14 @@ If you are building in a Git working directory you also have to have a GNU
146 146
 `autoconf` of at least version 2.59. Autoconf is however not needed if you
147 147
 build an unmodified version of the released source.
148 148
 
  149
+#### Building Documentation ####
  150
+
  151
+*   `xsltproc` -- XSLT processor.
  152
+*   `fop` -- Apache FOP (requires Java).
  153
+*   `Markdown.pl` -- Optional. This is a `perl` script that generates an
  154
+    HTML version of a document written in Markdown notation. It can be
  155
+    downloaded at <http://daringfireball.net/projects/markdown>.
  156
+
149 157
 ### Installing ###
150 158
 
151 159
 *   An `install` program that can take multiple file names.
@@ -191,8 +199,8 @@ Step 4: Run the following commands to configure the build:
191 199
 
192 200
     $ ./configure  [ options ]
193 201
 
194  
-By default, Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang,man/man1}`.
195  
-To instead install in `<BaseDir>/{bin,lib/erlang,man/man1}`, use the
  202
+By default, Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`.
  203
+To instead install in `<BaseDir>/{bin,lib/erlang}`, use the
196 204
 `--prefix=<BaseDir>` option.
197 205
 
198 206
 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.
226 234
 all applications.
227 235
 
228 236
 One of the things you can specify is where Erlang/OTP should be installed: by
229  
-default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang,man/man1}`;
  237
+default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`;
230 238
 to keep the same structure but install in a different place, `<Dir>` say,
231 239
 use the `--prefix` argument like this: `./configure --prefix=<Dir>`.
232 240
 
@@ -241,8 +249,6 @@ Some of the available `configure` options are:
241 249
     if possible)
242 250
   * `--{enable,disable}-hipe`: HiPE support (enabled by default on supported
243 251
     platforms)
244  
-  * `--disable-erlang-mandir`: No private Erlang mandir, i.e., the common
245  
-    mandir under `--prefix`, or `--mandir` will be used
246 252
   * `--enable-darwin-universal`: Build universal binaries on darwin i386.
247 253
   * `--enable-darwin-64bit`: Build 64bit binaries on darwin
248 254
   * `--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:
427 433
 where `<Dir>` would be what you find `ERL_TOP` is set to in the top level
428 434
 Makefile.
429 435
 
  436
+How to Build the Erlang/OTP Documentation
  437
+-----------------------------------------
  438
+
  439
+    $ cd $ERL_TOP
  440
+
  441
+If you have just built Erlang/OTP in the current source tree, you have
  442
+already ran `configure` and do not need to do this again; otherwise, run
  443
+`configure`.
  444
+
  445
+    $ ./configure [Configure Args]
  446
+
  447
+When building the documentation you need a full Erlang/OTP-R13B04 system in
  448
+the `$PATH`.
  449
+
  450
+    $ export PATH=<Erlang/OTP-R13B04 bin dir>:$PATH     # Assuming bash/sh
  451
+
  452
+This document as well as some other documents have been written using
  453
+Markdown notation. HTML versions of these documents are created and included
  454
+in the HTML documentation if the environment variable `MD2HTML` is set to a
  455
+command that generates HTML on `stdout` for a Markdown document passed as
  456
+argument. This is a last minute hack, which will be handled in a better way
  457
+in the future. We currently set `MD2HTML` as follows.
  458
+
  459
+    $ export MD2HTML="perl <path to script>/Markdown.pl --html4tags"
  460
+
  461
+Build the documentation.
  462
+
  463
+    $ make docs
  464
+
  465
+The documentation can be installed either using the `install-docs` target,
  466
+or using the `release_docs` target.
  467
+
  468
+*   If you have installed Erlang/OTP using the `install` target, install
  469
+    the documentation using the `install-docs` target. Install locations
  470
+    determined by `configure` will be used.
  471
+
  472
+        $ make install-docs
  473
+
  474
+*   If you have installed Erlang/OTP using the `release` target, install
  475
+    the documentation using the `release_docs` target. You typically want
  476
+    to use the same RELEASE_ROOT as when invoking `make release`.
  477
+
  478
+        $ make release_docs RELEASE_ROOT=<release dir>
  479
+
  480
+How to Install the Pre-formatted Erlang/OTP documentation
  481
+---------------------------------------------------------
  482
+
  483
+Pre-formatted documentation can be downloaded at
  484
+<http://www.erlang.org/download.html>.
  485
+
  486
+For some graphical tools to find the on-line help you have to install
  487
+the HTML documentation on top of the installed OTP applications, i.e.
  488
+
  489
+    $ cd <PrefixDir>/lib/erlang
  490
+    $ gunzip -c otp_html_R13B04.tar.gz | tar xf -
  491
+
  492
+For `erl -man <page>` to work the Unix manual pages have to be
  493
+installed in the same way, i.e.
  494
+
  495
+    $ cd <PrefixDir>/lib/erlang
  496
+    $ gunzip -c otp_man_R13B04.tar.gz | tar xf -
  497
+
430 498
 Support for SMP (Symmetric Multi Processing)
431 499
 --------------------------------------------
432 500
 
@@ -449,22 +517,6 @@ of the emulator with SMP support by passing `-smp enable` as
449 517
 command line arguments to erl, and you can force a start of the
450 518
 emulator without SMP support by passing `-smp disable`.
451 519
 
452  
-How to install the Erlang/OTP documentation
453  
--------------------------------------------
454  
-
455  
-For some graphical tools to find the on-line help you have to install
456  
-the HTML documentation on top of the installed OTP applications, i.e.
457  
-
458  
-    $ cd <PrefixDir>/lib/erlang
459  
-    $ gunzip -c otp_html_R<XY>B-<Z>.tar.gz | tar xf -
460  
-
461  
-For `erl -man <page>` to work the Unix manual pages have to be
462  
-installed in the same way, i.e.
463  
-
464  
-    $ cd <PrefixDir>/lib/erlang
465  
-    $gunzip -c otp_man_R<XY>B-<Z>.tar.gz | tar xf -
466  
-
467  
-
468 520
 GS (Graphic System)
469 521
 -------------------
470 522
 
33  Makefile.in
@@ -130,20 +130,25 @@ ERLANG_INST_BINDIR= $(ERLANG_INST_LIBDIR)/bin
130 130
 # during installation. If DESTDIR != "", it cannot be run from this location.
131 131
 ERLANG_LIBDIR     = $(DESTDIR)$(ERLANG_INST_LIBDIR)
132 132
 
133  
-# The directory in which man pages for above executables are put
134  
-ERL_MAN1DIR      = $(DESTDIR)$(EXTRA_PREFIX)@mandir@/man1
135  
-ERL_MAN1EXT      = 1
136  
-
137  
-# The directory in which Erlang private man pages are put. In order
138  
-# not to clutter up the man namespace these are by default put in the
139  
-# Erlang private directory $(ERLANG_LIBDIR)/man (\@erl_mandir\@ is set
140  
-# to $(erlang_libdir)/man). If you want to install the man pages
141  
-# together with the rest give the argument "--disable-erlang-mandir"
142  
-# when you run configure, which will set \@erl_mandir\@ to \@mandir\@.
143  
-#   If you want a special suffix on the manpages set ERL_MANEXT to
144  
-# this suffix, e.g. "erl"
145  
-ERL_MANDIR       = $(DESTDIR)$(EXTRA_PREFIX)@erl_mandir@
146  
-ERL_MANEXT       =
  133
+# ----------------------------------------------------------------------
  134
+# This functionality has been lost along the way... :(
  135
+# It could perhaps be nice to reintroduce some day; therefore,
  136
+# it is not removed just commented out.
  137
+
  138
+## # The directory in which man pages for above executables are put
  139
+## ERL_MAN1DIR      = $(DESTDIR)$(EXTRA_PREFIX)@mandir@/man1
  140
+## ERL_MAN1EXT      = 1
  141
+
  142
+## # The directory in which Erlang private man pages are put. In order
  143
+## # not to clutter up the man namespace these are by default put in the
  144
+## # Erlang private directory $(ERLANG_LIBDIR)/man (\@erl_mandir\@ is set
  145
+## # to $(erlang_libdir)/man). If you want to install the man pages
  146
+## # together with the rest give the argument "--disable-erlang-mandir"
  147
+## # when you run configure, which will set \@erl_mandir\@ to \@mandir\@.
  148
+## #   If you want a special suffix on the manpages set ERL_MANEXT to
  149
+## # this suffix, e.g. "erl"
  150
+## ERL_MANDIR       = $(DESTDIR)$(EXTRA_PREFIX)@erl_mandir@
  151
+## ERL_MANEXT       =
147 152
 
148 153
 # ----------------------------------------------------------------------
149 154
 
24  configure.in
@@ -236,16 +236,20 @@ AC_ARG_ENABLE(shared-zlib,
236 236
 [  --enable-shared-zlib        enable using shared zlib library
237 237
   --disable-shared-zlib       disable shared zlib, compile own zlib source (default)])
238 238
 
239  
-#
240  
-# Set Erlang man page directory
241  
-#
242  
-AC_ARG_ENABLE(erlang-mandir,
243  
-[  --disable-erlang-mandir do not install Erlang man pages in a private directory],
244  
-[ case "$enableval" in
245  
-    no) erl_mandir=$mandir ;;
246  
-    *)  erl_mandir='$(erlang_libdir)/man' ;;
247  
-  esac ], erl_mandir='$(erlang_libdir)/man')
248  
-AC_SUBST(erl_mandir)
  239
+dnl This functionality has been lost along the way... :(
  240
+dnl It could perhaps be nice to reintroduce some day; therefore,
  241
+dnl it is not removed just commented out.
  242
+dnl
  243
+dnl #
  244
+dnl # Set Erlang man page directory
  245
+dnl #
  246
+dnl AC_ARG_ENABLE(erlang-mandir,
  247
+dnl [  --disable-erlang-mandir do not install Erlang man pages in a private directory],
  248
+dnl [ case "$enableval" in
  249
+dnl     no) erl_mandir=$mandir ;;
  250
+dnl     *)  erl_mandir='$(erlang_libdir)/man' ;;
  251
+dnl   esac ], erl_mandir='$(erlang_libdir)/man')
  252
+dnl AC_SUBST(erl_mandir)
249 253
 
250 254
 AC_ARG_ENABLE(darwin-universal,
251 255
 [  --enable-darwin-universal    build universal binaries on darwin i386],
9  xcomp/README.md
Source Rendered
@@ -14,7 +14,7 @@ compile Erlang/OTP. Before reading this document you should read the
14 14
 general. `$ERL_TOP` is the top directory in the source tree.
15 15
 
16 16
 `otp_build` Versus `configure`/`make`
17  
-------------------------------------
  17
+-------------------------------------
18 18
 
19 19
 Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build`
20 20
 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
111 111
 be built using this Erlang system, together with the cross compilation tools
112 112
 provided.
113 113
 
  114
+If you want to build the documentation out of the same source tree as you are
  115
+cross compiling in, you currently need a full Erlang/OTP system of the same
  116
+release as the one being built for the build machine. If this is the case,
  117
+build and install one for the build machine (or use one already built) and add
  118
+it to the `$PATH` before cross building, and building the documentation. See
  119
+[`$ERL_TOP/INSTALL.md`] [1] for information on building the documentation.
  120
+
114 121
 If you want to build using a compatible Erlang/OTP system in the `$PATH`,
115 122
 jump to (3).
116 123
 

0 notes on commit 4085125

Please sign in to comment.
Something went wrong with that request. Please try again.