1 files changed, 120 insertions, 0 deletions
diff --git a/docs/content/guide/dev_guide.compiler.markup.ngdoc b/docs/content/guide/dev_guide.compiler.markup.ngdoc
new file mode 100644
index 00000000..64a3940b
--- /dev/null
+++ b/docs/content/guide/dev_guide.compiler.markup.ngdoc
@@ -0,0 +1,120 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Angular HTML Compiler: Understanding Angular Markup
+@description
+
+
+Markup in angular is a feature that you can use in templates to transform the content of DOM
+elements prior to the compile phase (in which elements are compiled and link functions are
+returned.  See the {@link dev_guide.compiler compiler docs} for details on how the compiler
+works.)  The ability to make pre-compile changes to DOM elements lets you create shorthand for
+{@link api/angular.widget widget} and {@link api/angular.directive directive} declarations.
+
+
+Angular provides one built-in markup feature: the double curly-braces used to declare binding
+points (between the model and view) for angular expressions.  You can also create your own custom
+markup.
+
+
+# Using Double Curly-brace Markup (`{{ }}`)
+
+
+The double curly-brace (`{{ }}`) markup translates an enclosed expression into an {@link
+api/angular.directive.ng:bind ng:bind} directive:
+
+
+<pre>
+{{expression}}
+</pre>
+
+
+is transformed to:
+
+
+<pre>
+<span ng:bind="expression"></span>
+</pre>
+
+
+Markup is useful for the simple reason that `{{1+2}}` is easier to write and understand than `<span
+ng:bind="1+2"></span>`. After markup shorthand is expanded into the DOM elements it represents, the
+expanded elements are then {@link dev_guide.compiler compiled} normally.
+
+
+
+
+# Creating Custom Markup
+
+
+Let's say you want to define markup that transforms `---` into a horizontal rule (`<hr/>`):
+
+
+<pre>
+header
+---
+footer
+</pre>
+
+
+should translate to:
+<pre>
+header
+<hr/>
+footer
+</pre>
+
+
+Here is how you could extend the angular compiler to create the "---" markup:
+
+
+<pre>
+angular.markup('---', function(text, textNode, parentElement) {
+    var compiler = this;
+    var index = text.indexOf('---');
+    if (index > -1) {
+        var before = compiler.text(text.substring(0, index));
+        var hr = compiler.element('hr');
+        var after = compiler.text(text.substring(index + 3));
+        textNode.after(after);
+        textNode.after(hr);
+        textNode.after(before);
+        textNode.remove();
+    }
+});
+</pre>
+
+
+Unlike the way the compiler processes {@link api/angular.widget widgets} and {@link
+api/angular.directive directives} (matching the name of the handler function to a DOM element or
+attribute name), the compiler calls every markup handler for every text node, giving the handler a
+chance to transform the text. The markup handler needs to find all the matches in the text.
+
+
+## Attribute Markup
+
+
+Attribute markup extends the angular compiler in a very similar way to markup, except that it
+allows you to modify the state of attribute text rather then the content of a node.
+
+
+<pre>
+angular.attrMarkup('extraClass', function(attrValue, attrName, element){
+ if (attrName == 'additional-class') {
+   element.addClass(attrValue);
+ }
+});
+</pre>
+
+
+
+
+## Related Topics
+
+
+* {@link dev_guide.compiler Angular HTML Compiler}
+
+
+## Related API
+
+
+* {@link api/angular.compile Compiler API Reference}