Merge commit 'bonsaiden/master'

Conflicts:
	server.js
	site/pl/index.html

Author: smith

build.js

@@ -164,10 +164,10 @@ var Garden = Class(function(options) {
                 top: lang.navigation[0]
             };
 
-            jade.renderFile(template, {locals: options}, function(err, html){
-                if (err) throw err;
-                fs.writeFileSync(out, html);
-            });
+            var jadefile = fs.readFileSync(template);
+            var jadetemplate = jade.compile (jadefile);
+            var html = jadetemplate(options);
+            fs.writeFileSync(out, html);
             this.log('    Done.');
         }
     },

doc/en/array/constructor.md

@@ -11,10 +11,10 @@ when creating new arrays.
     new Array(3); // Result: []
     new Array('3') // Result: ['3']
 
-In cases when there is only one argument passed to the `Array` constructor,
-and that argument is a `Number`, the constructor will return a new *sparse* 
+In cases when there is only one argument passed to the `Array` constructor
+and when that argument is a `Number`, the constructor will return a new *sparse* 
 array with the `length` property set to the value of the argument. It should be 
-noted that **only** the `length` property of the new array will be set this way, 
+noted that **only** the `length` property of the new array will be set this way; 
 the actual indexes of the array will not be initialized. 
 
     var arr = new Array(3);

doc/en/array/general.md

@@ -1,15 +1,15 @@
 ## Array Iteration and Properties
 
 Although arrays in JavaScript are objects, there are no good reasons to use
