Updating all the read me files, license, & documentation

LICENSE.txt

@@ -0,0 +1,21 @@
+Treb is provided under the MIT License, to wit:
+
+Copyright (c) 2012, Elliott White III (Eli White)
+
+Permission is hereby granted, free of charge, to any person obtaining a 
+copy of this software and associated documentation files (the "Software"), 
+to deal in the Software without restriction, including without limitation 
+the rights to use, copy, modify, merge, publish, distribute, sublicense, 
+and/or sell copies of the Software, and to permit persons to whom the 
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included 
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
+DEALINGS IN THE SOFTWARE.

README.textile

@@ -0,0 +1,48 @@
+h1. Treb - a PHP mini-framework
+
+bq. "Treb" is short for "Trebuchet":http://en.wikipedia.org/wiki/Trebuchet, a medieval siege weapon that was of very simple design & concept, yet elegant in it's action.  It was a tool for 'quickly getting things done'  (As long as the thing at hand, was destroying a castle).  In this way, it mimics the design philosophies of this framework.
+
+h2. Background
+
+Treb is an amalgamation of experience in building custom frameworks of similar nature at numerous past employers.  In each of these cases, the goal was a custom application with specific scalability needs, and traditional PHP frameworks didn't fit the bill.
+
+When working at mojoLive, this framework was built from scratch, and in hopes of not having to write 'yet another framework' when moving on to another company.  Eli White asked permission to open source the core framework that was written for mojoLive.
+
+Treb is the result of that (and many hours of scrubbing all specific-to-mojoLive aspects out of the code).  It's a start, and will continue to be cleaned up and enhanced as time goes on.  There will most likely still be parts of how this framework operates, that are rather specific to it's original purpose's needs, that will need made more generic, but we will cross those roads as they approach us.
+
+h2. Goals / Purpose / Philosophy
+
+Treb is not a fully fleshed out framework like many, that tries to give you a solution to every path you might encounter.  Because in my experience, those frameworks do a great job of taking the 90% mark of most web projects, and making them SUPER easy.  But in the process, they don't really help you with that difficult 10% ... the parts specific to your business and how your application needs to grow.   In fact, they can hinder you, if a style of framework that requires you to do things the 'framework way', and that way doesn't work for you.  You find yourself hacking the framework just to grow.
+
+Treb is also not a micro-framework, the new style of super-compact frameworks that strive only to do some basic MVC routing for you, and then leave you to do everything yourself.
+
+Treb instead is designed to be somewhere right down the middle.  It's as minimal as it can be, to do basic MVC routing and provide you a standard directory structure to start building off of.  But at the same time, it provides a library of what I consider 'crucial' aspects for building a secure, scalable web application, such as input filtering & output escaping.  More importantly, it provides a simple data model with built in write-through data caching, and data set caching features.
+
+It is however, somewhat opinionated about those.  You certainly aren't 'required' to use the data models and/or caching layers.  You can rip those out and do whatever you want.  But if you do use them, they operate in a certain way, and assume a PDO-accessible SQL server, and a memcached compliant cache server.
+
+In the end, I'm not sure if anyone would really see Treb as a framework that you'd use to 'build an application on top of'.  But instead, as a starting point to build your application with.  You'll need and want to extend it, to bend it to match what you are needing to do.  But it should give you a major leg up on building that 'from scratch' application, without starting truly from scratch.
+
+h2. Technology
+
+Treb is not 'well architected' by modern definitions of this, it wasn't meant to be.  It was meant to be a simple, functional system.  It doesn't do dependency injection, it doesn't use namespaces, it uses the singleton & multiton patterns in specifically chosen places and it has zero tests.  It simply was made as a simple, useable, and extendable framework.
+
+It does however require PHP 5.3+, as it uses some advanced aspects of PHP, and will move to PHP 5.4 in the near future.
+
+h2. Features
+
+As mentioned there are a number of things that this framework attempts to do for you, a quick overview of them (but not exhaustive by any means) is:
+
+* MVC pattern
+* Automatic routing based upon directory structure & method names
+* Caching layer
+* DB/Model layer, with easy model creation & automatic write-through caching
+* Data Filtering, Output Escaping & Easy CSRF protection
+* Easy to use media (CSS/JS) versioning
+* A sample deployment script (From SVN to Remote Servers)
+* Cookie handling
+* PHP-based Views w/ Helper methods for common tasks
+* Numerous other small things ...
+
+h2. Documentation
+
+The best documentation in this case, is to read the code, it's well documented and should be therefore easy to extend.  You should start by reading this "Basic Documentation":https://github.com/EliW/treb/blob/master/ops/docs/framework.textile that is provided, but it doesn't cover all aspects of the framework at the moment.  After that, dive in, "download the source":https://github.com/EliW/treb/downloads, and see what you can find.

