Move non-license info from LICENSE file to README

* LICENSE: Remove INSTALLATION, TYPICAL USE, WARNINGS sections (i.e.,
remove all non-license information).
* README.md (Overview): Add link to README.cords; some other minor changes;
reformat text.
* README.md (General Description): Add link to README.win32 and
README.win64; reformat text.
* README.md (Installation and Portability): Mention CMake before providing
exact build commands; add reference to README.cmake and README.macros;
mention how to build the collector on Windows; mention that threads are on
be default; mention how to build cord library with Makefile.direct mention
that Symbian has a separate makefile.
* README.md (The C++ Interface to the Allocator): Copy information about
building the C++ GC libraries from LICENSE; add link to gcinterface.md.
* doc/README.cords: Copy information about cord library building from
LICENSE file.

3 files changed, 63 insertions, 107 deletions

diff --git a/LICENSE b/LICENSE
index 00d52163..9bedaa80 100644
--- a/LICENSE
+++ b/LICENSE
@@ -28,71 +28,3 @@ to use the GNU-style build procedure come with a modified GPL license
 that appears not to significantly restrict use of the collector, though
 use of those files for a purpose other than building the collector may
 require the resulting code to be covered by the GPL.
-
-For more details and the names of other contributors, see the README.md,
-doc/README.*, AUTHORS and include/gc.h files.  These files describe typical
-use of the collector on a machine that is already supported.
-
-For the version number, see README.md or include/gc_version.h files.
-
-INSTALLATION:
-Under UN*X, Linux, Cygwin:
-Alternative 1 (the old way): type "make -f Makefile.direct check".
-        Link against libgc.a.
-
-Alternative 2 (the new way): type
-        "./configure --prefix=<dir>; make; make check; make install".
-        Link against <dir>/lib/libgc.a or <dir>/lib/libgc.so.
-        See doc/README.autoconf for details.
-
-Alternative 3 (another new way): type
-        "mkdir out; cd out; cmake ..; cmake --build ."
-        See doc/README.cmake for details.
-
-Under Windows 95, 98, Me, NT, or 2000:
-copy the appropriate makefile to MAKEFILE, read it, and type "nmake check".
-(Under Windows, this assumes you have Microsoft command-line tools
-installed, and suitably configured.)
-Read the machine specific README.XXX in the doc directory if one exists.
-
-If you need thread support, you should define GC_THREADS as described in
-doc/README.macros (configure defines this implicitly unless --disable-threads
-option is given).
-
-If you wish to use the cord (structured string) library with the stand-alone
-Makefile.direct, type "make -f Makefile.direct cords".  (You may need to
-override CC specified in the Makefile. The CORD_printf implementation in
-cordprnt.c is known to be less than perfectly portable.  The rest of the
-package should still work.)  See include/cord.h for the API.
-
-If you wish to use the collector from C++, type "make c++", or use
---enable-cplusplus with the configure script.  This creates libgccpp.a and
-libgctba.a files, or their shared library equivalents (libgccpp.so and
-libgctba.so).  You should link with either the first or the second one, but
-not both.  See include/gc_cpp.h and doc/gcinterface.md.
-
-TYPICAL USE:
-Include "gc.h" from the include subdirectory.  Link against the
-appropriate library ("libgc.a" under UN*X).  Replace calls to malloc
-by calls to GC_MALLOC, and calls to realloc by calls to GC_REALLOC.
-If the object is known to never contain pointers, use GC_MALLOC_ATOMIC
-instead of GC_MALLOC.
-
-Define GC_DEBUG before including gc.h for additional checking.
-
-More documentation on the collector interface can be found in README.md,
-doc/gcinterface.md, include/gc.h, and other files in the doc directory.
-
-WARNINGS:
-
-Do not store the only pointer to an object in memory allocated
-with system malloc, since the collector usually does not scan
-memory allocated in this way.
-
-Use with threads may be supported on your system, but requires the collector
-to be built with thread support.  See Makefile.am or Makefile.direct.
-The collector does not guarantee to scan thread-local storage (e.g. of the
-kind accessed with pthread_getspecific()).  The collector does scan
-thread stacks though, so generally the best solution is to ensure that
-any pointers stored in thread-local storage are also stored on the
-thread's stack for the duration of their lifetime.
diff --git a/README.md b/README.md
index fb3c38b5..97cda16c 100644
--- a/README.md
+++ b/README.md
@@ -53,8 +53,6 @@ discussed in
  * Boehm, H., and D. Chase, "A Proposal for GC-safe C Compilation",
    The Journal of C Language Translation 4, 2 (December 1992).
 
-and
-
  * Boehm H., "Simple GC-safe Compilation", Proceedings of the ACM SIGPLAN '96
    Conference on Programming Language Design and Implementation.
 
@@ -62,7 +60,7 @@ Unlike the collector described in the second reference, this collector
 operates either with the mutator stopped during the entire collection
 (default) or incrementally during allocations.  (The latter is supported
 on fewer machines.)  On the most common platforms, it can be built
