diff --git a/CMakeLists.txt b/CMakeLists.txt index 1142a3869..113112e1b 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/Makefile.am b/Makefile.am index cb6576138..702a8344f 100644 --- a/Makefile.am +++ b/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 \ diff --git a/README.md b/README.md index e3d433ff5..a393fec99 100644 --- a/README.md +++ b/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" diff --git a/docs/README.cords b/docs/README.cords deleted file mode 100644 index 164ae3013..000000000 --- a/docs/README.cords +++ /dev/null @@ -1,43 +0,0 @@ -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 at -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. diff --git a/docs/cords.md b/docs/cords.md new file mode 100644 index 000000000..551731462 --- /dev/null +++ b/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. diff --git a/docs/overview.md b/docs/overview.md index 0c60e72f0..b595cc359 100644 --- a/docs/overview.md +++ b/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