classes/README.txt

@@ -0,0 +1,3 @@
+The purpose of the /classes/ directory, is to hold any custom 
+classes that you need to make for your project.  Anything that 
+you store here will be auto loaded for you as you request them.

config/README.txt

@@ -0,0 +1,6 @@
+The /config/ directory should specifically hold one file, config.xml, 
+which is parsed by the framework in order to store various configuration 
+options for you.  The reason for a whole directory for this, is under the 
+assumption that you will end up with multiple configuration files (live, 
+test, preview, etc), that you will want to keep track of separately, and 
+that get copied to 'config.xml' as appropriate.

controllers/.readme → controllers/README.txt

@@ -1 +1,2 @@
-In /controllers/ lives, well, all your controllers, make subdirectories as you will and auto-routing will find them for you.
+In /controllers/ lives, well, all your controllers, make subdirectories 
+as you will and auto-routing will find them for you.

cron/.readme → cron/README.txt

@@ -1 +1,2 @@
-You don't need to use the /cron/ directory, but it's the nominal place to put any cron scripts that you want to create
+You don't need to use the /cron/ directory, but it's the nominal 
+place to put any cron scripts that you want to create

errors/README.txt

@@ -0,0 +1,3 @@
+In /errors/ just put a file named for each error response you want 
+a page for, such as 404.php or 500.php and it will be called as a 
+'one page stands alone' serving of those error pages.

framework/README.txt

@@ -0,0 +1,4 @@
+The /framework/ directory holds all the files related to the Treb framework 
+itself.  Modify these at your own risk.  Typically these files should be 
+left alone, and you should should write your own classes/extensions in the 
+/classes/ directory.

library/README.txt

@@ -0,0 +1,8 @@
+The /library/ directory's purpose is for you to put 3rd party PHP 
+libraries that you are using.  Why is this different from /classes/? 
+Mostly semantic, in that /classes/ is for your own code extensions 
+that you create.   Whereas /library/ should hold 3rd party ones you 
+are using.  This will help you to keep them separate in your mind & 
+the code.  Also, since you can't rely on autoloading working with 
+all the libraries, autoloading isn't enabled in the library folder.  
+Include any of these libraries on the fly as needed.

models/README.txt

@@ -0,0 +1,2 @@
+In /models/ place all of your .model.php files that handle 
+your DB<->data mapping relations.

ops/README.txt

@@ -0,0 +1,3 @@
+The /ops/ directory should hold any/all of your support programs, 
+other configuration files, etc.  It includes by default a simple 
+deployment script you can configure, as well as a CSS/JS compressor

ops/docs/framework.textile

@@ -1,12 +1,12 @@
-h1. Mojo Code Documentation
+h1. Treb Code Documentation
 
-bq. This documentation is specifically designed to be an overview of the Mojo mini-framework system that has been created here.  Making it, hopefully, easy for a new programmer to familiarize themselves with the basics of the system and understand the flow of the code & how parts of it were intended to be used.  
+bq. This documentation is specifically designed to be an overview of the Treb mini-framework system that has been created here.  Making it, hopefully, easy for a new programmer to familiarize themselves with the basics of the system and understand the flow of the code & how parts of it were intended to be used.  
 
-bq. This is *NOT* intended to serve as complete documentation, as I believe deeply in code comments for that.  You can see that via browsing the source, or via the automatically generated phpdoc pages at: "http://docs.mojolive.com/":http://docs.mojolive.com/
+bq. This is *NOT* intended to serve as complete documentation, as I believe deeply in code comments for that.  You can see that via browsing the source, or via the automatically generated phpdoc pages.
 
 h2. Basic Routing
 
