Convert README.cords to Markdown format

* CMakeLists.txt [enable_docs] (FILES): Install `cords.md` instead of
`README.cords`.
* Makefile.am (docdocsdir): Replace `README.cords` to `cords.md`.
* README.md (Overview): Likewise.
* docs/overview.md (Some Collector Details, Documentation files):
Likewise.
* docs/README.cords: rename to `cords.md`; convert file contents from
text to Markdown format.

CMakeLists.txt

@@ -969,9 +969,9 @@ if (enable_docs)
   install(FILES
             docs/README.autoconf
             docs/README.cmake
-            docs/README.cords
             docs/README.environment
             docs/README.macros
+            docs/cords.md
             docs/debugging.md
             docs/faq.md
             docs/finalization.md

Makefile.am

@@ -218,9 +218,9 @@ docdocsdir = $(docdir)/docs
 dist_docdocs_DATA = \
     docs/README.autoconf \
     docs/README.cmake \
-    docs/README.cords \
     docs/README.environment \
     docs/README.macros \
+    docs/cords.md \
     docs/debugging.md \
     docs/faq.md \
     docs/finalization.md \

README.md

@@ -80,7 +80,7 @@ widespread use.
 
 Rudimentary tools for use of the collector as a [leak detector](docs/leak.md)
 are included, as is a fairly sophisticated string package "cord" that
-makes use of the collector.  (See [README.cords](docs/README.cords) and
+makes use of the collector.  (See [cords.md](docs/cords.md) 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"

docs/cords.md

@@ -0,0 +1,43 @@
+# Cords package
+
+Cords package (also known as "cord library") is a string package that uses
+a tree-based representation.
+
+See `cord.h` for a description of the basic functions provided.  And, `ec.h`
+describes "extensible cords", those are essentially output streams that write
+to a cord; these allow for efficient construction of cords without requiring
+a bound on the size of a cord.
+
+The `cord` library is built along with `gc` library by default unless manually
+disabled (e.g., in case of cmake-based build, unless `-Dbuild_cord=OFF` option
+is passed to `cmake`).
+
+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.
+
+
+A fundamentally similar "rope" data structure is also part of SGI's standard
+template library implementation, and its descendants, which include the
+GNU C++ library.  That uses reference counting by default.  There is a short
+description of that data structure in
+[Rope Implementation Overview](http://www.sgi.com/tech/stl/ropeimpl.html).
+
+All of these are descendants of the "ropes" in Xerox Cedar.
+
+`cord/tests/de.c` is a very dumb text editor that illustrates the use of
+cords.  It maintains a list of file versions.  Each version is simply a cord
+representing the file contents.  Nonetheless, standard editing operations are
+efficient, even on very large files.  (Its 3-line "user manual" can be
+obtained by invoking it without arguments.  Note that `^R^N` and `^R^P` move
+the cursor by almost a screen.  It does not understand tabs, which will show
+up as highlighted "I"s.  Use the UNIX `expand` program first.)  To build the
+editor, type `make de` in the bdwgc root directory.
+
+Note that `CORD_printf` and friends use C functions with variable numbers
+of arguments in non-standard-conforming ways.  This code is known to break on
+some platforms, notably PowerPC.  It should be possible to build the remainder
+of the library (everything but `cordprnt.c`) on any platform that supports the
+collector.

docs/overview.md

@@ -93,7 +93,7 @@ For an overview of the implementation, see [here](gcdescr.md).
 The garbage collector distribution includes a C string (`cord.h`) package that
 provides for fast concatenation and substring operations on long strings.
 A simple curses- and Windows-based editor that represents the entire file as
-a cord is included as a sample application.  See [README.cords](README.cords)
+a cord is included as a sample application.  See [cords.md](cords.md)
 file for the details.
 
 Performance of the non-incremental collector is typically competitive with
@@ -261,7 +261,7 @@ The following documents are not platform-specific in general.
 
 [Instructions on how to port the library to new platforms](porting.md).
 
-[Description of the cord library built on top of GC](README.cords).
+[Description of the cord library built on top of GC](cords.md).
 
 ## More background information