-with or without thread support.  On a few platforms, it can take advantage
+with or without thread support.  On some platforms, it can take advantage
 of a multiprocessor to speed up garbage collection.
 
 Many of the ideas underlying the collector have previously been explored
@@ -74,13 +72,13 @@ CSL 84-7).  Doug McIlroy wrote a simpler fully conservative collector that
 was part of version 8 UNIX (tm), but appears to not have received
 widespread use.
 
-Rudimentary tools for use of the collector as a
-[leak detector](doc/leak.md) are included,
-as is a fairly sophisticated string package "cord" that makes use of the
-collector.  (See doc/README.cords and H.-J. Boehm, R. Atkinson, and M. Plass,
-"Ropes: An Alternative to Strings", Software Practice and Experience 25, 12
-(December 1995), pp. 1315-1330.  This is very similar to the "rope" package
-in Xerox Cedar, or the "rope" package in the SGI STL or the g++ distribution.)
+Rudimentary tools for use of the collector as a [leak detector](doc/leak.md)
+are included, as is a fairly sophisticated string package "cord" that
+makes use of the collector.  (See [README.cords](doc/README.cords) and
+H.-J. Boehm, R. Atkinson, and M. Plass, "Ropes: An Alternative to Strings",
+Software Practice and Experience 25, 12 (December 1995), pp. 1315-1330.
+This is very similar to the "rope" package in Xerox Cedar, or the "rope"
+package in the SGI STL or the g++ distribution.)
 
 Further collector documentation can be found in the
 [overview](doc/overview.md).
@@ -128,9 +126,9 @@ best to compile with `ALL_INTERIOR_POINTERS` and to use
 `GC_malloc_ignore_off_page` if you get collector warnings from
 allocations of very large objects.  See [here](doc/debugging.md) for details.
 
-_WARNING_: pointers inside memory allocated by the standard `malloc` are not
-seen by the garbage collector.  Thus objects pointed to only from such a
-region may be prematurely deallocated.  It is thus suggested that the
+_WARNING_: pointers inside memory allocated by the standard (system) `malloc`
+are not seen by the garbage collector.  Thus objects pointed to only from such
+a region may be prematurely deallocated.  It is thus suggested that the
 standard `malloc` be used only for memory regions, such as I/O buffers, that
 are guaranteed not to contain pointers to garbage collectible memory.
 Pointers in C language automatic, static, or register variables,
@@ -139,16 +137,16 @@ semantics similar to standard malloc, but allocates objects that are
 traced by the collector.)
 
 _WARNING_: the collector does not always know how to find pointers in data
-areas that are associated with dynamic libraries.  This is easy to
-remedy IF you know how to find those data areas on your operating
-system (see `GC_add_roots`).  Code for doing this under SunOS, IRIX
-5.X and 6.X, HP/UX, Alpha OSF/1, Linux, and win32 is included and used
-by default.  (See doc/README.win32 for Win32 details.)  On other systems
-pointers from dynamic library data areas may not be considered by the
-collector.  If you're writing a program that depends on the collector
-scanning dynamic library data areas, it may be a good idea to include
-at least one call to `GC_is_visible` to ensure that those areas are
-visible to the collector.
+areas that are associated with dynamic libraries.  This is easy to remedy
+if you know how to find those data areas on your operating system (see
+`GC_add_roots`).  Code for doing this under SunOS, IRIX 5.X and 6.X, HP/UX,
+Alpha OSF/1, Linux, and Win32 is included and used by default.
+(See [README.win32](doc/README.win32) and [README.win64](doc/README.win64)
+for Windows details.)  On other systems, pointers from dynamic library data
+areas may not be considered by the collector.  If you're writing a program
+that depends on the collector scanning dynamic library data areas, it may
+be a good idea to include at least one call to `GC_is_visible` to ensure
+that those areas are visible to the collector.
 
 Note that the garbage collector does not need to be informed of shared
 read-only data.  However, if the shared library mechanism can introduce
@@ -176,18 +174,18 @@ stored on the thread's stack for the duration of their lifetime.
 ## Installation and Portability
 
 The collector operates silently in the default configuration.
-In the event of problems, this can usually be changed by defining the
+In the event of issues, this can usually be changed by defining the
 `GC_PRINT_STATS` or `GC_PRINT_VERBOSE_STATS` environment variables.  This
 will result in a few lines of descriptive output for each collection.
 (The given statistics exhibit a few peculiarities.
 Things don't appear to add up for a variety of reasons, most notably
 fragmentation losses.  These are probably much more significant for the
-contrived program "test.c" than for your application.)
+contrived program `tests/test.c` than for your application.)
 
 On most Unix-like platforms, the collector can be built either using a
 GNU autoconf-based build infrastructure (type `./configure; make` in the
-simplest case), or with a classic makefile by itself (type
-`make -f Makefile.direct`).
+simplest case), or using CMake (see the sample below), or with a classic
+makefile by itself (type `make -f Makefile.direct`).
 
 Please note that the collector source repository does not contain configure
 and similar auto-generated files, thus the full procedure of autoconf-based
@@ -202,9 +200,10 @@ build of `master` branch of the collector could look like:
     make check
 
 Cloning of `libatomic_ops` is now optional provided the compiler supports
