--- a/README.txt	Fri Nov 25 19:49:31 2011 -0800
+++ b/README.txt	Sat Mar 23 04:43:46 2013 -0700
@@ -1,7 +1,7 @@
 buttercup: a flower for k0s.org
 ===============================
 
-buttercup is a `flower <TODO>`_ that is used to bloom a website like
+buttercup is a ``flower`` that is used to bloom a website like
 `k0s.org <http://k0s.org>`_.  There are several `python <http://python.org>`_
 components to a buttercup website:
 
@@ -13,16 +13,161 @@
  * software demos:
    - anagram
    - wordstream
+ * and so forth
+
 
 why is buttercup so messy?
 --------------------------
 
 Easy.  Its the backport of a highly specific website to a flower.  The
 buttercup flower is in fact a study in botany, useful in the study of
-species, but probably less interesting as a practical deployment.
+species, but probably less interesting as a practical deployment for
+widescale use.
 
 
 does buttercup work yet?
 ------------------------
 
-No.  It is still a work in progress.
+Depends on what you want to do.  Right now, what `buttercup` does is
+mostly best gleaned from the source code.  I hope to change this with time.
+
+
+what is a flower?
+-----------------
+
+Every website has, in essence, an intent, a purpose the website serves
+and tools and method with which to enact such purpose.  While the
+intent itself belongs to the domain of natural language, the tools
+(read: web applications) and how they are deployed (including
+e.g. request dispatching) should be catalogued in a manner actionable
+to machine.
+
+A flower is a deployment pattern of a website.
+
+The deployment pattern contains information about what tools (usually,
+python packages) are required, how they are set up for an instance of
+the pattern, and how they interact with each other; but it does not
+contain content (including site-static content) save in abstract.
+
+For example, imagine you are making a very simple website where you
+want static files and directories served from the path info segment
+``/``, a blog served at ``/blog``, and the ability to upload files to
+whatever directory ``/`` corresponds to on the web server's
+filesystem. (Let's also make it real simple and completely ignore auth
+which you should definitely *NOT* do if you were to deploy this flower.)
+If you were me, you'd probably use
+`decoupage <http://k0s.org/hg/decoupage/>`_
+ for the file server,
+`bitsyblog <http://k0s.org/hg/bitsyblog/>`_
+for the blog software,
+and `uploader <http://k0s.org/hg/uploader/>`_
+for the file upload widget.
+This would be a *flower*.  It has a clear intent -- a blog and file
+server -- and a set of tools that manifests that intent.
+You could have variations on this, such as mounting the blog at ``/``
+and files at ``/files``, but since the deployment intentions are the
+same (the tools interact with each other the same way, from a machine
+point of view).  It would be of merit to write this example flower,
+but such shall be reserved for an exercise to the reader (which may
+very well be me).
+
+
+I'm a programmer.  Can you give me a briefer explanation?
+---------------------------------------------------------
+
+Assuming you know object-oriented programming, a flower would be the
+*class* of the website, and the website would be the instance.
+
+
+what should a flower look like?
+-------------------------------
+
+As said, buttercup is currently messy.  It was written as a marriage
+between a very minimalistic need of saving some time on very specific
+problems and the abstract idea of flowers which I didn't have time to
+delve in.  Voila! Software is born.  In addition, even had I the best
+intentions and time available to them, technologies such as more
+recent pip changes were not available at the time of crafting.
+
+Also, I'm lazy and/or don't have time to work on it.
+
+In essence, ``buttercup`` has (or should have):
+
+- a list of software requirements (that should be installed in
+``--develop`` mode in a ``virtualenv``)
+- a method of "fitting the pipes" with
+  `wsgintegrate <http://k0s.org/hg/wsgintegrate/>`_
+- (and there's also something about ensuring system packages are
+   installed and what not; see e.g
+   http://k0s.org/hg/buttercup/file/c008855cf3a9/buttercup/PACKAGES.txt
+   though I believe it is yet unused)
+
+If I were to incorporate these as concepts into ``buttercup``, I would
+make the flower have:
+
+- a ``pip``
+  `requirements file <http://www.pip-installer.org/en/latest/requirements.html>`_
+
+- a skeleton of a ``wsgintegrate`` ``.ini`` file and methods to
+  interpolate this skeleton to the instance
+
+- *and*, very importantly but very forgettably, tools to port
+   production changes to the ``wsgintegrate`` configuration back to
+   the flower.
+
+- (in addition formalize the system packages (obviously per platform)
+  needed and how to check for them install them etc.  Not sure if
+  there is stuff out there for this; outside of the fact that several
+  platforms have to be supported, its a pain.  Vagrant and puppet seem
+  close...ish. Silverlining?)
+
+Obviously, this sort of make-up works for ``buttercup``.  It would not
+work so well if, say, you were using apache + mod_wsgi vs
+e.g. wsgintegrate and a standalone WSGI server.  While the latter (and
+other) software stacks can certainly be part of flowers, I care less
+about them for my personal development needs/wants.  You could imagine
+a buttercup variant, built roughly the same but with e.g. apache.
+While the intents are close, that is a different flower ... at least
+until an abstraction layer is written to obviate that difference (the
+clause itself being very illustrative as to what a flower *is*).
+
+
+why is this all coded into buttercup?  why not have one or more base packages?
+------------------------------------------------------------------------------
+
+So far all I've needed to care about was k0s.org for purposes of
+flowers.  Being not one to repeat code and being very much one to put
+things in the right place, if there is an event to abstract the logic,
+abstract I will.
+
+
+so what's the advantage of flowers, anyway?  is this just for deployment?
+-------------------------------------------------------------------------
+
+While I've presented flowers as a deployment pattern for a website,
+that is mostly for expedience and because such language is easily
+understood.  While of course this is directly usable for deployment, I
+am more interested in classification.  Its kinda like design patterns
+or whatever other sorts of patterns:  having a copy of the catalog
+does not guarantee an understanding of taxonomy.
+
+There are technical advantages at looking at websites and their
+deployments as evolving pattern.  There is the generic: the flower;
+and there is the newly deployed site.  But both change and evolve.
+You can make a new flower from the old.  You can use a flower as part
+of a flower.  They become building blocks.
+
+I want to make something crazy called *flowerbed* which combines some
+generic flower software (to be written) with wsgintegrate and a web
+interface to manipulating directed graphs (also to be written).  With
+this and a little elbow grease and unicorn dust, you could write a
+tool to allow you to make a flower (and also the website, if desired)
+just by drawing a graph with a preselected set of tools and pipes.
+But, as usual, postponed until needed.
+
+
+it seems like it'd be cool if ``buttercup``
+and other flowers were insantiable TTW.
+-------------------------------------------
+
+It does, doesn't it?  You should write that!  Or maybe I will someday.