--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.markdown	Sat Mar 19 19:53:12 2011 -0500
@@ -0,0 +1,93 @@
+fructose_gen.py
+===============
+
+Quick Start
+-----------
+
+`fructose_gen.py` is a Python script for auto-generatng the `main()` function
+for the C++ testing framework [Fructose][1].
+
+Sample usage:
+
+    $ python fructose_gen.py [options] test1.h test2.h ... testN.h > main.cpp
+
+In this example, `fructose_gen.py` will read the Fructose test files `test1.h`
+through `testN.h` and produce on standard output C++ code with a generated
+`main()` function. This auto-generated code will instantiate all the test
+instances, register the appropriate tests with each instance, and then execute
+each test in turn.
+
+To see usage information and a list of options:
+
+    $ python fructose_gen.py --help
+
+
+Code Generation Styles
+----------------------
+
+`fructose_gen.py` supports two styles of code generation, described below.
+
+### xUnit Style ###
+
+The default style is xUnit style. In this form, `fructose_gen.py` will scan
+C++ code looking for classes or structs that inherit from `fructose::test_base<>`.
+Inside those classes or structs, member functions that match the following
+pattern are assumed to be test functions:
+
+      void testXXXX(const std::string&)
+
+Upon finding such a function, `fructose_gen.py` will register that member
+function as a test with the name "testXXXX". 
+
+
+### Generator Style ###
+
+To remain backward compatible with the `generator` program that ships with
+Fructose, invoke `fructose_gen.py` with a `-g` or `--generator` option flag.
+
+In this style, `fructose_gen.py` will scan files for the `FRUCTOSE_CLASS`,
+`FRUCTOSE_STRUCT` and `FRUCTOSE_TEST` macros. See the Fructose documentation
+for more information.
+
+
+Caveats
+-------
+
+`fructose_gen.py` is not a true C++ code parser, and in fact is quite simple
+in how it operates. This is sufficient for most cases, but please be aware of
+the following limitations.
+
+1. Ensure your class (or struct) definition is all on one line:
+
+         class my_unit_test : public fructose::test_base<my_unit_test>
+
+   If you split the above across multiple lines `fructose_gen.py` will not
+   recognize your class and will not generate a test instance for it.
+
+2. `fructose_gen.py` does not understand C-style comments or the preprocessor.
+   To comment out a test, you can either use C++ comments, or change the function
+   name slightly to ensure it won't be recognized. Examples:
+
+          /*
+          ** void test_is_sorted(const std::string& name)  // this won't work
+          */
+
+          #if 0
+          void test_is_sorted(const std::string& name)   // this won't work
+          #endif
+
+          void not_a_test_is_sorted(const std::string& name) // this works
+          // void test_is_sorted(const std::string& name)    // this works
+          // FRUCTOSE_TEST(is_sorted)                        // this works
+
+   The above also applies to commenting out test classes.
+
+
+Support
+-------
+See the [fructose_gen support site][2] hosted at [bitbucket.org][3].
+
+
+[1]: http://fructose.sourceforge.net/
+[2]: https://bitbucket.org/bgneal/fructose_gen
+[3]: https://bitbucket.org