doc(compiler): rewrite

4 files changed, 143 insertions, 74 deletions

diff --git a/docs/content/guide/compiler.ngdoc b/docs/content/guide/compiler.ngdoc
new file mode 100644
index 00000000..90dc4d61
--- /dev/null
+++ b/docs/content/guide/compiler.ngdoc
@@ -0,0 +1,143 @@
+@ngdoc overview
+@name Developer Guide: HTML Compiler
+@description
+
+# Overview
+
+Angular's {@link api/angular.module.ng.$compile HTML compiler} allows the developer to teach the
+browser new HTML syntax. The compiler allows you to attach behavior to any HTML element or attribute
+and even create new HTML element or attributes with custom behavior. Angular calls these behavior
+extensions {@link api/angular.module.ng.$compileProvider.directive directives}.
+
+HTML has a lot of constructs for formatting the HTML for static documents in declarative fashion.
+For example if something needs to be centered, there is no need to provide instructions to the
+browser how the window size needs to be divided in half so that center is found, and that this
+center needs to be aligned with the text's center. Simply add `align="center"` attribute to any
+element to achieve the desired behavior. Such is the power of declarative language.
+
+But the declarative language is also limited, since it does not allow you to teach the browser new
+syntax. For example there is no easy way to get the browser to align the text at 1/3 the position
+instead of 1/2. What is needed is a way to teach browser new HTML syntax. 
+
+Angular comes pre-bundled with common directives which are useful for building any app. We also
+expect that you will create directives that are specific to your app. These extension become a
+Domain Specific Language for building your application.
+
+All of this compilation takes place in the web browser; no server side or pre-compilation step is
+involved.
+
+
+# Compiler
+
+Compiler is an angular service which traverses the DOM looking for attributes. The compilation 
+process happens into two phases.
+
+  1. **Compile:** traverse the DOM and collect all of the directives. The result is a linking
+  function.
+
+  2. **Link:** combine the directives with a scope and produce a live view. Any changes in the
+  scope model are reflected in the view, and any user interactions with the view are reflected
+  in the scope model. Making the scope model a single source of truth.
+
+Some directives such {@link api/angular.module.ng.$compileProvider.directive.ng:repeat
+`ng-repeat`} clone DOM elements once for each item in collection. Having a compile and link phase
+improves performance since the cloned template only needs to be compiled once, and then linked
+once for each clone instance.
+
+
+# Directive
+
+Directive is a behavior which should be triggered when specific HTML constructs are encountered in
+compilation process. The directives can be placed in element names, attributes, class names, as
+well as comments. Here are some equivalent examples of invoking {@link
+api/angular.module.ng.$compileProvider.directive.ng:bind `ng-bind`} directive.
+
+<pre>
+  <span ng-bind="exp"></span>
+  <span class="ng-bind: exp;"></span>
+  <ng-bind></ng-bind>
+  <!-- directive: ng-bind exp -->
+</pre>
+
+Directive is just a function which executes when the compiler encounters it in the DOM. See {@link
+api/angular.module.ng.$compileProvider.directive directive API} for in depth documentation on how
+to write directives.
+
+Here is a directive which makes any element draggable. Notice the `draggable` attribute on the
+`<span>` element.
+
+<doc-example module="drag">
+  <doc-source>
+    <script>
+      angular.module('drag', []).
+        directive('draggable', function($document) {
+          var startX=0, startY=0, x = 0, y = 0;
+          return function(scope, element, attr) {
+            element.css({
+             position: 'relative',
+             border: '1px solid red',
+             backgroundColor: 'lightgrey',
+             cursor: 'pointer'
+            });
+            element.bind('mousedown', function(event) {
+              startX = event.screenX - x;
+              startY = event.screenY - y;
+              $document.bind('mousemove', mousemove);
+              $document.bind('mouseup', mouseup);
+            });
+            
+            function mousemove(event) {
+              y = event.screenY - startY;
+              x = event.screenX - startX;
+              element.css({
+                top: y + 'px',
+                left:  x + 'px'
+              });
+            }
+            
+            function mouseup() {
+              $document.unbind('mousemove', mousemove);
+              $document.unbind('mouseup', mouseup);
+            }
+          }
+        });
+    </script>
+    <span draggable>Drag ME</span>
+  </doc-source>
+</doc-example>
+
+
+The presence of `draggable` attribute an any element gives the element new behavior. The beauty of
+this approach is that we have thought the browser a new trick, we have extended the vocabulary of
+what browser understands in a way, which is natural to anyone who is familiar with HTML
+principles.
+
+
+# Understanding View
+
+There are many templating systems out there. Most of them consume a static string template and 
+combine it with data, resulting in a new string. The resulting text is then `innerHTML`ed into
+an element. 
+
+<img src="img/One_Way_Data_Binding.png">
+
+This means that any changes to the data, need to be re-merged with the template and then
+`innerHTML`ed into the DOM. Some of the issues are: reading user input and merging it with data,
+clobbering user input by overwriting it, managing the whole update process, and lack of behavior
+expressiveness.
+
+Angular is different. Angular compiler consumes DOM with directives, not string templates. The
+result is a linking function, which when combined with a scope model results in live view. The
+view and scope model bindings are transparent, no action from the developer is needed to update
+the view. And because no `innerHTML` is used there are no issues of clobbering user input.
+Furthermore, angular directives can contain not just text bindings, but behavioral constructs as
+well.
+
+<img src="img/Two_Way_Data_Binding.png">
+
+The Angular approach produces stable DOM. This means that the DOM element instance bound to model
+item instance does not change for the lifetime of the binding. This means that the code can get
+hold of the elements and register event handlers and know that the reference will not be destroyed
+by template data merge.
+
+
diff --git a/docs/content/guide/dev_guide.compiler.ngdoc b/docs/content/guide/dev_guide.compiler.ngdoc
deleted file mode 100644
index f52928a6..00000000
--- a/docs/content/guide/dev_guide.compiler.ngdoc
+++ /dev/null
@@ -1,24 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Angular HTML Compiler
-@description
-
-The core of Angular is its HTML compiler.  The compiler processes Angular 
-{@link guide/directive directives} allowing them to transform a
-static HTML page into a dynamic web application.
-
-The default HTML transformations that the Angular compiler provides are useful for building generic
-apps, but you can also extend the compiler to create a domain-specific language for building
-specific types of web applications.
-
-All compilation takes place in the web browser; no server is involved.
-
-
-## Related Topics
-
-* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}
-* {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element}
-
-## Related API
-
-* {@link api/angular.module.ng.$compile Angular Compiler API}
-* {@link guide/directive Directives API}
diff --git a/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc b/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc
deleted file mode 100644
index 8ffa760e..00000000
--- a/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc
+++ /dev/null
@@ -1,16 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Angular HTML Compiler: Testing a New DOM Element
-@description
-
-
-"Testing, testing, come in, over?"
-
-
-## Related Topics
-
-* {@link dev_guide.compiler Angular HTML Compiler}
-* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}
-
-## Related API
-
-* {@link api/angular.module.ng.$compile $compile()}
diff --git a/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc b/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc
deleted file mode 100644
index ea433cc5..00000000
--- a/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc
+++ /dev/null
@@ -1,34 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Angular HTML Compiler: Understanding How the Compiler Works
-@description
-
-The {@link api/angular.module.ng.$compile compiler} is responsible for applying
-{@link guide/directive directives} to the HTML. The directives
-extend the behavior of HTML elements and can effect the DOM structure, presentation, and behavior.
-This allows Angular to teach the browser new tricks.
-
-The compilation starts at the root element and proceeds in a depth-first order. As the compiler
-visits each node it collects the directives, orders them by priority and executes their compile
-function. The result of the compilation process is a linking function. The linking function
-can be used on the template clones to quickly bind the directives with the scope.
-
-The result of the compilation process is a live view. We say 'live' since any changes to the
-model attached to the {@link api/angular.module.ng.$rootScope.Scope scope} are reflected in the view,
-and any changes in the view are reflected in the scope. This makes the scope the 'single source of
-truth'.
-
-Since directives allow attachment of behavior to the HTML, the angular philosophy is to use the
-HTML as Domain Specific Language (DSL) when building an application. For example it may be useful
-to declare `TabPanel` directive, or `KeyboardShortcut` directive when for an application.
-
-For details on how directives are created see {@link guide/directive
-directives}
-
-## Related Topics
-
-* {@link dev_guide.compiler Angular HTML Compiler}
-* {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element}
-
-## Related API
-
-* {@link api/angular.module.ng.$compile $compile()}