Add Github flavored readme files

action/README.md

@@ -0,0 +1 @@
+The `action` namespace relies on `lithium\http`, and includes classes required to route and dispatch HTTP requests.

console/README.md

@@ -0,0 +1,187 @@
+
+The console package contains a set of classes required to route and dispatch
+incoming console requests. Moreover it contains the console front-controller
+file (`lithium.php`) as well as wrappers for both *nix and Windows environments
+(`li3` and `li3.bat` respectively), allowing to easily invoke the
+console front-controller from the command line.
+
+A command is to the command line what an action controller is to the HTTP
+request/response flow. In that commands are quite similar to controllers.
+Commands don't leverage the the full MVC as they don't utilize views, but
+directly interact with the user through `in()` and `out()`.
+
+Lithium itself provides amongst others commands for creating new applications
+or parts thereof. However commands can also be provided through other libraries
+or by your application. Commands running in the application context will have
+complete access to your application. This is especially useful to reuse
+existing logic in an application's model when creating a command to be run as
+i.e. a cron-job.
+
+-----
+
+## Invoking the front-controller ##
+
+You right away invoke the console front-controller through one of the wrappers
+provided. From the root directory of a standard Lithium distribution call  one
+of the follwing commands. The first is for users on a *nix command line the
+second for users on a Windows system. Please note that the preceding `$` in
+examples always indicates things that you entere on the command line.
+
+    $ libraries/lithium/console/li3
+    $ libraries/lithium/console/li3.bat
+
+
+However it is recommended you add the path containing the wrapper to the paths
+searched by your system. This is `$PATH` for *nix and `%PATH%` for Windows.
+
+
+### A: Configuring your $PATH on *nix ###
+
+This is almost always achievable on a per-user basis through the user's
+`.profile` (Users running Bash may prefer `.bash_profile`). The file is located
+in your home directory.  Open the file and add the following line, assuming the
+`li3` wrapper exists in `/path/to/libraries/lithium/console`.
+
+    export PATH+=:/path/to/libraries/lithium/console
+
+
+Once you've followed these steps, save your modified the file and reload your environment settings
+by sourcing the modified profile through the following command.
+
+    $ source ~/.profile
+
+
+If you can't or don't want to modify your `$PATH` you use two other techniques
+to make the wrapper available as just `li3`.  You can either symlink the
+wrapper into one of the paths found in the `$PATH` environment variable or
+create a permanent alias by adding an alias to i.e. the `.bashrc` file in your
+home directory.
+
+    $ cd /path/to/a/directory/in/your/path
+    $ ln -s /path/to/libraries/lithium/console .
+
+
+
+    alias li3='/path/to/lithium/libraries/lithium/console/li3'
+
+
+### B: Configuring your %PATH% on Windows ###
+
+**Note**: Please note that if you're on  Windows you've additionally got to add the PHP directory to
+  the `%PATH%` environment variable. As we are going to edit that variable for adding
+  the location of where the `li3.bat` wrapper is anyway, we can kill two birds with one stone.
+
+ * Open _System_ from within the _Control Panel_.
+ * Open the _Advanced_ tab.
+ * Clicking the _Environment Variables_ button open a dialog where you can edit the variables.
+ * Double click the _PATH_ entry in order to edit it.
+ * Add `;C:\path\to\php;C:\path\to\libraries\lithium\console` to the end of the value.
+
+### Finishing up ###
+
+Now that you've made the wrapper available as `li3` or `li3.bat` respectively,
+you should be able to use it from the command-line just by executing `li3` and
+`li3.bat`. Invoking the wrapper like that (without arguments) should give you a
+list of available commands.
+
+    $ li3
+    $ li3.bat
+
+-----
+
+## Built-in commands ##
+
+Using the commands which come with lithium is easy. Invoke the wrapper without
+any arguments to get a list of all available commands. Get a description about
+each command and the options and arguments it accept or may require by using
+the `help` command.
+
+    $ li3 help
+    $ li3 help create
+    $ li3 help g11n
+
+-----
+
+## Creating custom commands ##
+
+Creating your own commands is very easy. A few fundamentals:
+
+* All commands inherit from `lithium\console\Command`.
+* Commands are normally placed in your application or library's `extensions/commands` directory.
+
+Here's an example command:
+
+
+    <?php
+
+    namespace app\extensions\command;
+
+    class HelloWorld extends \lithium\console\Command {
+
+      public function run() {
+		    $this->header('Welcome to the Hello World command!');
+		    $this->out('Hello, World!');
+      }
+    }
+
+    ?>
+
+
+If you would like to try this command, create an application or use an existing
+application, and place the command into the application's `extensions/commands`
+directory and save it as `HelloWorld.php`. After doing so, open a shell and
+change directory to your application's directory and run the following command:
+
+
+    $ li3 hello_world
+
+
+Although it's probably obvious, when this command runs it will output a nice
+header with the text `Welcome to the Hello World command!` and some regular
+text `Hello, World!` after it.
+
+The public method `run()` is called on your command instance every time your
+command has been requested to run. From this method you can add your own command
+logic.
+
+### Parsing options and arguments ###
+
+Parsing options and arguments to commands should be simple. In fact, the
+parsing is already done for you.
+
+Short and long (GNU-style) options in the form of `-f`, `--foo` and `--foo=bar`
+are automatically parsed and exposed to your command instance through its
+properties. XF68-style long options (i.e. `-foo`) are not supported by default
+but support can be added by extending the console router.
+
+Arguments are passed directly to the invoked method.
+
+Let's look at an example, going back to the `hello_world` command from earlier:
+
+    <?php
+
+    namespace app\extensions\command;
+
+    class HelloWorld extends \lithium\console\Command {
+
+      public $recipient;
+
+      public function run() {
+        $this->header('Welcome to the Hello World command!');
+        $this->out('Hello, ' . ($this->recipient ?: 'World') . '!');
+      }
+    }
+
+    ?>
+
+
+Notice the additional property `$recipient`? Great! Now when `--recipient` is
+passed to the `hello_world` command, the recipient property on your command
+instance will be set to whatever was passed into the command at runtime.
+
+Try it out with the following command:
+
+    $ li3 hello_world --recipient=AwesomeGuy
+
+
+You should get a special greeting from our good old `hello_world` command.