-the [`for in loop`](#object.forinloop) in for iteration on them. In fact there 
+the [`for in loop`](#object.forinloop) in for iteration on them. In fact, there 
 are a number of good reasons **against** the use of `for in` on arrays.
 
 > **Note:** JavaScript arrays are **not** *associative arrays*. JavaScript only 
 > has [objects](#object.general) for mapping keys to values. And while associative 
 > arrays **preserve** order, objects **do not**.
 
-Since the `for in` loop enumerates all the properties that are on the prototype 
-chain and the only way to exclude those properties is to use 
+Because the `for in` loop enumerates all the properties that are on the prototype 
+chain and because the only way to exclude those properties is to use 
 [`hasOwnProperty`](#object.hasownproperty), it is already up to **twenty times** 
 slower than a normal `for` loop.
 
@@ -23,7 +23,7 @@ to use the classic `for` loop.
         console.log(list[i]);
     }
 
-There is one extra catch in the above example, that is the caching of the 
+There is one extra catch in the above example, which is the caching of the 
 length of the array via `l = list.length`.
 
 Although the `length` property is defined on the array itself, there is still an
@@ -52,7 +52,7 @@ does not have any effect on the array.
 
 ### In Conclusion
 
-For the best performance it is recommended to always use the plain `for` loop
+For the best performance, it is recommended to always use the plain `for` loop
 and cache the `length` property. The use of `for in` on an array is a sign of
 badly written code that is prone to bugs and bad performance. 
 

doc/en/core/delete.md

@@ -0,0 +1,87 @@
+## The `delete` Operator
+
+In short, it's *impossible* to delete global variables, functions and some other
+stuff in JavaScript which have a `DontDelete` attribute set.
+
+### Global code and Function code
+
+When a variable or a function is defined in a global 
+or a [function scope](#function.scopes) it is a property of either 
+Activation object or Global object. Such properties have a set of attributes, 
+one of these is `DontDelete`. Variable and function declarations in global 
+and function code always create properties with `DontDelete`, therefore 
+cannot be deleted.
+
+    // global variable:
+    var a = 1; // DontDelete is set
+    delete a; // false
+    a; // 1
+
+    // normal function:
+    function f() {} // DontDelete is set
+    delete f; // false
+    typeof f; // "function"
+
+    // reassigning doesn't help:
+    f = 1;
+    delete f; // false
+    f; // 1
+
+### Explicit properties
+
+There are things which can be deleted normally: these are explicitly set 
+properties.
+
+    // explicitly set property:
+    var obj = {x: 1};
+    obj.y = 2;
+    delete obj.x; // true
+    delete obj.y; // true
+    obj.x; // undefined
+    obj.y; // undefined
+
+In the example above `obj.x` and `obj.y` can be deleted because they have no 
+`DontDelete` atribute. That's why an example below works too.
+
+    // this works fine, except for IE:
+    var GLOBAL_OBJECT = this;
+    GLOBAL_OBJECT.a = 1;
+    a === GLOBAL_OBJECT.a; // true - just a global var
+    delete GLOBAL_OBJECT.a; // true
+    GLOBAL_OBJECT.a; // undefined
+
+Here we use a trick to delete `a`. [`this`](#function.this) here refers 
+to the Global object and we explicitly declare variable `a` as it's property 
+which allows us to delete it.
+
+IE (at least 6-8) has some bugs, so code above doesn't work.
+
+### Function arguments and built-ins
+
+Functions' normal arguments, [`arguments` object](#function.arguments) 
+and built-in properties also have `DontDelete` set.
+
+    // function arguments and properties:
+    (function (x) {
+    
+      delete arguments; // false
+      typeof arguments; // "object"
+      
+      delete x; // false
+      x; // 1
+      
+      function f(){}
+      delete f.length; // false
+      typeof f.length; // "number"
+      
+    })(1);
+
+### Host objects
+    
+Behaviour of `delete` operator can be unpredictable for hosted objects. Due to 
+specification, host objects are allowed to implement any kind of behavior. 
+
+### In conclusion
+
+`delete` operator often has an unexpected behaviour and can be safely used 
+only for dealing with explicitly set properties on normal objects.

doc/en/core/eval.md

@@ -11,8 +11,8 @@ The `eval` function will execute a string of JavaScript code in the local scope.
     test(); // 3
     foo; // 1
 
-But `eval` only executes in local scope when it is being called **directly** *and* 
-the name of the called function is actually `eval`.
+However, `eval` only executes in the local scope when it is being called
+**directly** *and* when the name of the called function is actually `eval`.
 
     var foo = 1;
     function test() {
@@ -35,14 +35,13 @@ in the global scope since `eval` is not being called directly in that case.
 
 ### Security Issues
 
-`eval` also is a security problem as it executes **any** code given to it,
+`eval` also is a security problem. Because it executes **any** code given to it,
 it should **never** be used with strings of unknown or untrusted origins.
 
 ### In Conclusion
 
-`eval` should never be used, any code that makes use of it is to be questioned in
+`eval` should never be used. Any code that makes use of it is to be questioned in
 its workings, performance and security. In case something requires `eval` in 
-order to work, its design is to be questioned and should **not** be used in the 
-first place, a *better design* should be used, that does not require the use of 
-`eval`. 
+order to work, it should **not** be used in the first place.
+A *better design* should be used, that does not require the use of `eval`.
 

doc/en/core/semicolon.md

@@ -1,10 +1,10 @@
 ## Automatic Semicolon Insertion
 
 Although JavaScript has C style syntax, it does **not** enforce the use of
-semicolons in the source code, it is possible to omit them.
+semicolons in the source code, so it is possible to omit them.
 
-But JavaScript is not a semicolon-less language, it in fact needs the 
-semicolons in order to understand the source code. Therefore the JavaScript
+JavaScript is not a semicolon-less language. In fact, it needs the 
+semicolons in order to understand the source code. Therefore, the JavaScript
 parser **automatically** inserts them whenever it encounters a parse
 error due to a missing semicolon.
 
@@ -19,7 +19,7 @@ Insertion happens, and the parser tries again.
     test()
 
 The automatic insertion of semicolon is considered to be one of **biggest**
-design flaws in the language, as it *can* change the behavior of code.
+design flaws in the language because it *can* change the behavior of code.
 
 ### How it Works
 
@@ -87,7 +87,7 @@ Below is the result of the parser's "guessing" game.
 > which are followed by a new line, while this is not neccessarily the fault of 
 > the automatic semicolon insertion, it can still be an unwanted side-effect. 
 
-The parser drastically changed the behavior of the code above, in certain cases
+The parser drastically changed the behavior of the code above. In certain cases,
 it does the **wrong thing**.
 
 ### Leading Parenthesis
@@ -106,9 +106,9 @@ the above will yield a `TypeError` stating that `undefined is not a function`.
 
 ### In Conclusion
 
-It is highly recommended to **never** omit semicolons, it is also advocated to 
+It is highly recommended to **never** omit semicolons; it is also advocated to 
 keep braces on the same line with their corresponding statements and to never omit 
 them for one single-line `if` / `else` statements. Both of these measures will 
-not only improve the consistency of the code, they will also prevent the 
+not only improve the consistency of the code, but they will also prevent the 
 JavaScript parser from changing its behavior.
 

doc/en/core/undefined.md

@@ -7,9 +7,9 @@ being `undefined`.
 
 `undefined` is a type with exactly one value: `undefined`.
 
-The language also defines a global variable that has the value of `undefined`,
-this variable is also called `undefined`. But this variable is **not** a constant,
-nor is it a keyword of the language. This means that its *value* can be easily 
+The language also defines a global variable that has the value of `undefined`;
+this variable is also called `undefined`. However, this variable is **neither** a constant
+nor a keyword of the language. This means that its *value* can be easily 
 overwritten.
 
 > **ES5 Note:** `undefined` in ECMAScript 5 is **no longer** *writable* in strict
@@ -31,12 +31,12 @@ Since the global variable `undefined` only holds a copy of the actual *value* of
 `undefined`, assigning a new value to it does **not** change the value of the 
 *type* `undefined`.
 
-Still, in order to compare something against the value of `undefined` it is
+Still, in order to compare something against the value of `undefined`, it is
 necessary to retrieve the value of `undefined` first.
 
 In order to protect code against a possible overwritten `undefined` variable, a 
 common technique used is to add an additional parameter to an
-[anonymous wrapper](#function.scopes), that gets no argument passed to it.
+[anonymous wrapper](#function.scopes) that gets no argument passed to it.
 
     var undefined = 123;
     (function(something, foo, undefined) {
@@ -55,8 +55,8 @@ wrapper.
 
     })('Hello World', 42);
 
-The only difference being here, that this version results in 4 more bytes being
-used in case it is minified and there is no other `var` statement inside the
+The only difference here is that this version results in 4 more bytes being
+used in case it is minified, and there is no other `var` statement inside the
 anonymous wrapper.
 
 ### Uses of `null`
@@ -66,7 +66,7 @@ the sense of a traditional *null*, the actual `null` (both a literal and a type)
 is more or less just another data type.
 
 It is used in some JavaScript internals (like declaring the end of the
-prototype chain by setting `Foo.prototype = null`), but in almost all cases it
+prototype chain by setting `Foo.prototype = null`), but in almost all cases, it
 can be replaced by `undefined`.
 
 

doc/en/function/arguments.md

@@ -23,8 +23,8 @@ The code below will return a new `Array` containing all the elements of the
 
     Array.prototype.slice.call(arguments);
 
-This conversion is **slow**, it is **not recommended** to use it in performance 
-critical sections of code.
+Because this conversion is **slow**, it is **not recommended** to use it in
+performance-critical sections of code.
 
 ### Passing Arguments
 
@@ -59,14 +59,14 @@ wrappers.
 ### Formal Parameters and Arguments Indices
 
 The `arguments` object creates *getter* and *setter* functions for both its 
-properties as well as the function's formal parameters.
+properties, as well as the function's formal parameters.
 
 As a result, changing the value of a formal parameter will also change the value
 of the corresponding property on the `arguments` object, and the other way around.
 
     function foo(a, b, c) {
         arguments[0] = 2;
-        a; // 2                                                           
+        a; // 2
 
         b = 4;
         arguments[1]; // 4
@@ -105,8 +105,8 @@ modern JavaScript engines. That case is the use of `arguments.callee`.
 
 In the above code, `foo` can no longer be a subject to [inlining][1] since it 
 needs to know about both itself and its caller. This not only defeats possible 
-performance gains that would arise from inlining, it also breaks encapsulation
-since the function may now be dependent on a specific calling context.
+performance gains that would arise from inlining, but it also breaks encapsulation
+because the function may now be dependent on a specific calling context.
 
 It is **highly recommended** to **never** make use of `arguments.callee` or any of 
 its properties.

doc/en/function/closures.md

@@ -1,8 +1,8 @@
 ## Closures and References
 
-One of JavaScript's most powerful features is the availability of *closures*,
-this means that scopes **always** keep access to the outer scope they were
-defined in. Since the only scoping that JavaScript has is 
+One of JavaScript's most powerful features is the availability of *closures*.
+With closures, scopes **always** keep access to the outer scope, in which they
+were defined. Since the only scoping that JavaScript has is 
 [function scope](#function.scopes), all functions, by default, act as closures.
 
 ### Emulating private variables
@@ -24,7 +24,7 @@ defined in. Since the only scoping that JavaScript has is
     foo.increment();
     foo.get(); // 5
 
-Here, `Counter` returns **two** closures. The function `increment` as well as 
+Here, `Counter` returns **two** closures: the function `increment` as well as 
 the function `get`. Both of these functions keep a **reference** to the scope of 
 `Counter` and, therefore, always keep access to the `count` variable that was 
 defined in that very scope.
@@ -58,8 +58,8 @@ copying the value of the loops index variable.
 The above will **not** output the numbers `0` through `9`, but will simply print
 the number `10` ten times.
 
-The *anonymous* function keeps a **reference** to `i` and at the time 
-`console.log` gets called, the `for loop` has already finished and the value of 
+The *anonymous* function keeps a **reference** to `i`. At the time 
+`console.log` gets called, the `for loop` has already finished, and the value of 
 `i` as been set to `10`.
 
 In order to get the desired behavior, it is necessary to create a **copy** of 
@@ -84,8 +84,8 @@ argument and will receive a copy of the **value** of `i` as its parameter `e`.
 The anonymous function that gets passed to `setTimeout` now has a reference to 
 `e`, whose value does **not** get changed by the loop.
 
-There is another possible way of achieving this; that is to return a function 
-from the anonymous wrapper, that will then have the same behavior as the code 
+There is another possible way of achieving this, which is to return a function 
+from the anonymous wrapper that will then have the same behavior as the code 
 above.
 
     for(var i = 0; i < 10; i++) {

doc/en/function/constructors.md

@@ -24,7 +24,7 @@ implicitly returns the value of `this` - the new object.
 The above calls `Foo` as constructor and sets the `prototype` of the newly
 created object to `Foo.prototype`.
 
-In case of an explicit `return` statement the function returns the value 
+In case of an explicit `return` statement, the function returns the value 
 specified that statement, **but only** if the return value is an `Object`.                                     
 
     function Bar() {
@@ -73,7 +73,7 @@ explicitly return a value.
     Bar();
 
 Both calls to `Bar` return the exact same thing, a newly create object which
-has a property called `method` on it, that is a 
+has a property called `method` on it, which is a 
 [Closure](#function.closures).
 
 It is also to note that the call `new Bar()` does **not** affect the prototype 
@@ -86,7 +86,7 @@ not using the `new` keyword.
 
 ### Creating New Objects via Factories
 
-An often made recommendation is to **not** use `new` since forgetting its use
+An often made recommendation is to **not** use `new` because forgetting its use
 may lead to bugs.
 
 In order to create new object, one should rather use a factory and construct a