-The Mojo framework has automatic routing built in.  Any request that comes in that isn't for a media file (js/css/img/font), is automatically routed into our bootstrap. From that, it looks at the URL that was provided, and attempts to find the appropriate controller to handle it.  No configuration of a routing file is needed.
+The Treb framework has automatic routing built in.  Any request that comes in that isn't for a media file (js/css/img/font), is automatically routed into our bootstrap. From that, it looks at the URL that was provided, and attempts to find the appropriate controller to handle it.  No configuration of a routing file is needed.
 
 It's actually very flexible in how it handles the routing, allowing the code structure underneath the system to change as needed, and be organized in whatever manner makes sense for that particular section of the website. All controllers are stored in the /controllers directory & related subdirectories, and so we will be looking there.  Controllers are always named in the @[name].controller.php@ naming style, extended from the main Controller class, and the methods within each file are @exec[name]()@.
 
@@ -39,7 +39,7 @@ Do note that if you use this feature, that *ANYTHING* sent after the path will b
 
 h2. Data Filtering
 
-One of the tenets of good web programming is FIEO (Filter Input, Escape Output).  The Mojo Framework has functionality for this automatically built into the framework.  For any of your action endpoints (@execNAME()@ methods), by default no data is passed into them, and all normal external data sources (such as @$_POST@, @$_GET@, etc) are destroyed/wiped by the time your action runs.  So unless you do anything, you will receive no data.  The ultimate in filtering.
+One of the tenets of good web programming is FIEO (Filter Input, Escape Output).  The Treb Framework has functionality for this automatically built into the framework.  For any of your action endpoints (@execNAME()@ methods), by default no data is passed into them, and all normal external data sources (such as @$_POST@, @$_GET@, etc) are destroyed/wiped by the time your action runs.  So unless you do anything, you will receive no data.  The ultimate in filtering.
 
 What is provided, therefore, is a filtering mechanism that allows you to not only specify what data fields you want to exist, but also to specify what kind of data should exist in each field.  The field is then filtered&sanitized for you, ensuring that the field always exists (no need for @isset()@ checks) and is a valid 'insert type' of data.
 
@@ -151,7 +151,7 @@ There are a number of other configuration options (properties) that you can set
 
 h2. Using Cache
 
-The cache mechanism built for Mojo allows for fairly easy access, and later extensibility.  At the moment, it is essentially a write-through class for Memcached.  To access the cache, a helper function has been made that returns to you the Singleton instance of cache:  @cache()@
+The cache mechanism built for Treb allows for fairly easy access, and later extensibility.  At the moment, it is essentially a write-through class for Memcached.  To access the cache, a helper function has been made that returns to you the Singleton instance of cache:  @cache()@
 
 This allows you to very easily access the singleton and at the same time set or read a single variable.  So for example, to read in the value of the key 'user.12373', you need only do:
 
@@ -296,6 +296,3 @@ You can see a list of all predefined log severities in the top of the Log class
 
 This is very useful to have debugging features in your code, that are normally turned off.  But when needed for live debugging, you can turn up the logging level for a while and watch what comes in the various log files.
 
-h2. Summary
-
-At this point just go read "http://docs.mojolive.com/":http://docs.mojolive.com/ for more details, or look in the code.

tmp/.readme → tmp/README.txt

@@ -1 +1,2 @@
-It never hurts to have a /tmp/ directory, this just preexists for use, put session files here, uploads, whatever you need
+It never hurts to have a /tmp/ directory, this just preexists for 
+use, put session files here, uploads, whatever you need

views/README.txt

@@ -0,0 +1,3 @@
+In /views/ all of your view files will be kept in a mirrored configuration 
+to that of /controllers/  The /templates subdirectory holds any of your 
+.header. and .footer. files.

web/README.txt

@@ -0,0 +1,2 @@
+The /web/ directory should be your HTML Root for Apache.  
+Don't delete the .htaccess and index.php, they are crucial to this working.

web/css/README.txt

@@ -0,0 +1,6 @@
+CSS files go here, no big whoop.   
+
+If you name a file containing the phrase .min.  So for example:  global.min.js ...
+
+Then the treb deployment script assumes that it's already been minified and 
+doesn't attempt to do it on the fly.

web/js/README.txt

@@ -0,0 +1,5 @@
+All JS files go here (or in subdirectories here).  
+
+As with CSS, you can name files with .min. in them (such as jquery.min.js), 
+and the deploy.sh program won't attempt to minify them on the fly, assuming 
+that they've already been minified once.