template/README.md

@@ -0,0 +1,160 @@
+
+## Special syntax ##
+
+Views have a special syntax for outputting escaped text. The standard way to
+output escaped text in your views from Lithium is as follows:
+
+    <?= $variable; ?>
+
+
+This is where a lot of confusion comes in, because it is commonly misunderstood
+that Lithium depends on `short_open_tags`, however, that's not the case. The
+contents of a view are processed through a tokenizer (`template/view/Compiler`) before
+it is included by PHP. The file is then `compiled` into the final PHP+HTML (or whatever
+other content type that is requsted), which is then passed off to be fully rendered
+by the two-step view to its final form.
+
+See the PHP [manual](http://php.net/manual/en/book.tokenizer.php) to learn more about tokens.
+
+The stream wrapper reads the file and searches for anything that looks like
+`<?=...?>` and replaces it with `<?php echo $h(...); ?>`.
+
+The design decision behind using PHP's short echo syntax is because it's a
+familiar syntax and it helps developers focus more on what data _should not_ be
+escaped vs. what data _needs_ to be escaped.
+
+One special case situation to take _important_ note of, is the use of `<?=$this->foo()?>`.
+In this scenario, the code is translated to `<?php echo $this->foo(); ?>`
+rather than being filtered through `$h()` as with the former explanation. When direct access to a method or property on `$this` is contained in the shorthands syntax, it will be output as normal without being filtered.
+This is to make it easier to work with helpers that return markup.
+
+An example would be something like:
+
+    <?=$this->form->create();?>
+    ... my form here ...
+    <?=$this->form->end();?>
+
+**Note:** `$h()` is the HTML escape function used in views.
+
+**Note:** To output regular, unescaped text, use plain old `<?php echo ...; ?>`.
+
+**Other useful information:**
+
+ * [Introduction to PHP streams](http://www.php.net/intro.stream)
+ * [Stream examples](http://www.php.net/stream.examples)
+
+----
+
+## Using helpers ##
+
+Helpers are lazy-loaded by the current renderer. To use a helper, you can
+reference it by its name like this:
+
+    echo $this->html->link('Google', 'http://www.google.com');
+
+In a template, `$this` refers to the `Renderer` object. By using `$this->html`
+for the first time, the renderer will create an instance of the helper and store
+it so that the next time the helper is invoked the renderer will not have to
+re-instantiate the helper.
+
+Using such an approach, helpers can easily be loaded as needed without any
+performance impact.
+
+**More info**
+
+ * [ HTML helper](template/helper/Html)
+ * [ Form helper](template/helper/Form)
+ * [ Helper base class](template/Helper)
+
+----
+
+## Creating custom helpers ##
+
+You can also create your own custom helper very easily by extending the `Helper` base class, and
+placing your helper in the correct namespace. By default, helpers belong in the
+`<library>\extensions\helper` namespace, but this can be changed through configuration (see the
+the `Libraries` class (`core/Libraries`)).
+For example, consider the following class, saved as `app/extensions/helper/Custom.php`:
+
+    <?php
+
+    namespace app\extensions\helper;
+
+    class Custom extends \lithium\template\Helper {
+
+      public function greeting($name) {
+        return "Hello {$name}!";
+      }
+    }
+
+   ?>
+
+
+You can then use your helper in templates as follows:
+
+    <?=$this->custom->greeting("World"); ?>
+
+
+Your custom helper will then be auto-loaded into the templating engine from your application or a
+plugin.
+
+----
+
+## Extending core helpers ##
+
+Because your application and plugins have a higher order-of-precedence than the Lithium core,
+classes like helpers can be extended and replaced seamlessly, without any changes to your templates.
+
+For example, to add or replace methods in the `Form` helper, you can add the following to
+`app/extensions/helper/Form.php`:
+
+
+    <?php
+
+    namespace app\extensions\helper;
+
+    class Form extends \lithium\template\helper\Form {
+
+      // Add or override Form helper methods
+    }
+
+    ?>
+
+
+Your custom `Form` helper will now be invoked in all instances where `$this->form` is called in a
+template. For more information on the load order of classes, see
+the `locate()` method of the `Libraries` class (`core/Libraries::locate`)
+
+----
+
+## Rendering elements ##
+
+Elements are reusable view snippets that you can use in several views and layouts.
+You can reference it like so:
+
+    echo $this->_render('element', 'menu');
+
+
+Where `menu` is the name of your element file, in this example `app/views/elements/menu.html.php`.  When using `$this->_render()`, all of the variables set in the controller are available to the element template.
+You can pass variables declared in the view or additional static content using the third parameter to `$this->_render()`:
+
+    $var1 = 'something';
+    echo $this->_render('element', 'menu', array(
+      'var1' => $var1,
+      'var2' => 'something else'
+    ));
+
+
+If you need the element template to not have access to existing data passed to the parent template, use the alternate syntax that calls the `View` render method directly:
+
+    echo $this->view()->render(
+      array('element' => 'menu'),
+      array('var1' => $var1, 'var2' => $var2)
+    );
+
+
+**More info**
+
+ *  `View` (`template/View`)
+ *  `Renderer` (`template/view/Renderer`)
+ *  `File adapter` (`template/view/adapter/File`)