-atomic intrinsics.
+atomic intrinsics.  See [README.autoconf](doc/README.autoconf) for details.
 
-Alternatively, the collector could be built with CMake, like this:
+As noted above, alternatively, the collector could be built with CMake, like
+this:
 
     mkdir out
     cd out
@@ -212,11 +211,25 @@ Alternatively, the collector could be built with CMake, like this:
     cmake --build .
     ctest
 
+See [README.cmake](doc/README.cmake) for details.
+
 Finally, on most targets, the collector could be built and tested directly
 with a single compiler invocation, like this:
 
     gcc -I include -o gctest tests/test.c extra/gc.c && ./gctest
 
+On Windows, CMake could be used to build the library as described above or
+by typing `nmake -f NT_MAKEFILE`, this assumes you have Microsoft command-line
+tools installed and suitably configured.  See [README.win32](doc/README.win32)
+for details.
+
+The library is built with threads support on (i.e. for thread-safe operation)
+by default, unless `--disable-threads` is passed to `./configure` (or
+`-Denable_threads=OFF` is passed to `cmake` tool).
+
+The library could be configured more precisely during the build by defining
+the macros listed in [README.macros](doc/README.macros) file.
+
 Below we focus on the collector build using classic makefile.  For the
 Makefile.direct-based process, typing `make check` instead of `make` will
 automatically build the collector and then run `setjmp_test` and `gctest`.
@@ -230,7 +243,8 @@ version will use more.  64-bit versions may use more.) `make check` will also,
 as its last step, attempt to build and test the "cord" string library.)
 
 Makefile.direct will generate a library libgc.a which you should link against.
-Typing "make cords" will build the cord library (libcord.a).
+Typing `make -f Makefile.direct cords` will build the cord library (libcord.a)
+as well.
 
 The GNU style build process understands the usual targets.  `make check`
 runs a number of tests.  `make install` installs at least libgc, and libcord.
@@ -245,13 +259,13 @@ The collector currently is designed to run essentially unmodified on
 machines that use a flat 32-bit or 64-bit address space.
 That includes the vast majority of Workstations and X86 (X >= 3) PCs.
 
-In a few cases (Amiga, OS/2, Win32, MacOS) a separate makefile
-or equivalent is supplied.  Many of these have separate README.system
-files.
+In a few cases (Amiga, OS/2, PCR, Symbian, Win32) a separate makefile
+or equivalent is supplied.  Many of these have separate a host-specific
+doc/README.* file.
 
 Dynamic libraries are completely supported only under SunOS/Solaris,
 (and even that support is not functional on the last Sun 3 release),
-Linux, FreeBSD, NetBSD, IRIX 5&6, HP/UX, Win32 (not Win32S) and OSF/1
+Linux, FreeBSD, NetBSD, IRIX, HP/UX, Win32 (not Win32s) and OSF/1
 on DEC AXP machines plus perhaps a few others listed near the top
 of dyn_load.c.  On other machines we recommend that you do one of
 the following:
@@ -384,10 +398,15 @@ This is rarely necessary.  Details can be found in gc_typed.h.
 
 The Ellis-Hull C++ interface to the collector is included in the collector
 distribution.  If you intend to use this, type
-`./configure --enable-cplusplus; make` (or `make -f Makefile.direct c++`)
-after the initial build of the collector is complete.  See gc_cpp.h for the
-definition of the interface.  This interface tries to approximate the
-Ellis-Detlefs C++ garbage collection proposal without compiler changes.
+`./configure --enable-cplusplus && make` (or
+`cmake -Denable_cplusplus=ON . && cmake --build .`, or
+`make -f Makefile.direct c++` depending on the build system you use).
+This creates libgccpp.a and libgctba.a files, or their shared library
+equivalents (libgccpp.so and libgctba.so).  You should link with either the
+first (gccpp) or the second one (gctba), but not both.  See gc_cpp.h and
+[gcinterface.md](doc/gcinterface.md) for the definition of the interface.
+This interface tries to approximate the Ellis-Detlefs C++ garbage collection
+proposal without compiler changes.
 
 Very often it will also be necessary to use gc_allocator.h and the
 allocator declared there to construct STL data structures.  Otherwise
diff --git a/doc/README.cords b/doc/README.cords
index 7cdb186e..ad0b9a41 100644
--- a/doc/README.cords
+++ b/doc/README.cords
@@ -5,7 +5,12 @@ See cord.h for a description of the functions provided.  Ec.h describes
 to a cord.  These allow for efficient construction of cords without
 requiring a bound on the size of a cord.
 
-More details on the data structure can be found in
+The cord library is built by default in case of the GNU autoconf-based build
+and the CMake-based one (unless "-Dbuild_cord=OFF" option is given to cmake).
+If you wish to build the library with the stand-alone Makefile.direct, type
+"make -f Makefile.direct cords".
+
+More details on the data structure can be found in:
 
 Boehm, Atkinson, and Plass, "Ropes: An Alternative to Strings",
 Software Practice and Experience 25, 12, December 1995, pp. 1315-1330.