Kohana v3.3.0

modules/userguide/guide/de-de/about.conventions.md

@@ -0,0 +1,300 @@
+# Regeln
+
+Es wird dazu ermutigt, dem Kohana [Programmierstil](http://dev.kohanaframework.org/wiki/kohana2/CodingStyle) zu folgen. Dieser benutzt den [Allman/BSD](http://de.wikipedia.org/wiki/Einr%C3%BCckungsstil#Allman_.2F_BSD_.2F_.E2.80.9EEast_Coast.E2.80.9C_.2F_Horstmann)-Stil.
+
+## Klassennamen und Dateilage {#classes}
+
+Das automatische Laden von Klassen wird durch ihre strengen Namensregeln erm<72>glicht. Die Klassen beginnen mit einem Gro<72>buchstaben und ihre W<>rter werden durch Unterstriche getrennt. Diese sind entscheidend, an welcher Stelle die Klasse im Dateisystem gefunden wird. 
+
+Folgende Regeln gelten:
+
+1. Binnenversalien (camelCase) sollten nicht benutzt werden, au<61>er wenn eine weitere Ordner-Ebene unerw<72>nscht ist
+2. alle Datei- und Verzeichnisnamen in Kleinbuchstaben
+3. alle Klassen werden im `classes`-Verzeichnis in jeder Ebene des [Kaskaden-Dateisystem](about.filesystem) zusammengefasst
+
+[!!] Im Gegensatz zu Kohana v2.x besteht keine Unterteilung zwischen "Controllern", "Models", "Bibliotheken" und "Helfern". Alle Klassen befinden sich im "classes/"-Verzeichnis, unabh<62>ngig ob es statische "Helfer" oder Objekt-"Bibliotheken" sind. Man kann irgendeinen Klassen-Aufbau (statische Klasse, Singleton, Adapter) verwenden, den man mag.
+
+## Beispiele
+
+Denk daran, dass der Unterstrich in Klassennamen eine tiefere Verzeichnisebene bedeutet. Beachte folgende Beispiele:
+
+Klassenname           | Dateipfad
+----------------------|-------------------------------
+Controller_Template   | classes/controller/template.php
+Model_User            | classes/model/user.php
+Database              | classes/database.php
+Database_Query        | classes/database/query.php
+Form                  | classes/form.php
+
+## Programmierstil {#coding_standards}
+
+Um einen sehr konsistenten Quelltext zu produzieren, bitten wir jeden den folgenden Programmierstil so genau wie m<>glich umzusetzen.
+
+### Klammerung
+
+Bitte benutze den den [Allman/BSD](http://de.wikipedia.org/wiki/Einr%C3%BCckungsstil#Allman_.2F_BSD_.2F_.E2.80.9EEast_Coast.E2.80.9C_.2F_Horstmann)-Stil.
+
+### Namensregeln
+
+Kohana benutzt f<>r Namen Unter_striche, keine BinnenVersalien (camelCase).
+
+#### Klassen
+
+	// Libary
+	class Beer {
+
+	// Libary extension, uses Kohana_ prefix
+	class Beer extends Kohana_Beer {
+
+	// Controller class, uses Controller_ prefix
+	class Controller_Apple extends Controller {
+
+	// Model class, uses Model_ prefix
+	class Model_Cheese extends Model {
+
+	// Helper class, cf. libary
+	class peanut {
+
+Benutze keine Klammern, wenn eine Klasseninstanz erstellt, aber keine Parameter <20>bergibt:
+
+	// Correct:
+	$db = new Database;
+
+	// Incorrect:
+	$db = new Database();
+
+#### Funktionen und Methoden
+
+Funktionen sollten kleingeschrieben sein und Unter_striche zur Worttrennung benutzen:
+
+	function drink_beverage($beverage)
+	{
+
+#### Variablen
+
+Alle Variablen sollten ebenfalls kleingeschrieben sein und Unter_striche benutzen, keine BinnenVersalien (camelCase):
+
+	// Correct:
+	$foo = 'bar';
+	$long_example = 'uses underscores';
+
+	// Incorrect:
+	$weDontWantThis = 'understood?';
+
+### Einr<6E>ckung
+
+Du musst zur Einr<6E>ckung deines Quelltextes Tabulatoren benutzen. Leerzeichen f<>r Tabellarisierung zu verwenden, ist strengstens verboten.
+
+Vertikaler Abstand (bei Mehrzeiligkeit) wird mit Leerzeichen gemacht. Tabulatoren sind schlecht f<>r die vertikale Ausrichtung, weil verschiedene Leute unterschiedliche Tabulatoren-Breiten haben.
+
+	$text = 'this is a long text block that is wrapped. Normally, we aim for '
+		  . 'wrapping at 80 chars. Vertical alignment is very important for '
+		  . 'code readability. Remember that all indentation is done with tabs,'
+		  . 'but vertical alignment should be completed with spaces, after '
+		  . 'indenting with tabs.';
+
+### Zeichenkettenverkn<6B>pfung
+
+Setze keine Leerzeichen um den Verkn<6B>pfungsoperator:
+
+	// Correct:
+	$str = 'one'.$var.'two';
+
+	// Incorrect:
+	$str = 'one'. $var .'two';
+	$str = 'one' . $var . 'two';
+
+### Einzeilige Ausdr<64>cke
+
+Einzeilige IF-Bedingungen sollten nur bei Anweisungen benutzt werden, die die normale Verarbeitung unterbrechen (z.B. return oder continue):
+
+	// Acceptable:
+	if ($foo == $bar)
+		return $foo;
+
+	if ($foo == $bar)
+		continue;
+
+	if ($foo == $bar)
+		break;
+
+	if ($foo == $bar)
+		throw new Exception('You screwed up!');
+
+	// Not acceptable:
+	if ($baz == $bun)
+		$baz = $bar + 2;
+
+### Vergleichsoperatoren
+
+Bitte benutze OR and AND:
+
+	// Correct:
+	if (($foo AND $bar) OR ($b AND $c))
+
+	// Incorrect:
+	if (($foo && $bar) || ($b && $c))
+	
+Bitte benutze elseif, nicht else if:
+
+	// Correct:
+	elseif ($bar)
+
+	// Incorrect:
+	else if($bar)
+
+### Switch structures
+
+Each case, break and default should be on a separate line. The block inside a case or default must be indented by 1 tab.
+
+	switch ($var)
+	{
+		case 'bar':
+		case 'foo':
+			echo 'hello';
+		break;
+		case 1:
+			echo 'one';
+		break;
+		default:
+			echo 'bye';
+		break;
+	}
+
+### Parentheses
+
+There should be one space after statement name, followed by a parenthesis. The ! (bang) character must have a space on either side to ensure maximum readability. Except in the case of a bang or type casting, there should be no whitespace after an opening parenthesis or before a closing parenthesis.
+
+	// Correct:
+	if ($foo == $bar)
+	if ( ! $foo)
+
+	// Incorrect:
+	if($foo == $bar)
+	if(!$foo)
+	if ((int) $foo)
+	if ( $foo == $bar )
+	if (! $foo)
+
+### Ternaries
+
+All ternary operations should follow a standard format. Use parentheses around expressions only, not around just variables.
+
+	$foo = ($bar == $foo) ? $foo : $bar;
+	$foo = $bar ? $foo : $bar;
+
+All comparisons and operations must be done inside of a parentheses group:
+
+	$foo = ($bar > 5) ? ($bar + $foo) : strlen($bar);
+
+When separating complex ternaries (ternaries where the first part goes beyond ~80 chars) into multiple lines, spaces should be used to line up operators, which should be at the front of the successive lines:
+
+	$foo = ($bar == $foo)
+		 ? $foo
+		 : $bar;
+
+### Type Casting
+
+Type casting should be done with spaces on each side of the cast:
+
+	// Correct:
+	$foo = (string) $bar;
+	if ( (string) $bar)
+
+	// Incorrect:
+	$foo = (string)$bar;
+
+When possible, please use type casting instead of ternary operations:
+
+	// Correct:
+	$foo = (bool) $bar;
+
+	// Incorrect:
+	$foo = ($bar == TRUE) ? TRUE : FALSE;
+
+When casting type to integer or boolean, use the short format:
+
+	// Correct:
+	$foo = (int) $bar;
+	$foo = (bool) $bar;
+
+	// Incorrect:
+	$foo = (integer) $bar;
+	$foo = (boolean) $bar;
+
+### Constants
+
+Always use uppercase for constants:
+
+	// Correct:
+	define('MY_CONSTANT', 'my_value');
+	$a = TRUE;
+	$b = NULL;
+
+	// Incorrect:
+	define('MyConstant', 'my_value');
+	$a = True;
+	$b = null;
+
+Place constant comparisons at the end of tests:
+
+	// Correct:
+	if ($foo !== FALSE)
+
+	// Incorrect:
+	if (FALSE !== $foo)
+
+This is a slightly controversial choice, so I will explain the reasoning. If we were to write the previous example in plain English, the correct example would read:
+
+	if variable $foo is not exactly FALSE
+
+And the incorrect example would read:
+
+	if FALSE is not exactly variable $foo
+
+Since we are reading left to right, it simply doesn't make sense to put the constant first.
+
+### Comments
+
+#### One-line comments
+
+Use //, preferably above the line of code you're commenting on. Leave a space after it and start with a capital. Never use #.
+
+	// Correct
+
+	//Incorrect
+	// incorrect
+	# Incorrect
+
+### Regular expressions
+
+When coding regular expressions please use PCRE rather than the POSIX flavor. PCRE is considered more powerful and faster.
+
+	// Correct:
+	if (preg_match('/abc/i'), $str)
+
+	// Incorrect:
+	if (eregi('abc', $str))
+
+Use single quotes around your regular expressions rather than double quotes. Single-quoted strings are more convenient because of their simplicity. Unlike double-quoted strings they don't support variable interpolation nor integrated backslash sequences like \n or \t, etc.
+
+	// Correct:
+	preg_match('/abc/', $str);
+
+	// Incorrect:
+	preg_match("/abc/", $str);
+
+When performing a regular expression search and replace, please use the $n notation for backreferences. This is preferred over \\n.
+
+	// Correct:
+	preg_replace('/(\d+) dollar/', '$1 euro', $str);
+
+	// Incorrect:
+	preg_replace('/(\d+) dollar/', '\\1 euro', $str);
+
+Finally, please note that the $ character for matching the position at the end of the line allows for a following newline character. Use the D modifier to fix this if needed. [More info](http://blog.php-security.org/archives/76-Holes-in-most-preg_match-filters.html).
+
+	$str = "email@example.com\n";
+
+	preg_match('/^.+@.+$/', $str);  // TRUE
+	preg_match('/^.+@.+$/D', $str); // FALSE

modules/userguide/guide/de-de/about.kohana.md

@@ -0,0 +1,15 @@
+# Was ist Kohana?
+
+Kohana ist ein Open-Source-basiertes, [objektorientiertes](http://de.wikipedia.org/wiki/Objektorientierte_Programmierung) [MVC](http://de.wikipedia.org/wiki/Model_View_Controller "Model View Controller")-[Webframework](http://de.wikipedia.org/wiki/Web_Application_Framework) unter Verwendung von [PHP5](http://php.net/manual/de/intro-whatis "PHP Hypertext Preprocessor"). Es wird von Freiwilligen entwickelt, das darauf abzielt schnell, sicher und schlank zu sein.
+
+[!!] Kohana ist unter der [BSD-Lizenz](http://kohanaframework.org/license) ver<65>ffentlicht, so dass man es rechtlich f<>r alle Arten von Open-Source-, kommerzieller oder privater Projekte nutzen kann.
+
+## Was macht Kohana besonders?
+
+Durch den einzigartigen [Dateisystem](about.filesystem)-Aufbau ist alles erweiterbar und man braucht wenige oder keine [Einstellungen](about.configuration) vornehmen. Die [Fehlerbehandlung](debugging.errors) hilft, die Fehlerquelle schnell zu finden, und die [Fehlersuche](debugging) und [Programmanalyse](debugging.profiling) erm<72>glichen einen Einblick in die Anwendung.
+
+Um die Sicherheit deiner Anwendung zu unterst<73>tzen, enth<74>lt Kohana Werkzeuge f<>r [XSS-Entfernung](security.xss), [Eingabe-<2D>berpr<70>fung](security.validation), [signierte Cookies](security.cookies), [Formular](security.forms)- und [HTML](security.html)-Erstellung. Die [Datenbank](security.database)-Schicht bietet Schutz vor [SQL-Injection](http://de.wikipedia.org/wiki/SQL-Injection). Nat<61>rlich wurde der gesamte offizielle Quelltext sorgf<67>ltig geschrieben und auf Sicherheit gepr<70>ft.
+
+## Diese Dokumentation ist schei<65>e!
+
+Wir bem<65>hen uns um eine vollst<73>ndige Dokumentation. Wenn eine Frage trotzdem offen bleibt, versuche es beim [inoffiziellen Wiki](http://kerkness.ca/wiki/doku.php). Wenn du etwas zum Handbuch beitragen oder <20>ndern willst, erstelle bitte [eine Kopie](http://github.com/kohana/userguide), bearbeite sie und stelle eine Anfrage zur Zusammenf<6E>hrung. Falls du nicht mit git vertraut bist, kannst du auch ein [Feature-Vorschlag](http://dev.kohanaframework.org/projects/kohana3/issues) (Anmeldung erforderlich) machen.

modules/userguide/guide/developers.md

@@ -0,0 +1,150 @@
+# Distributed Source Control Management
+
+Unlike SVN, git does not used a central repository. This is why git is "distributed" and SVN is
+"centralized". Although this makes git an extremely powerful system for collaborators, tracking
+changes between various collaborators can quickly become difficult as multiple forks are created.
+
+Please read the following before working with this code:
+
+1. [Dealing with newlines](http://github.com/guides/dealing-with-newlines-in-git)
+2. [Submitting changes from your fork](http://github.com/guides/fork-a-project-and-submit-your-modifications)
+3. [Using SSH keys with github](http://github.com/guides/how-to-not-have-to-type-your-password-for-every-push)
+
+## Managing Remote Repositories
+
+First, you will need to tell git about the remote repository:
+
+    > git remote add kohana git://github.com/kohana/kohana.git
+
+This tells git about the kohana repository and gives it a name which we can use to refer to it when
+fetching changes from the repository.
+
+## Developing locally
+
+There are 3 branches in all the kohana repositories:
+
+* **master** This branch always points to the latest release tag. In essence it points to the last stable edition of the codebase
+* **3.0.x**  This is a release branch for development of the 3.0.x series, i.e. 3.0, 3.0.3, 3.0.8 etc.
+* **3.1.x**  This is a release branch for development of the 3.1.x series, i.e. 3.1, 3.1.4, 3.1.14 etc.
+
+To work on a specific release branch you need to check it out then check out the appropriate branches.
+Release branch names follow the same convention in both kohana/kohana and kohana/core.
+
+To work on 3.0.x you'd do the following:
+
+	> git clone git://github.com/kohana/kohana.git
+	....
+	
+	> cd kohana
+	> git submodule update --init
+	....
+
+	> git checkout 3.0.x
+	Switched to branch '3.0.x'
+	> git submodule update 
+
+	> cd system
+	> git checkout 3.0.x
+	# Switched to branch 3.0.x
+
+It's important that you follow the last step, because unlike svn, git submodules point at a
+specific commit rather than the tip of a branch.  If you cd into the system folder after
+a `git submodule update` and run `git status` you'll be told:
+
+	# Not currently on any branch.
+	nothing to commit (working directory clean)
+
+Similarly, if you want to work on modules, make sure you checkout the correct branch before you start working.
+
+**IMPORTANT:** It is highly recommended that you run the unit tests whilst developing to
+ensure that any changes you make do not break the api. *See TESTING.md for more info*
+
+### Creating new features
+
+New features or API breaking modifications should be developed in separate branches so as to isolate them
+until they're stable and **tests have been written for the feature**.
+
+The naming convention for feature branches is:
+
+	feature/{issue number}-{short hyphenated description}
+	
+	// i.e.
+
+	feature/4045-rewriting-config-system
+	
+When a new feature is complete and tested it can be merged into its respective release branch using
+`git pull --no-ff`. The `--no-ff` switch is important as it tells git to always create a commit
+detailing what branch you're merging from. This makes it a lot easier to analyse a feature's history.
+
+Here's a quick example:
+
+	> git status
+	# On branch feature/4045-rewriting-everything
+	
+	> git checkout 3.1.x
+	# Switched to branch '3.1.x'
+
+	> git merge --no-ff feature/4045-rewriting-everything
+
+**If a change you make intentionally breaks the api then please correct the relevant tests before pushing!**
+
+### Bug fixing 
+
+If you're making a bugfix then before you start create a unit test which reproduces the bug,
+using the `@ticket` notation in the test to reference the bug's issue number
+(i.e. `@ticket 4045` for issue #4045). 
+
+If you run the test then the one you've just made should fail.
+
+Once you've written the bugfix, run the tests again before you commit to make sure that the
+fix actually works,then commiti both the fix and the test.
+
+There is no need to create separate branches for bugfixes, creating them in the main release
+branch is perfectly acceptable.
+
+## Merging Changes from Remote Repositories
+
+Now that you have a remote repository, you can pull changes in the remote "kohana" repository
+into your local repository:
+
+    > git pull kohana master
+
+**Note:** Before you pull changes you should make sure that any modifications you've made locally
+have been committed.
+
+Sometimes a commit you've made locally will conflict with one made in the "kohana" one.
+
+There are a couple of scenarios where this might happen:
+
+### The conflict is to do with a few unrelated commits and you want to keep changes made in both commits
+
+You'll need to manually modify the files to resolve the conflict, see the "Resolving a merge"
+section [in the git-scm book](http://book.git-scm.com/3_basic_branching_and_merging.html) for more info
+
+### You've fixed something locally which someone else has already done in the remote repo
+
+The simplest way to fix this is to remove all the changes that you've made locally.
+
+You can do this using 
+
+    > git reset --hard kohana
+
+### You've fixed something locally which someone else has already fixed but you also have separate commits you'd like to keep
+
+If this is the case then you'll want to use a tool called rebase.  First of all we need to
+get rid of the conflicts created due to the merge:
+
+    > git reset --hard HEAD
+
+Then find the hash of the offending local commit and run:
+
+    > git rebase -i {offending commit hash}
+
+i.e.
+
+	> git rebase -i 57d0b28
+
+A text editor will open with a list of commits, delete the line containing the offending commit
+before saving the file & closing your editor.
+
+Git will remove the commit and you can then pull/merge the remote changes.

modules/userguide/guide/userguide/adding.md

@@ -0,0 +1,55 @@
+# Adding your module to the userguide
+
+Making your module work with the userguide is simple.
+
+First, copy this config and place in it `<module>/config/userguide.php`, replacing anything in `<>` with the appropriate things:
+
+	return array
+	(
+		// Leave this alone
+		'modules' => array(
+	
+			// This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename'
+			'<modulename>' => array(
+	
+				// Whether this modules userguide pages should be shown
+				'enabled' => TRUE,
+				
+				// The name that should show up on the userguide index page
+				'name' => '<Module Name>',
+	
+				// A short description of this module, shown on the index page
+				'description' => '<Description goes here.>',
+				
+				// Copyright message, shown in the footer for this module
+				'copyright' => '&copy; 2010–2011 <Your Name>',
+			)	
+		),
+
+		/*
+		 * If you use transparent extension outside the Kohana_ namespace,
+		 * add your class prefix here. Both common Kohana naming conventions are
+		 * excluded: 
+		 *   - Modulename extends Modulename_Core
+		 *   - Foo extends Modulename_Foo
+		 * 
+		 * For example, if you use Modulename_<class_name> for your base classes
+		 * then you would define:
+		 */
+		'transparent_prefixes' => array(
+			'Modulename' => TRUE,
+		)
+	);
+
+Next, create a folder in your module directory called `guide/<modulename>` and create `index.md` and `menu.md`.  All userguide pages use [Markdown](markdown).  The index page is what is shown on the index of your module, the menu is what shows up in the side column.  The menu should be formatted like this:
+
+	## [Module Name]()
+	 - [Page name](page-path)
+	 - [This is a Category](category)
+		 - [Sub Page](category/sub-page)
+		 - [Another](category/another)
+			 - [Sub sub page](category/another/sub-page)
+	 - Categories do not have to be a link to a page
+		 - [Etcetera](etc)
+
+Page paths are relative to `guide/<modulename>`.  So `[Page name](path-path)` would look for `guide/<modulename>/page-name.md` and `[Another](category/another)` would look for `guide/<modulename>/page-name.md`.   The guide pages can be named or arranged any way you want within that folder (with the exception of `menu.md` and `index.md`). The breadcrumbs and page titles are pulled from the `menu.md file`, not the file names or paths.  You can have items that are not pages (a category that doesn't have a corresponding page).  To link to the `index.md` page, you should have an empty link, e.g. `[Module Name]()`.  Do not include `.md` in your links.  

modules/userguide/guide/userguide/config.md

@@ -0,0 +1,35 @@
+# Configuration
+
+The userguide has the following config options, available in `config/userguide.php`.
+
+	return array
+	(
+		// Enable the API browser.  TRUE or FALSE
+		'api_browser'  => TRUE,
+
+		// Enable these packages in the API browser.  TRUE for all packages, or a string of comma seperated packages, using 'None' for a class with no @package
+		// Example: 'api_packages' => 'Kohana,Kohana/Database,Kohana/ORM,None',
+		'api_packages' => TRUE,
+
+	);
+
+You can enable or disable the entire API browser, or limit it to only show certain packages.  To disable a module from showing pages in the userguide, simply change that module's `enabled` option using the cascading filesystem.  For example:
+
+	`application/config/userguide.php`
+
+	return array
+	(
+		'modules' => array
+		(
+			'kohana' => array
+			(
+				'enabled' => FALSE,
+			),
+			'database' => array
+			(
+				'enabled' => FALSE,
+			)
+		)
+	)
+
+Using this you could make the userguide only show your modules and classes in the API browser, if you wanted to host your own documentation on your site.  Feel free to change the styles and views as well, but be sure to give credit where credit is due!

modules/userguide/guide/userguide/contributing.md

@@ -0,0 +1,75 @@
+# Contributing
+
+Kohana is community driven, and we rely on community contributions for the documentation.
+
+## Guidelines
+
+Documentation should use complete sentences, good grammar, and be as clear as possible.  Use lots of example code, but make sure the examples follow the Kohana conventions and style.
+
+Try to commit often, with each commit only changing a file or two, rather than changing a ton of files and commiting it all at once.  This will make it easier to offer feedback and merge your changes.   Make sure your commit messages are clear and descriptive.  Bad: "Added docs",  Good: "Added initial draft of hello world tutorial",  Bad: "Fixed typos",  Good: "Fixed typos on the query builder page"
+
+If you feel a menu needs to be rearranged or a module needs new pages, please open a [bug report](http://dev.kohanaframework.org/projects/userguide3/issues/new) to discuss it.
+
+## Quick Method
+
+To quickly point out something that needs improvement, report a [bug report](http://dev.kohanaframework.org/projects/userguide3/issues/new).
+
+If you want to contribute some changes, you can do so right from your browser without even knowing git!
+
+First create an account on [GitHub](https://github.com/signup/free).
+
+You will need to fork the module for the area you want to improve.  For example, to improve the [ORM documentation](../orm) fork <http://github.com/kohana/orm>.  To improve the [Kohana documentation](../kohana), fork <http://github.com/kohana/core>, etc.  So, find the module you want to improve and click on the Fork button in the top right.
+
+![Fork the module](contrib-github-fork.png)
+
+The files that make the User Guide portion are found in `guide/<module>/`, and the API browser portion is made from the comments in the source code itself.  Navigate to one of the files you want to change and click the edit button in the top right of the file viewer.
+
+![Click on edit to edit the file](contrib-github-edit.png)
+
+Make the changes and add a **detailed commit message**.  Repeat this for as many files as you want to improve. (Note that you can't preview what the changes will look unless you actually test it locally.)
+
+After you have made your changes, send a pull request so your improvements can be reviewed to be merged into the official documentation.
+
+![Send a pull request](contrib-github-pull.png)
+
+Once your pull request has been accepted, you can delete your repository if you want.  Your commit will have been copied to the official branch.
+
+## If you know Git
+
+### Short version
+
+Fork the module whose docs you wish to improve (e.g. `git://github.com/kohana/orm.git` or `git://github.com/kohana/core.git`), checkout the `3.2/develop` branch (for the 3.2 docs), make changes, and then send a pull request.
+
+### Long version
+
+(This still assumes you at least know your way around Git, especially how submodules work.)
+
+ 1. Fork the specific repo you want to contribute to on GitHub. (For example, go to http://github.com/kohana/core and click the fork button.)
+
+ 1. Now you need to add your fork as a "git remote" to your application and ensure you are on the right branch. An example for the [ORM](../orm) module and 3.2 docs:
+
+		cd my-kohana-app/modules/orm
+
+		# add your repository as a new remote
+		git remote add <your name> git://github.com/<your name>/orm.git
+
+		# Get the correct branch
+		git checkout 3.2/develop
+
+ 1. Now go into the repo of the area of docs you want to contribute to and add your forked repo as a new remote, and push to it.
+
+		cd my-kohana-app/modules/orm
+
+		# Make some changes to the docs
+		nano file.md
+
+		# Commit your changes - Use a descriptive commit message! If there is a redmine ticket for the changes you are making include "Fixes #XXXXX" in the commit message so its tracked.
+		git commit -a -m "Corrected a typo in the ORM docs. Fixes #12345."
+
+		# make sure we are up to date with the latest changes
+		git merge origin/3.2/develop
+
+		# Now push your changes to your fork.
+		git push <your name> 3.2/develop
+
+ 1. Finally, send a pull request on GitHub.

modules/userguide/guide/userguide/index.md

@@ -0,0 +1,3 @@
+# Userguide
+
+The userguide module provides documentation viewing including browsing the source code comments.

modules/userguide/guide/userguide/markdown.md

@@ -0,0 +1,237 @@
+# Markdown Syntax
+
+The userguide uses [Markdown](http://daringfireball.net/projects/markdown/) and [Markdown Extra](http://michelf.com/projects/php-markdown/extra/) for the userguide pages, and the in-code comments used to generate the API browser.  This is a brief summary of most of Markdown and Markdown extra features.  It does not cover everything, and it does not cover all the caveats.
+
+[!!] Be sure to check out the **[Userguide Specific Syntax](#userguide-specific-syntax)** for things that Userguide adds to markdown.
+
+## Headers
+
+    # Header 1
+	
+	## Header 2
+	
+	### Header 3
+	
+	#### Header 4
+
+## Paragraphs
+~~~
+Regular text will be transformed into paragraphs.
+Single returns will not make a new paragraph, this
+allows for wrapping (especially for in-code
+comments).
+
+A new paragraph will start if there is a blank line between
+blocks of text.  Chars like > and & are escaped for you.
+
+To make a line break,  
+put two spaces at the  
+end of a line.
+~~~
+Regular text will be transformed into paragraphs.
+Single returns will not make a new paragraph, this
+allows for wrapping (especially for in-code
+comments).
+
+A new paragraph will start if there is a blank line between
+blocks of text.  Chars like > and & are escaped for you.
+
+To make a line break,  
+put two spaces at the  
+end of a line.
+
+## Links
+~~~
+This is a normal link: [Kohana](http://kohanaframework.org).
+
+This link has a title: [Kohana](http://kohanaframework.org "The swift PHP framework")
+~~~
+This is a normal link: [Kohana](http://kohanaframework.org)
+
+This link has a title: [Kohana](http://kohanaframework.org "The swift PHP framework")
+
+## Code blocks
+
+	For inline code simply surround some `text with tick marks.`
+	
+For inline code simply surround some `text with tick marks.`
+
+	// For a block of code,
+	// indent in four spaces,
+	// or with a tab
+
+You can also do a "fenced" code block:
+
+	~~~
+	A fenced code block has tildes
+	          above and below it
+	This is sometimes useful when code is near lists
+	~~~
+~~~
+A fenced code block has tildes
+		  above and below it
+This is sometimes useful when code is near lists
+~~~
+
+## Unordered Lists
+
+~~~
+*  To make a unordered list, put an asterisk, minus, or + at the beginning
+-  of each line, surrounded by spaces.  You can mix * - and +, but it
++  makes no difference.
+~~~
+*  To make a unordered list, put an asterisk, minus, or + at the beginning
+-  of each line, surrounded by spaces.  You can mix * - and +, but it
++  makes no difference.
+
+## Ordered Lists
+
+~~~
+1.  For ordered lists, put a number and a period
+2.  On each line that you want numbered.
+9.  It doesn't actually have to be the correct number order
+5.  Just as long as each line has a number
+~~~
+1.  For ordered lists, put a number and a period
+2.  On each line that you want numbered.
+9.  It doesn't actually have to be the correct number order
+5.  Just as long as each line has a number
+
+## Nested Lists
+
+~~~
+*  To nest lists you just add four spaces before the * or number
+	1. Like this
+		*  It's pretty basic, this line has eight spaces, so its nested twice
+	1. And this line is back to the second level
+		*  Out to third level again
+*  And back to the first level
+~~~
+*  To nest lists you just add four spaces before the * or number
+	1. Like this
+		*  It's pretty basic, this line has eight spaces, so its nested twice
+	1. And this line is back to the second level
+		*  Out to third level again
+*  And back to the first level
+
+## Italics and Bold
+
+~~~
+Surround text you want *italics* with *asterisks* or _underscores_.
+
+**Double asterisks** or __double underscores__ makes text bold.
+
+***Triple*** will do *both at the same **time***.
+~~~
+Surround text you want *italics* with *asterisks* or _underscores_.
+
+**Double asterisks** or __double underscores__ makes text **bold**.
+
+___Triple___ will do *both at the same **time***.
+
+## Horizontal Rules
+
+Horizontal rules are made by placing 3 or more hyphens, asterisks, or underscores on a line by themselves.
+~~~
+---
+* * * *
+_____________________
+~~~
+---
+* * * *
+_____________________
+
+## Images
+
+Image syntax looks like this:
+
+	![Alt text](/path/to/img.jpg)
+	
+	![Alt text](/path/to/img.jpg "Optional title")
+
+[!!] Note that the images in userguide are [namespaced](#namespacing).
+
+## Tables
+~~~
+First Header  | Second Header
+------------- | -------------
+Content Cell  | Content Cell
+Content Cell  | Content Cell
+~~~
+
+First Header  | Second Header
+------------- | -------------
+Content Cell  | Content Cell
+Content Cell  | Content Cell
+
+Note that the pipes on the very left and very right side are optional, and you can change the text-alignment by adding a colon on the right, or on both sides for center.
+~~~
+| Item      | Value | Savings |
+| --------- | -----:|:-------:|
+| Computer  | $1600 |   40%   |
+| Phone     |   $12 |   30%   |
+| Pipe      |    $1 |    0%   |
+~~~
+| Item      | Value | Savings |
+| --------- | -----:|:-------:|
+| Computer  | $1600 |   40%   |
+| Phone     |   $12 |   30%   |
+| Pipe      |    $1 |    0%   |
+
+# Userguide Specific Syntax
+
+In addition to the features and syntax of [Markdown](http://daringfireball.net/projects/markdown/) and [Markdown Extra](http://michelf.com/projects/php-markdown/extra/) the following apply to userguide pages and api documentation:
+
+## Namespacing
+
+The first thing to note is that all links are "namespaced" to the current module.  For example, from anywhere within the Kohana core docs you do not need to include `kohana` at the beginning of a link url.  For example: `[Hello World Tutorial](tutorials/hello-world)` rather than `(kohana/tutorials/hello-world)`.
+
+To link to a modules index page, have an empty url like: `[Kohana]()`.
+
+To link to page in a different module, prefix your url with `../` and the module name.  For example: `[Kohana Routes](../kohana/routing)`
+
+**Images are also namespaced**, using `![Alt Text](imagename.jpg)` would look for `media/guide/<modulename>/imagename.jpg`.
+
+[!!] If you want your userguide pages to be browsable on github or similar sites outside Kohana's own userguide module, specify the optional .md file extension in your links
+
+## API Links
+
+You can make links to the api browser by wrapping any class name in brackets.  You may also include a function name, or propery name to link to that specifically.  All of the following will link to the API browser:
+
+	[Request]  
+	[Request::execute]  
+	[Request::execute()]  
+	[Request::$status]  
+
+[Request]  
+[Request::execute]  
+[Request::execute()]  
+[Request::$status]  
+
+If you want to have parameters and have the function be clickable, only put the brackets around the class and function (not the params), and put a backslash in front of the opening parenthesis.
+
+	[Kohana::$config]\('foobar','baz')
+	
+[Kohana::$config]\('foobar','baz')
+
+## Notes
+
+If you put `[!!]` in front of a line it will be a "note" and be placed in a box with a lightbulb.
+
+	[!!]  This is a note
+
+will display as:
+	
+[!!] This is a note
+
+## Headers automatically get IDs
+
+Headers are automatically assigned an id, based on the content of the header, so each header can be linked to. You can manually assign a different id using the syntax as defined in Markdown Extra. If multiple headers have the same content (e.g. more than one "Examples" header), only the first will get be automatically assigned an id, so you should manually assign more descriptive ids. For example:
+
+	### Examples     {#more-descriptive-id}
+
+## Including Views
+
+If you need you may include a regular Kohana View file by placing the name of the view in double curly brackets.  **If the view is not found, no error or exception will be shown, the curly brackets and view name will simply remain there!**
+
+	{{some/view/file}}

modules/userguide/guide/userguide/menu.md

@@ -0,0 +1,7 @@
+## [Userguide]()
+ - [Using the Userguide](using)
+ - [How userguide works](works)
+ - [Contributing](contributing)
+ - [Markdown Syntax](markdown)
+ - [Configuration](config)
+ - [Adding your module](adding)

modules/userguide/guide/userguide/using.md

@@ -0,0 +1 @@
+Give tips on how to most effectively use the user guide.  How to navigate around, how things are organized, etc. 

modules/userguide/guide/userguide/works.md

@@ -0,0 +1,25 @@
+# How the Userguide works
+
+The userguide uses [Markdown](markdown) for the documentation.  Both the userguide pages, and the in code comments for the API browser are written in markdown.
+
+## Userguide pages
+
+Userguide pages are in the module they apply to, in `guide/<module>`. For example, documentation for Kohana is in `system/guide/kohana` and documentation for orm is in `modules/orm/guide/orm`, database is in `modules/database/guide/database`, etc.
+
+Each module has an index page at `guide/<module>/index.md`.
+
+Each module's menu is at `guide/<module>/menu.md`.
+
+All other pages are are in `guide/<module>` and can be organized in subfolders and named however you want.
+
+For more info on how to make your module have userguide pages, see [Adding your module](adding).
+
+### Images
+
+Any images used in the userguide pages must be in `media/guide/<module>/`.  For example, if a page has `![Image Title](hello-world.jpg)` the image would be located at `media/guide/<module>/hello-world.jpg`.  Images for the ORM module are in `modules/orm/media/guide/orm`, and images for the Kohana docs are in `system/media/guide/kohana`.
+
+### API browser
+
+The API browser is generated from the actual source code.  The descriptions for classes, constants, properties, and methods is extracted from the comments and parsed in Markdown.  For example if you look in the comment for [Kohana_Core::init](http://github.com/kohana/core/blob/c443c44922ef13421f4a/classes/kohana/core.php#L5) you can see a markdown list and table.  These are parsed and show correctly in the API browser.  `@param`, `@uses`, `@throws`, `@returns` and other tags are parsed as well.
+
+TODO: give more specific details on how to comment your classes, constants, methods, etc. including package and how it relates to the api module.