event docs; xtreme markdown fixes

docs/client/api.html

@@ -934,7 +934,7 @@ reactive data sources used by that function. For more information, or
 to learn how to make your own reactive data sources, see
 [Reactivity](#reactivity).
 
-<!--
+{{!
 Meteor.ui.render runs html_func in a reactive context, then returns a
 DocumentFragment that can be inserted anywhere in a Document and that
 will automatically update itself in place whenever the context is
@@ -955,7 +955,7 @@ can use Meteor.ui.chunk to create a nested tree of invalidation
 contexts.
 [events]
 [more?]
--->
+}}
 
 
 Example:
@@ -1113,25 +1113,27 @@ the handlers for those events. The property can be in one of several
 forms:
 
 <dl>
-{{#dtdd "<em>eventname</em>"}}
-Matches a particular type of event, such as 'click'
+{{#dtdd "<em>eventtype</em>"}}
+Matches a particular type of event, such as 'click'.
 {{/dtdd}}
 
-{{#dtdd "<em>eventname selector</em>"}}
+{{#dtdd "<em>eventtype selector</em>"}}
 Matches a particular type of event, but only when it appears on
-an element that matches a certain CSS selector
+an element that matches a certain CSS selector.  
 {{/dtdd}}
 
 {{#dtdd "<em>event1, event2</em>"}}
-To handle more than one type of event with the same function, use a comma-separated list.{{/dtdd}}
-
+To handle more than one type of event with the same function, use a comma-separated list.
+{{/dtdd}}
 </dl>
 
 The handler function gets one argument, an object with information
-about the event. It will receive some additional context data
-in `this`, depending on the context of the element that generated
-the event, set either by an `event_data` option attached to a chunk
-or by a Handlebars template or block helper.
+about the event. It will receive some additional context data in
+`this`, depending on the context of the element that generated the
+event.  In a Handlebars template, the element's context is the
+Handlebars data context, which is set by block helpers such as `#with`
+and `#each`.  When using [`Meteor.ui.chunk`](#meteor_ui_chunk), the
+data context is set using the `event_data` option.
 
 Example:
 
@@ -1146,6 +1148,83 @@ Example:
       'keydown, click .accept': function (event) { ... }
     }
 
+Most events bubble up the document tree from their originating
+element.  For example, `'click p'` catches a click anywhere in a
+paragraph, even if the click originated on a link, span, or some other
+element inside the paragraph.  The originating element of the event
+is available as the `target` property, while the element that matched
+the selector and is currently handling it is called `currentTarget`.
+
+    {
+      'click p': function (event) {
+        var paragraph = event.currentTarget; // always a P
+        var clickedElement = event.target; // could be the P or a child element
+      }
+    }
+
+If a selector matches multiple elements that an event bubbles to, it
+will be called multiple times, for example in the case of `'click
+div'` or `'click *'`.  If no selector is given, the handler
+will only be called once, on the original target element.
+
+The following properties and methods are available on the event object
+passed to handlers:
+
+<dl class="objdesc">
+{{#dtdd "type" "String"}}
+The event's type, such as "click", "blur" or "keypress".
+{{/dtdd}}
+
+{{#dtdd "target" "DOM Element"}}
+The element that originated the event.
+{{/dtdd}}
+
+{{#dtdd "currentTarget" "DOM Element"}}
+The element currently handling the event.  This is the element that
+matches the selector in the event map.  For events that bubble, it may
+be `target` or an ancestor of `target`, and its value changes as the
+event bubbles.
+{{/dtdd}}
+
+{{#dtdd "which" "Number"}}
+For mouse events, the number of the mouse button (1=left, 2=middle, 3=right).
+For key events, a character or key code.
+{{/dtdd}}
+
+{{#dtdd "stopPropagation()"}}
+Prevent the event from propagating (bubbling) up to other elements.
+Other event handlers matching the same element are still fired, in
+this and other event maps.
+{{/dtdd}}
+
+{{#dtdd "stopImmediatePropagation()"}}
+Prevent all additional event handlers from being run on this event,
+including other handlers in this event map, handlers reached by
+bubbling, and handlers in other event maps.
+{{/dtdd}}
+
+{{#dtdd "preventDefault()"}}
+Prevents the action the browser would normally take in response to this
+event, such as following a link or submitting a form.  Further handlers
+are still called, but cannot reverse the effect.
+{{/dtdd}}
+
+{{#dtdd "isPropagationStopped()"}}
+Returns whether `stopPropagation()` has been called for this event.
+{{/dtdd}}
+
+{{#dtdd "isImmediatePropagationStopped()"}}
+Returns whether `stopImmediatePropagation()` has been called for this event.
+{{/dtdd}}
+
+{{#dtdd "isDefaultPrevented()"}}
+Returns whether `preventDefault()` has been called for this event.
+{{/dtdd}}
+</dl>
+
+Returning `false` from a handler is the same as calling
+both `stopImmediatePropagation` and `preventDefault` on the event.
+
 {{/api_box_inline}}
 
 <h2 id="timers"><span>Timers</span></h2>

docs/client/docs.css

@@ -238,28 +238,28 @@ dl.example dd {
     margin-bottom: 10px;
 }
 
-.objdesc dt {
+dl.objdesc dt {
     margin-top: 1em;
     margin-left: 1.5em;
 }
 
-.objdesc dt .name {
+dl.objdesc dt .name {
     font-weight: bold;
 }
 
-.objdesc dt .type {
+dl.objdesc dt .type {
     margin-left: 15px;
     font-size: .9em;
     font-weight: 200;
     color: black;
 }
 
-.objdesc dd {
+dl.objdesc dd {
     margin-bottom: 1em;
     margin-left: 1.5em;
 }
 
-.callbacks dt .name, .methods dt .name {
+dl.callbacks dt .name, dl.methods dt .name {
   /* like code tag */
   font-family: monospace;
   font-size: 1.1em;

docs/client/docs.js

@@ -318,11 +318,10 @@ Handlebars.registerHelper('better_markdown', function(fn) {
     return result;
   };
 
-  // prevent liverange comment at beginning or end of line from throwing
-  // off showdown's HTML block parsing
-  input = input.replace(/^(<!--.*?-->)|(<!--.*?-->)$/mg, function(s) {
-    return '\n'+s+'\n';
-  });
+  input = input.replace(/<!--.*?-->/g, '\n$&\n');
+
+  var hashedBlocks = {};
+  var numHashedBlocks = 0;
 
   var nestedTags = [];
   while (idx < input.length) {
@@ -349,24 +348,25 @@ Handlebars.registerHelper('better_markdown', function(fn) {
         }
       }
       var newBlock = blockBuf.join('');
+      var openTagFinish = newBlock.indexOf('>') + 1;
       var closeTagLoc = newBlock.lastIndexOf('<');
-      var firstMatchingClose = newBlock.indexOf('</'+blockTag+'>');
-      var shouldIndent =
-            (firstMatchingClose >= 0 && firstMatchingClose < closeTagLoc);
-      // Put final close tag at beginning of line, indent other lines if necessary.
-      // Not indenting unless necessary saves us from indenting in a <pre> tag.
-      var part1 = newBlock.substring(0, closeTagLoc);
-      var part2 = newBlock.substring(closeTagLoc);
-      if (shouldIndent)
-        part1 = part1.replace(/\n/g, '\n  ');
-      newBlock = part1 + '\n' + part2;
-      newParts.push(newBlock);
+
+      var key = ++numHashedBlocks;
+      hashedBlocks[key] = newBlock.slice(openTagFinish, closeTagLoc);
+      newParts.push(newBlock.slice(0, openTagFinish),
+                    '!!!!HTML:'+key+'!!!!',
+                    newBlock.slice(closeTagLoc));
       blockBuf.length = 0;
     }
   }
 
   var newInput = newParts.join('');
   var output = converter.makeHtml(newInput);
+
+  output = output.replace(/!!!!HTML:(.*?)!!!!/g, function(z, a) {
+    return hashedBlocks[a];
+  });
+
   return output;
 });