Remove doc.am and move gc.man to base folder

(refactoring)

This is to eliminate non-dist-doc files in doc folder.

* CMakeLists.txt [enable_docs] (doc/gc.man): Rename to gc.man.
* Makefile.am [ENABLE_DOCS] (dist_man3_MANS): Likewise.
* Makefile.direct (BSD-pkg-install): Likewise.
* Makefile.am: Do not include doc/doc.am.
* Makefile.am [ENABLE_DOCS] (dist_doc_DATA, dist_man3_MANS): Copy
assignment from doc.am.
* doc/doc.am: Remove.
* doc/gc.man: Rename to gc.man.

1 files changed, 155 insertions, 0 deletions

diff --git a/gc.man b/gc.man
new file mode 100644
index 00000000..640bd511
--- /dev/null
+++ b/gc.man
@@ -0,0 +1,155 @@
+.TH BDWGC 3 "26 Mar 2019"
+.SH NAME
+GC_malloc, GC_malloc_atomic, GC_free, GC_realloc, GC_enable_incremental,
+GC_register_finalizer, GC_malloc_ignore_off_page,
+GC_malloc_atomic_ignore_off_page, GC_set_warn_proc \- Garbage collecting
+malloc replacement
+.SH SYNOPSIS
+#include <gc.h>
+.br
+void * GC_malloc(size_t size);
+.br
+void * GC_malloc_atomic(size_t size);
+.br
+void GC_free(void *ptr);
+.br
+void * GC_realloc(void *ptr, size_t size);
+.br
+void GC_enable_incremental(void);
+.br
+void * GC_malloc_ignore_off_page(size_t size);
+.br
+void * GC_malloc_atomic_ignore_off_page(size_t size);
+.br
+void GC_set_warn_proc(void (*proc)(char *, GC_word));
+.br
+.sp
+cc ... -lgc
+.LP
+.SH DESCRIPTION
+.I GC_malloc
+and
+.I GC_free
+are plug-in replacements for standard malloc and free.  However,
+.I
+GC_malloc
+will attempt to reclaim inaccessible space automatically by invoking
+a conservative garbage collector at appropriate points.  The collector
+traverses all data structures accessible by following pointers from the
+machines registers, stack(s), data, and bss segments.  Inaccessible structures
+will be reclaimed.  A machine word is considered to be a valid pointer if
+it is an address inside an object allocated by
+.I
+GC_malloc
+or friends.
+.LP
+In most cases it is preferable to call the macros GC_MALLOC, GC_FREE, etc.
+instead of calling GC_malloc and friends directly.  This allows debugging
+versions of the routines to be substituted by defining GC_DEBUG before
+including gc.h.
+.LP
+See the documentation in the include files gc_cpp.h and gc_allocator.h,
+as well as the gcinterface.md file in the distribution,
+for an alternate, C++ specific interface to the garbage collector.
+Note that C++ programs generally
+need to be careful to ensure that all allocated memory (whether via new,
+malloc, or STL allocators) that may point to garbage collected memory
+is either itself garbage collected, or at least traced by the collector.
+.LP
+Unlike the standard implementations of malloc,
+.I
+GC_malloc
+clears the newly allocated storage.
+.I
+GC_malloc_atomic
+does not.  Furthermore, it informs the collector that the resulting object
+will never contain any pointers, and should therefore not be scanned by the
+collector.
+.LP
+.I
+GC_free
+can be used to deallocate objects, but its use is optional, and generally
+discouraged.
+.I
+GC_realloc
+has the standard realloc semantics.  It preserves pointer-free-ness.
+.I
+GC_register_finalizer
+allows for registration of functions that are invoked when an object becomes
+inaccessible.
+.LP
+The garbage collector tries to avoid allocating memory at locations that
+already appear to be referenced before allocation.  (Such apparent
+``pointers'' are usually large integers and the like that just happen to look
+like an address.)  This may make it hard to allocate very large objects.
+An attempt to do so may generate a warning.
+.LP
+.I
+GC_malloc_ignore_off_page
+and
+.I
+GC_malloc_atomic_ignore_off_page
+inform the collector that the client code will always maintain a pointer to
+near the beginning of the object (within the first 512 bytes), and that
+pointers beyond that can be ignored by the collector.  This makes it much
+easier for the collector to place large objects.  These are recommended for
+large object allocation.  (Objects expected to be > ~100 KB should be
+allocated this way.)
+.LP
+It is also possible to use the collector to find storage leaks in programs
+destined to be run with standard malloc/free.  The collector can be compiled
+for thread-safe operation.  Unlike standard malloc, it is safe to call malloc
+after a previous malloc call was interrupted by a signal, provided the
+original malloc call is not resumed.
+.LP
+The collector may, on rare occasion, produce warning messages.  On UNIX
+machines these appear on stderr.  Warning messages can be filtered,
+redirected, or ignored with
+.I
+GC_set_warn_proc
+This is recommended for production code.  See gc.h for details.
+.LP
+Fully portable code should call
+.I
+GC_INIT
+from the primordial thread of the main program before making any other
+GC calls.  On most platforms this does nothing and the collector is
+initialized on first use.  On a few platforms explicit initialization is
+necessary.  And it can never hurt.
+.LP
+Debugging versions of many of the above routines are provided as macros.
+Their names are identical to the above, but consist of all capital letters.
+If GC_DEBUG is defined before gc.h is included, these routines do additional
+checking, and allow the leak detecting version of the collector to produce
+slightly more useful output.  Without GC_DEBUG defined, they behave exactly
+like the lower-case versions.
+.LP
+On some machines, collection will be performed incrementally after a call to
+.I
+GC_enable_incremental.
+This may temporarily write protect pages in the heap.  See the README file for
+more information on how this interacts with system calls that write to the
+heap.
+.LP
+Other facilities not discussed here include limited facilities to support
+incremental collection on machines without appropriate VM support, provisions
+for providing more explicit object layout information to the garbage
+collector, more direct support for ``weak'' pointers, support for
+``abortable'' garbage collections during idle time, etc.
+.LP
+.SH "SEE ALSO"
+The README and gc.h files in the distribution.  More detailed definitions of
+the functions exported by the collector are given there.  (The above list is
+not complete.)
+.LP
+The web site at http://www.hboehm.info/gc/ (or https://github.com/ivmai/bdwgc/).
+.LP
+Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Environment",
+"Software Practice & Experience", September 1988, pp. 807-820.
+.LP
+The malloc(3) man page.
+.LP
+.SH AUTHOR
+Hans-J. Boehm (boehm@acm.org).
+Some of the code was written by others (see the AUTHORS file for the details),
+most notably by Alan Demers, and, recently, Ivan Maidanski.