merge with upstream

Author: shamansir

.gitignore

@@ -9,6 +9,12 @@
 /site/zh
 /site/en
 /site/fi
+/site/pl
 /site/tr
+/site/ko
+/site/ja
+/site/es
+/site/zhtw
 *.md~
 *.src.md
+*.DS_store

build.js

@@ -1,5 +1,5 @@
 var fs = require('fs'),
-    path = require('path');
+    path = require('path'),
     jade = require('jade'),
     md = require('node-markdown'),
     Class = require('neko').Class;
@@ -28,10 +28,10 @@ var Garden = Class(function(options) {
 
             if (that.loadIndex()) {
                 that.languages[lang] = that.lang;
-                that.log('    Done.')
+                that.log('    Done.');
 
             } else {
-                that.log('    Error: Could not find "index.json"!')
+                that.log('    Error: Could not find "index.json"!');
             }
         }
     });
@@ -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/de/intro/index.md

@@ -1,4 +1,43 @@
 ## Einführung
 
-Demnächst.
+**JavaScript Garden** ist eine wachsende Sammlung von Erklärungen der verzwicktesten Teile von JavaScript. Es gibt 
+Hinweise um häufige Fehler, Performance Probleme und schlechten Stil zu vermeiden.
 
+JavaScript Garden ist **keine** Anleitung um JavaScript zu lernen. Ein grundlegendes Verständnis der Sprache wird 
+wärmstens empfohlen. Eine gute [Einführung][1] findet sich zum Beispiel im Mozilla Developer Network.
+
+## Die Autoren
+
+Dieses Dokument wurde von zwei liebenswerten [Stack Overflow][2] Benutzern geschrieben: [Ivo Wetzel][3]
+(Text) and [Zhang Yi Jiang][4] (Design).
+
+## Beitragende
+
+ - [Caio Romão][5] (Rechtschreibung)
+ - [Andreas Blixt][6] (Sprachanpassungen)
+
+## Hosting
+
+JavaScript Garden wird von GitHub bereitgestellt, aber es wird auch von [Cramer Development][7] unterstützt durch 
+einen Mirror auf [JavaScriptGarden.info][8].
+
+## Lizenz
+
+JavaScript Garden wurde unter der [MIT Lizenz][9] veröffentlich und wird von [GitHub][10] veröffentlicht. Wenn du 
+Fehler findest mach bitte ein [Ticket][11] auf oder einen pull request ins repository. Du kannst uns auch im 
+[JavaScript Raum][12] des Stack Overflow Chats finden.
+
+Mehr demnächst.
+
+[1]: https://developer.mozilla.org/en/JavaScript/Guide
+[2]: http://stackoverflow.com/
+[3]: http://stackoverflow.com/users/170224/ivo-wetzel
+[4]: http://stackoverflow.com/users/313758/yi-jiang
+[5]: https://github.com/caio
+[6]: https://github.com/blixt
+[7]: http://cramerdev.com/
+[8]: http://javascriptgarden.info/
+[9]: https://github.com/BonsaiDen/JavaScript-Garden/blob/next/LICENSE
+[10]: https://github.com/BonsaiDen/JavaScript-Garden
+[11]: https://github.com/BonsaiDen/JavaScript-Garden/issues
+[12]: http://chat.[stackoverflow.com/rooms/17/javascript

doc/en/array/constructor.md

@@ -11,25 +11,25 @@ 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);
     arr[1]; // undefined
     1 in arr; // false, the index was not set
 
-The behavior of being able to set the length of the array upfront only comes in 
-handy in a few cases, like repeating a string, in which it avoids the use of a 
-`for loop` code.
+Being able to set the length of the array in advance is only useful in a few
+cases, like repeating a string, in which it avoids the use of a `for loop`
+code.
 
     new Array(count + 1).join(stringToRepeat);
 
 ### In Conclusion
 
-The use of the `Array` constructor should be avoided as much as possible. 
-Literals are definitely preferred. They are shorter and have a clearer syntax; 
-therefore, they also increase the readability of the code.
+The use of the `Array` constructor should be avoided. Literals are definitely
+preferred. They are shorter, have a clearer syntax, and increase code
+readability.
 

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`](#object.forinloop) loop. 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
@@ -45,14 +45,14 @@ elements that are contained in the array, the *setter* can be used to
     foo; // [1, 2, 3]
 
     foo.length = 6;
-    foo; // [1, 2, 3]
+    foo.push(4);
+    foo; // [1, 2, 3, undefined, undefined, undefined, 4]
 
-Assigning a smaller length does truncate the array, but increasing the length 
-does not have any effect on the array.
+Assigning a smaller length truncates the array. Increasing it creates a sparse 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,85 @@
+## 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 the Activation object or
+the Global object. Such properties have a set of attributes, one of which is
+`DontDelete`. Variable and function declarations in global and function code
+always create properties with `DontDelete`, and 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
+
+Explicitly set properties can be deleted normally.
+
+    // 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 the 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 its property 
+which allows us to delete it.
+
+IE (at least 6-8) has some bugs, so the code above doesn't work.
+
+### Function arguments and built-ins
+
+Functions' normal arguments, [`arguments` objects](#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
+    
+The behaviour of `delete` operator can be unpredictable for hosted objects. Due
+to the specification, host objects are allowed to implement any kind of behavior. 
+
+### In conclusion
+
+The `delete` operator often has unexpected behaviour and can only be safely
+used to delete 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() {
@@ -24,8 +24,8 @@ the name of the called function is actually `eval`.
     test(); // 2
     foo; // 3
 
-The use of `eval` should be avoided at **all costs**. 99.9% of its "uses" can be
-achieved **without** it.
+The use of `eval` should be avoided. 99.9% of its "uses" can be achieved
+**without** it.
 
 ### `eval` in Disguise
 
@@ -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,
-it should **never** be used with strings of unknown or untrusted origins.
+`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
-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`. 
+`eval` should never be used. Any code that makes use of it should be questioned
+in its workings, performance and security. If something requires `eval` in
+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
 
@@ -84,10 +84,10 @@ Below is the result of the parser's "guessing" game.
     })(window); //<- inserted
 
 > **Note:** The JavaScript parser does not "correctly" handle return statements 
-> which are followed by a new line, while this is not neccessarily the fault of 
+> that 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 
-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 
-JavaScript parser from changing its behavior.
+It is highly recommended to **never** omit semicolons. It is also recommended
+that braces be kept on the same line as their corresponding statements and to
+never omit them for single-line `if` / `else` statements. These measures will
+not only improve the consistency of the code, but they will also prevent the
+JavaScript parser from changing code behavior.