Add README with rationale

svn path=/trunk/libwapcaplet/; revision=6522

1 files changed, 59 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..f8c3b8e
--- /dev/null
+++ b/README
@@ -0,0 +1,59 @@
+LibWapCaplet - a string internment library
+==========================================
+
+Overview
+--------
+
+LibWapCaplet provides a reference counted string internment system
+designed to store small strings and allow rapid comparison of them in
+terms of equality. It supports a caseless comparison where it will
+automatically intern a lowercased variant of the string and use that
+for comparison if needed.
+
+Rationale
+---------
+
+Prior to LibWapCaplet, LibParserUtils contained a dictionary and hash
+implementation along with a red-black tree implementation
+internally. These three things were then used by client applications
+and libraries such as LibCSS. However, the code was deemed to be
+inefficient and the features in the wrong library. The behaviour
+required of the client libraries was therefore split out so that
+internment would still be able to be shared between different client
+libraries in the same application. (E.g. LibCSS and Hubbub)
+
+Requirements
+------------
+
+To compile LibWapCaplet you need:
+
+ * GNU Make 3.80 or better
+ * A version of GCC capable of -MMD -MF (unless you change the build
+   system)
+
+To compile the test suite you need:
+
+ * Check v0.9.5 or better.
+
+Compilation
+-----------
+
+To build LibWapCaplet in debug mode, type 'make'. To build it in
+release mode type 'make TARGET=release'.  To install, run 'make
+install'. If you wish to install LibWapCaplet into somewhere other
+than /usr/local/ then add PREFIX=/path/to/place to the installation
+make command.
+
+Verification
+------------
+
+To build and run the tests, run 'make test'.
+
+In release mode, fewer tests will be run as the assert() calls will be
+elided.
+
+API documentation
+-----------------
+
+For API documentation see include/libwapcaplet/libwapcaplet.h
+