v0.0.1

codemirror/doc/activebookmark.js

@@ -0,0 +1,57 @@
+// Kludge in HTML5 tag recognition in IE8
+document.createElement("section");
+document.createElement("article");
+
+(function() {
+  if (!window.addEventListener) return;
+  var pending = false, prevVal = null;
+
+  function updateSoon() {
+    if (!pending) {
+      pending = true;
+      setTimeout(update, 250);
+    }
+  }
+
+  function update() {
+    pending = false;
+    var marks = document.getElementById("nav").getElementsByTagName("a"), found;
+    for (var i = 0; i < marks.length; ++i) {
+      var mark = marks[i], m;
+      if (mark.getAttribute("data-default")) {
+        if (found == null) found = i;
+      } else if (m = mark.href.match(/#(.*)/)) {
+        var ref = document.getElementById(m[1]);
+        if (ref && ref.getBoundingClientRect().top < 50)
+          found = i;
+      }
+    }
+    if (found != null && found != prevVal) {
+      prevVal = found;
+      var lis = document.getElementById("nav").getElementsByTagName("li");
+      for (var i = 0; i < lis.length; ++i) lis[i].className = "";
+      for (var i = 0; i < marks.length; ++i) {
+        if (found == i) {
+          marks[i].className = "active";
+          for (var n = marks[i]; n; n = n.parentNode)
+            if (n.nodeName == "LI") n.className = "active";
+        } else {
+          marks[i].className = "";
+        }
+      }
+    }
+  }
+
+  window.addEventListener("scroll", updateSoon);
+  window.addEventListener("load", updateSoon);
+  window.addEventListener("hashchange", function() {
+    setTimeout(function() {
+      var hash = document.location.hash, found = null, m;
+      var marks = document.getElementById("nav").getElementsByTagName("a");
+      for (var i = 0; i < marks.length; i++)
+        if ((m = marks[i].href.match(/(#.*)/)) && m[1] == hash) { found = i; break; }
+      if (found != null) for (var i = 0; i < marks.length; i++)
+        marks[i].className = i == found ? "active" : "";
+    }, 300);
+  });
+})();

codemirror/doc/docs.css

@@ -0,0 +1,274 @@
+@font-face {
+  font-family: 'Source Sans Pro';
+  font-style: normal;
+  font-weight: 400;
+  src: local('Source Sans Pro'), local('SourceSansPro-Regular'), url(//themes.googleusercontent.com/static/fonts/sourcesanspro/v5/ODelI1aHBYDBqgeIAH2zlBM0YzuT7MdOe03otPbuUS0.woff) format('woff');
+}
+
+body, html { margin: 0; padding: 0; height: 100%; }
+section, article { display: block; padding: 0; }
+
+body {
+  background: #f8f8f8;
+  font-family: 'Source Sans Pro', Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+}
+
+p { margin-top: 0; }
+
+h2, h3, h1 {
+  font-weight: normal;
+  margin-bottom: .7em;
+}
+h1 { font-size: 140%; }
+h2 { font-size: 120%; }
+h3 { font-size: 110%; }
+article > h2:first-child, section:first-child > h2 { margin-top: 0; }
+
+#nav h1 {
+  margin-right: 12px;
+  margin-top: 0;
+  margin-bottom: 2px;
+  color: #d30707;
+  letter-spacing: .5px;
+}
+
+a, a:visited, a:link, .quasilink {
+  color: #A21313;
+}
+
+em {
+  padding-right: 2px;
+}
+
+.quasilink {
+  cursor: pointer;
+}
+
+article {
+  max-width: 700px;
+  margin: 0 0 0 160px;
+  border-left: 2px solid #E30808;
+  border-right: 1px solid #ddd;
+  padding: 30px 50px 100px 50px;
+  background: white;
+  z-index: 2;
+  position: relative;
+  min-height: 100%;
+  box-sizing: border-box;
+  -moz-box-sizing: border-box;
+}
+
+#nav {
+  position: fixed;
+  padding-top: 30px;
+  max-height: 100%;
+  box-sizing: -moz-border-box;
+  box-sizing: border-box;
+  overflow-y: auto;
+  left: 0; right: none;
+  width: 160px;
+  text-align: right;
+  z-index: 1;
+}
+
+@media screen and (min-width: 1000px) {
+  article {
+    margin: 0 auto;
+  }
+  #nav {
+    right: 50%;
+    width: auto;
+    border-right: 349px solid transparent;
+  }
+}
+
+#nav ul {
+  display: block;
+  margin: 0; padding: 0;
+  margin-bottom: 32px;
+}
+
+#nav a {
+  text-decoration: none;
+}
+
+#nav li {
+  display: block;
+  margin-bottom: 4px;
+}
+
+#nav li ul {
+  font-size: 80%;
+  margin-bottom: 0;
+  display: none;
+}
+
+#nav li.active ul {
+  display: block;
+}
+
+#nav li li a {
+  padding-right: 20px;
+  display: inline-block;
+}
+
+#nav ul a {
+  color: black;
+  padding: 0 7px 1px 11px;
+}
+
+#nav ul a.active, #nav ul a:hover {
+  border-bottom: 1px solid #E30808;
+  margin-bottom: -1px;
+  color: #E30808;
+}
+
+#logo {
+  border: 0;
+  margin-right: 12px;
+  margin-bottom: 25px;
+}
+
+section {
+  border-top: 1px solid #E30808;
+  margin: 1.5em 0;
+}
+
+section.first {
+  border: none;
+  margin-top: 0;
+}
+
+#demo {
+  position: relative;
+}
+
+#demolist {
+  position: absolute;
+  right: 5px;
+  top: 5px;
+  z-index: 25;
+}
+
+.yinyang {
+  position: absolute;
+  top: -10px;
+  left: 0; right: 0;
+  margin: auto;
+  display: block;
+  height: 120px;
+}
+
+.actions {
+  margin: 1em 0 0;
+  min-height: 100px;
+  position: relative;
+}
+
+.actionspicture {
+  pointer-events: none;
+  position: absolute;
+  height: 100px;
+  top: 0; left: 0; right: 0;
+}
+
+.actionlink {
+  pointer-events: auto;
+  font-family: arial;
+  font-size: 80%;
+  font-weight: bold;
+  position: absolute;
+  top: 0; bottom: 0;
+  line-height: 1;
+  height: 1em;
+  margin: auto;
+}
+
+.actionlink.download {
+  color: white;
+  right: 50%;
+  margin-right: 13px;
+  text-shadow: -1px 1px 3px #b00, -1px -1px 3px #b00, 1px 0px 3px #b00;
+}
+
+.actionlink.fund {
+  color: #b00;
+  left: 50%;
+  margin-left: 15px;
+}
+
+.actionlink:hover {
+  text-decoration: underline;
+}
+
+.actionlink a {
+  color: inherit;
+}
+
+.actionsleft {
+  float: left;
+}
+
+.actionsright {
+  float: right;
+  text-align: right;
+}
+
+@media screen and (max-width: 800px) {
+  .actions {
+    padding-top: 120px;
+  }
+  .actionsleft, .actionsright {
+    float: none;
+    text-align: left;
+    margin-bottom: 1em;
+  }
+}
+
+th {
+  text-decoration: underline;
+  font-weight: normal;
+  text-align: left;
+}
+
+#features ul {
+  list-style: none;
+  margin: 0 0 1em;
+  padding: 0 0 0 1.2em;
+}
+
+#features li:before {
+  content: "-";
+  width: 1em;
+  display: inline-block;
+  padding: 0;
+  margin: 0;
+  margin-left: -1em;
+}
+
+.rel {
+  margin-bottom: 0;
+}
+.rel-note {
+  margin-top: 0;
+  color: #555;
+}
+
+pre {
+  padding-left: 15px;
+  border-left: 2px solid #ddd;
+}
+
+code {
+  padding: 0 2px;
+}
+
+strong {
+  text-decoration: underline;
+  font-weight: normal;
+}
+
+.field {
+  border: 1px solid #A21313;
+}

codemirror/doc/internals.html

@@ -0,0 +1,504 @@
+<!doctype html>
+
+<title>CodeMirror: Internals</title>
+<meta charset="utf-8"/>
+<link rel=stylesheet href="docs.css">
+<style>dl dl {margin: 0;} .update {color: #d40 !important}</style>
+<script src="activebookmark.js"></script>
+
+<div id=nav>
+  <a href="https://codemirror.net"><h1>CodeMirror</h1><img id=logo src="logo.png"></a>
+
+  <ul>
+    <li><a href="../index.html">Home</a>
+    <li><a href="manual.html">Manual</a>
+    <li><a href="https://github.com/codemirror/codemirror">Code</a>
+  </ul>
+  <ul>
+    <li><a href="#top">Introduction</a></li>
+    <li><a href="#approach">General Approach</a></li>
+    <li><a href="#input">Input</a></li>
+    <li><a href="#selection">Selection</a></li>
+    <li><a href="#update">Intelligent Updating</a></li>
+    <li><a href="#parse">Parsing</a></li>
+    <li><a href="#summary">What Gives?</a></li>
+    <li><a href="#btree">Content Representation</a></li>
+    <li><a href="#keymap">Key Maps</a></li>
+  </ul>
+</div>
+
+<article>
+
+<h2 id=top>(Re-) Implementing A Syntax-Highlighting Editor in JavaScript</h2>
+
+<p style="font-size: 85%" id="intro">
+  <strong>Topic:</strong> JavaScript, code editor implementation<br>
+  <strong>Author:</strong> Marijn Haverbeke<br>
+  <strong>Date:</strong> March 2nd 2011 (updated November 13th 2011)
+</p>
+
+<p style="padding: 0 3em 0 2em"><strong>Caution</strong>: this text was written briefly after
+version 2 was initially written. It no longer (even including the
+update at the bottom) fully represents the current implementation. I'm
+leaving it here as a historic document. For more up-to-date
+information, look at the entries
+tagged <a href="http://marijnhaverbeke.nl/blog/#cm-internals">cm-internals</a>
+on my blog.</p>
+
+<p>This is a followup to
+my <a href="https://codemirror.net/story.html">Brutal Odyssey to the
+Dark Side of the DOM Tree</a> story. That one describes the
+mind-bending process of implementing (what would become) CodeMirror 1.
+This one describes the internals of CodeMirror 2, a complete rewrite
+and rethink of the old code base. I wanted to give this piece another
+Hunter Thompson copycat subtitle, but somehow that would be out of
+place—the process this time around was one of straightforward
+engineering, requiring no serious mind-bending whatsoever.</p>
+
+<p>So, what is wrong with CodeMirror 1? I'd estimate, by mailing list
+activity and general search-engine presence, that it has been
+integrated into about a thousand systems by now. The most prominent
+one, since a few weeks,
+being <a href="http://googlecode.blogspot.com/2011/01/make-quick-fixes-quicker-on-google.html">Google
+code's project hosting</a>. It works, and it's being used widely.</p>
+
+<p>Still, I did not start replacing it because I was bored. CodeMirror
+1 was heavily reliant on <code>designMode</code>
+or <code>contentEditable</code> (depending on the browser). Neither of
+these are well specified (HTML5 tries
+to <a href="http://www.w3.org/TR/html5/editing.html#contenteditable">specify</a>
+their basics), and, more importantly, they tend to be one of the more
+obscure and buggy areas of browser functionality—CodeMirror, by using
+this functionality in a non-typical way, was constantly running up
+against browser bugs. WebKit wouldn't show an empty line at the end of
+the document, and in some releases would suddenly get unbearably slow.
+Firefox would show the cursor in the wrong place. Internet Explorer
+would insist on linkifying everything that looked like a URL or email
+address, a behaviour that can't be turned off. Some bugs I managed to
+work around (which was often a frustrating, painful process), others,
+such as the Firefox cursor placement, I gave up on, and had to tell
+user after user that they were known problems, but not something I
+could help.</p>
+
+<p>Also, there is the fact that <code>designMode</code> (which seemed
+to be less buggy than <code>contentEditable</code> in Webkit and
+Firefox, and was thus used by CodeMirror 1 in those browsers) requires
+a frame. Frames are another tricky area. It takes some effort to
+prevent getting tripped up by domain restrictions, they don't
+initialize synchronously, behave strangely in response to the back
+button, and, on several browsers, can't be moved around the DOM
+without having them re-initialize. They did provide a very nice way to
+namespace the library, though—CodeMirror 1 could freely pollute the
+namespace inside the frame.</p>
+
+<p>Finally, working with an editable document means working with
+selection in arbitrary DOM structures. Internet Explorer (8 and
+before) has an utterly different (and awkward) selection API than all
+of the other browsers, and even among the different implementations of
+<code>document.selection</code>, details about how exactly a selection
+is represented vary quite a bit. Add to that the fact that Opera's
+selection support tended to be very buggy until recently, and you can
+imagine why CodeMirror 1 contains 700 lines of selection-handling
+code.</p>
+
+<p>And that brings us to the main issue with the CodeMirror 1
+code base: The proportion of browser-bug-workarounds to real
+application code was getting dangerously high. By building on top of a
+few dodgy features, I put the system in a vulnerable position—any
+incompatibility and bugginess in these features, I had to paper over
+with my own code. Not only did I have to do some serious stunt-work to
+get it to work on older browsers (as detailed in the
+previous <a href="https://codemirror.net/story.html">story</a>), things
+also kept breaking in newly released versions, requiring me to come up
+with <em>new</em> scary hacks in order to keep up. This was starting
+to lose its appeal.</p>
+
+<section id=approach>
+  <h2>General Approach</h2>
+
+<p>What CodeMirror 2 does is try to sidestep most of the hairy hacks
+that came up in version 1. I owe a lot to the
+<a href="http://ace.ajax.org">ACE</a> editor for inspiration on how to
+approach this.</p>
+
+<p>I absolutely did not want to be completely reliant on key events to
+generate my input. Every JavaScript programmer knows that key event
+information is horrible and incomplete. Some people (most awesomely
+Mihai Bazon with <a href="http://ymacs.org">Ymacs</a>) have been able
+to build more or less functioning editors by directly reading key
+events, but it takes a lot of work (the kind of never-ending, fragile
+work I described earlier), and will never be able to properly support
+things like multi-keystoke international character
+input. <a href="#keymap" class="update">[see below for caveat]</a></p>
+
+<p>So what I do is focus a hidden textarea, and let the browser
+believe that the user is typing into that. What we show to the user is
+a DOM structure we built to represent his document. If this is updated
+quickly enough, and shows some kind of believable cursor, it feels
+like a real text-input control.</p>
+
+<p>Another big win is that this DOM representation does not have to
+span the whole document. Some CodeMirror 1 users insisted that they
+needed to put a 30 thousand line XML document into CodeMirror. Putting
+all that into the DOM takes a while, especially since, for some
+reason, an editable DOM tree is slower than a normal one on most
+browsers. If we have full control over what we show, we must only
+ensure that the visible part of the document has been added, and can
+do the rest only when needed. (Fortunately, the <code>onscroll</code>
+event works almost the same on all browsers, and lends itself well to
+displaying things only as they are scrolled into view.)</p>
+</section>
+<section id="input">
+  <h2>Input</h2>
+
+<p>ACE uses its hidden textarea only as a text input shim, and does
+all cursor movement and things like text deletion itself by directly
+handling key events. CodeMirror's way is to let the browser do its
+thing as much as possible, and not, for example, define its own set of
+key bindings. One way to do this would have been to have the whole
+document inside the hidden textarea, and after each key event update
+the display DOM to reflect what's in that textarea.</p>
+
+<p>That'd be simple, but it is not realistic. For even medium-sized
+document the editor would be constantly munging huge strings, and get
+terribly slow. What CodeMirror 2 does is put the current selection,
+along with an extra line on the top and on the bottom, into the
+textarea.</p>
+
+<p>This means that the arrow keys (and their ctrl-variations), home,
+end, etcetera, do not have to be handled specially. We just read the
+cursor position in the textarea, and update our cursor to match it.
+Also, copy and paste work pretty much for free, and people get their
+native key bindings, without any special work on my part. For example,
+I have emacs key bindings configured for Chrome and Firefox. There is
+no way for a script to detect this. <a class="update"
+href="#keymap">[no longer the case]</a></p>
+
+<p>Of course, since only a small part of the document sits in the
+textarea, keys like page up and ctrl-end won't do the right thing.
+CodeMirror is catching those events and handling them itself.</p>
+</section>
+<section id="selection">
+  <h2>Selection</h2>
+
+<p>Getting and setting the selection range of a textarea in modern
+browsers is trivial—you just use the <code>selectionStart</code>
+and <code>selectionEnd</code> properties. On IE you have to do some
+insane stuff with temporary ranges and compensating for the fact that
+moving the selection by a 'character' will treat \r\n as a single
+character, but even there it is possible to build functions that
+reliably set and get the selection range.</p>
+
+<p>But consider this typical case: When I'm somewhere in my document,
+press shift, and press the up arrow, something gets selected. Then, if
+I, still holding shift, press the up arrow again, the top of my
+selection is adjusted. The selection remembers where its <em>head</em>
+and its <em>anchor</em> are, and moves the head when we shift-move.
+This is a generally accepted property of selections, and done right by
+every editing component built in the past twenty years.</p>
+
+<p>But not something that the browser selection APIs expose.</p>
+
+<p>Great. So when someone creates an 'upside-down' selection, the next
+time CodeMirror has to update the textarea, it'll re-create the
+selection as an 'upside-up' selection, with the anchor at the top, and
+the next cursor motion will behave in an unexpected way—our second
+up-arrow press in the example above will not do anything, since it is
+interpreted in exactly the same way as the first.</p>
+
+<p>No problem. We'll just, ehm, detect that the selection is
+upside-down (you can tell by the way it was created), and then, when
+an upside-down selection is present, and a cursor-moving key is
+pressed in combination with shift, we quickly collapse the selection
+in the textarea to its start, allow the key to take effect, and then
+combine its new head with its old anchor to get the <em>real</em>
+selection.</p>
+
+<p>In short, scary hacks could not be avoided entirely in CodeMirror
+2.</p>
+
+<p>And, the observant reader might ask, how do you even know that a
+key combo is a cursor-moving combo, if you claim you support any
+native key bindings? Well, we don't, but we can learn. The editor
+keeps a set known cursor-movement combos (initialized to the
+predictable defaults), and updates this set when it observes that
+pressing a certain key had (only) the effect of moving the cursor.
+This, of course, doesn't work if the first time the key is used was
+for extending an inverted selection, but it works most of the
+time.</p>
+</section>
+<section id="update">
+  <h2>Intelligent Updating</h2>
+
+<p>One thing that always comes up when you have a complicated internal
+state that's reflected in some user-visible external representation
+(in this case, the displayed code and the textarea's content) is
+keeping the two in sync. The naive way is to just update the display
+every time you change your state, but this is not only error prone
+(you'll forget), it also easily leads to duplicate work on big,
+composite operations. Then you start passing around flags indicating
+whether the display should be updated in an attempt to be efficient
+again and, well, at that point you might as well give up completely.</p>
+
+<p>I did go down that road, but then switched to a much simpler model:
+simply keep track of all the things that have been changed during an
+action, and then, only at the end, use this information to update the
+user-visible display.</p>
+
+<p>CodeMirror uses a concept of <em>operations</em>, which start by
+calling a specific set-up function that clears the state and end by
+calling another function that reads this state and does the required
+updating. Most event handlers, and all the user-visible methods that
+change state are wrapped like this. There's a method
+called <code>operation</code> that accepts a function, and returns
+another function that wraps the given function as an operation.</p>
+
+<p>It's trivial to extend this (as CodeMirror does) to detect nesting,
+and, when an operation is started inside an operation, simply
+increment the nesting count, and only do the updating when this count
+reaches zero again.</p>
+
+<p>If we have a set of changed ranges and know the currently shown
+range, we can (with some awkward code to deal with the fact that
+changes can add and remove lines, so we're dealing with a changing
+coordinate system) construct a map of the ranges that were left
+intact. We can then compare this map with the part of the document
+that's currently visible (based on scroll offset and editor height) to
+determine whether something needs to be updated.</p>
+
+<p>CodeMirror uses two update algorithms—a full refresh, where it just
+discards the whole part of the DOM that contains the edited text and
+rebuilds it, and a patch algorithm, where it uses the information
+about changed and intact ranges to update only the out-of-date parts
+of the DOM. When more than 30 percent (which is the current heuristic,
+might change) of the lines need to be updated, the full refresh is
+chosen (since it's faster to do than painstakingly finding and
+updating all the changed lines), in the other case it does the
+patching (so that, if you scroll a line or select another character,
+the whole screen doesn't have to be
+re-rendered). <span class="update">[the full-refresh
+algorithm was dropped, it wasn't really faster than the patching
+one]</span></p>
+
+<p>All updating uses <code>innerHTML</code> rather than direct DOM
+manipulation, since that still seems to be by far the fastest way to
+build documents. There's a per-line function that combines the
+highlighting, <a href="manual.html#markText">marking</a>, and
+selection info for that line into a snippet of HTML. The patch updater
+uses this to reset individual lines, the refresh updater builds an
+HTML chunk for the whole visible document at once, and then uses a
+single <code>innerHTML</code> update to do the refresh.</p>
+</section>
+<section id="parse">
+  <h2>Parsers can be Simple</h2>
+
+<p>When I wrote CodeMirror 1, I
+thought <a href="https://codemirror.net/story.html#parser">interruptable
+parsers</a> were a hugely scary and complicated thing, and I used a
+bunch of heavyweight abstractions to keep this supposed complexity
+under control: parsers
+were <a href="http://bob.pythonmac.org/archives/2005/07/06/iteration-in-javascript/">iterators</a>
+that consumed input from another iterator, and used funny
+closure-resetting tricks to copy and resume themselves.</p>
+
+<p>This made for a rather nice system, in that parsers formed strictly
+separate modules, and could be composed in predictable ways.
+Unfortunately, it was quite slow (stacking three or four iterators on
+top of each other), and extremely intimidating to people not used to a
+functional programming style.</p>
+
+<p>With a few small changes, however, we can keep all those
+advantages, but simplify the API and make the whole thing less
+indirect and inefficient. CodeMirror
+2's <a href="manual.html#modeapi">mode API</a> uses explicit state
+objects, and makes the parser/tokenizer a function that simply takes a
+state and a character stream abstraction, advances the stream one
+token, and returns the way the token should be styled. This state may
+be copied, optionally in a mode-defined way, in order to be able to
+continue a parse at a given point. Even someone who's never touched a
+lambda in his life can understand this approach. Additionally, far
+fewer objects are allocated in the course of parsing now.</p>
+
+<p>The biggest speedup comes from the fact that the parsing no longer
+has to touch the DOM though. In CodeMirror 1, on an older browser, you
+could <em>see</em> the parser work its way through the document,
+managing some twenty lines in each 50-millisecond time slice it got. It
+was reading its input from the DOM, and updating the DOM as it went
+along, which any experienced JavaScript programmer will immediately
+spot as a recipe for slowness. In CodeMirror 2, the parser usually
+finishes the whole document in a single 100-millisecond time slice—it
+manages some 1500 lines during that time on Chrome. All it has to do
+is munge strings, so there is no real reason for it to be slow
+anymore.</p>
+</section>
+<section id="summary">
+  <h2>What Gives?</h2>
+
+<p>Given all this, what can you expect from CodeMirror 2?</p>
+
+<ul>
+
+<li><strong>Small.</strong> the base library is
+some <span class="update">45k</span> when minified
+now, <span class="update">17k</span> when gzipped. It's smaller than
+its own logo.</li>
+
+<li><strong>Lightweight.</strong> CodeMirror 2 initializes very
+quickly, and does almost no work when it is not focused. This means
+you can treat it almost like a textarea, have multiple instances on a
+page without trouble.</li>
+
+<li><strong>Huge document support.</strong> Since highlighting is
+really fast, and no DOM structure is being built for non-visible
+content, you don't have to worry about locking up your browser when a
+user enters a megabyte-sized document.</li>
+
+<li><strong>Extended API.</strong> Some things kept coming up in the
+mailing list, such as marking pieces of text or lines, which were
+extremely hard to do with CodeMirror 1. The new version has proper
+support for these built in.</li>
+
+<li><strong>Tab support.</strong> Tabs inside editable documents were,
+for some reason, a no-go. At least six different people announced they
+were going to add tab support to CodeMirror 1, none survived (I mean,
+none delivered a working version). CodeMirror 2 no longer removes tabs
+from your document.</li>
+
+<li><strong>Sane styling.</strong> <code>iframe</code> nodes aren't
+really known for respecting document flow. Now that an editor instance
+is a plain <code>div</code> element, it is much easier to size it to
+fit the surrounding elements. You don't even have to make it scroll if
+you do not <a href="../demo/resize.html">want to</a>.</li>
+
+</ul>
+
+<p>On the downside, a CodeMirror 2 instance is <em>not</em> a native
+editable component. Though it does its best to emulate such a
+component as much as possible, there is functionality that browsers
+just do not allow us to hook into. Doing select-all from the context
+menu, for example, is not currently detected by CodeMirror.</p>
+
+<p id="changes" style="margin-top: 2em;"><span style="font-weight:
+bold">[Updates from November 13th 2011]</span> Recently, I've made
+some changes to the codebase that cause some of the text above to no
+longer be current. I've left the text intact, but added markers at the
+passages that are now inaccurate. The new situation is described
+below.</p>
+</section>
+<section id="btree">
+  <h2>Content Representation</h2>
+
+<p>The original implementation of CodeMirror 2 represented the
+document as a flat array of line objects. This worked well—splicing
+arrays will require the part of the array after the splice to be
+moved, but this is basically just a simple <code>memmove</code> of a
+bunch of pointers, so it is cheap even for huge documents.</p>
+
+<p>However, I recently added line wrapping and code folding (line
+collapsing, basically). Once lines start taking up a non-constant
+amount of vertical space, looking up a line by vertical position
+(which is needed when someone clicks the document, and to determine
+the visible part of the document during scrolling) can only be done
+with a linear scan through the whole array, summing up line heights as
+you go. Seeing how I've been going out of my way to make big documents
+fast, this is not acceptable.</p>
+
+<p>The new representation is based on a B-tree. The leaves of the tree
+contain arrays of line objects, with a fixed minimum and maximum size,
+and the non-leaf nodes simply hold arrays of child nodes. Each node
+stores both the amount of lines that live below them and the vertical
+space taken up by these lines. This allows the tree to be indexed both
+by line number and by vertical position, and all access has
+logarithmic complexity in relation to the document size.</p>
+
+<p>I gave line objects and tree nodes parent pointers, to the node
+above them. When a line has to update its height, it can simply walk
+these pointers to the top of the tree, adding or subtracting the
+difference in height from each node it encounters. The parent pointers
+also make it cheaper (in complexity terms, the difference is probably
+tiny in normal-sized documents) to find the current line number when
+given a line object. In the old approach, the whole document array had
+to be searched. Now, we can just walk up the tree and count the sizes
+of the nodes coming before us at each level.</p>
+
+<p>I chose B-trees, not regular binary trees, mostly because they
+allow for very fast bulk insertions and deletions. When there is a big
+change to a document, it typically involves adding, deleting, or
+replacing a chunk of subsequent lines. In a regular balanced tree, all
+these inserts or deletes would have to be done separately, which could
+be really expensive. In a B-tree, to insert a chunk, you just walk
+down the tree once to find where it should go, insert them all in one
+shot, and then break up the node if needed. This breaking up might
+involve breaking up nodes further up, but only requires a single pass
+back up the tree. For deletion, I'm somewhat lax in keeping things
+balanced—I just collapse nodes into a leaf when their child count goes
+below a given number. This means that there are some weird editing
+patterns that may result in a seriously unbalanced tree, but even such
+an unbalanced tree will perform well, unless you spend a day making
+strangely repeating edits to a really big document.</p>
+</section>
+<section id="keymap">
+  <h2>Keymaps</h2>
+
+<p><a href="#approach">Above</a>, I claimed that directly catching key
+events for things like cursor movement is impractical because it
+requires some browser-specific kludges. I then proceeded to explain
+some awful <a href="#selection">hacks</a> that were needed to make it
+possible for the selection changes to be detected through the
+textarea. In fact, the second hack is about as bad as the first.</p>
+
+<p>On top of that, in the presence of user-configurable tab sizes and
+collapsed and wrapped lines, lining up cursor movement in the textarea
+with what's visible on the screen becomes a nightmare. Thus, I've
+decided to move to a model where the textarea's selection is no longer
+depended on.</p>
+
+<p>So I moved to a model where all cursor movement is handled by my
+own code. This adds support for a goal column, proper interaction of
+cursor movement with collapsed lines, and makes it possible for
+vertical movement to move through wrapped lines properly, instead of
+just treating them like non-wrapped lines.</p>
+
+<p>The key event handlers now translate the key event into a string,
+something like <code>Ctrl-Home</code> or <code>Shift-Cmd-R</code>, and
+use that string to look up an action to perform. To make keybinding
+customizable, this lookup goes through
+a <a href="manual.html#option_keyMap">table</a>, using a scheme that
+allows such tables to be chained together (for example, the default
+Mac bindings fall through to a table named 'emacsy', which defines
+basic Emacs-style bindings like <code>Ctrl-F</code>, and which is also
+used by the custom Emacs bindings).</p>
+
+<p>A new
+option <a href="manual.html#option_extraKeys"><code>extraKeys</code></a>
+allows ad-hoc keybindings to be defined in a much nicer way than what
+was possible with the
+old <a href="manual.html#option_onKeyEvent"><code>onKeyEvent</code></a>
+callback. You simply provide an object mapping key identifiers to
+functions, instead of painstakingly looking at raw key events.</p>
+
+<p>Built-in commands map to strings, rather than functions, for
+example <code>"goLineUp"</code> is the default action bound to the up
+arrow key. This allows new keymaps to refer to them without
+duplicating any code. New commands can be defined by assigning to
+the <code>CodeMirror.commands</code> object, which maps such commands
+to functions.</p>
+
+<p>The hidden textarea now only holds the current selection, with no
+extra characters around it. This has a nice advantage: polling for
+input becomes much, much faster. If there's a big selection, this text
+does not have to be read from the textarea every time—when we poll,
+just noticing that something is still selected is enough to tell us
+that no new text was typed.</p>
+
+<p>The reason that cheap polling is important is that many browsers do
+not fire useful events on IME (input method engine) input, which is
+the thing where people inputting a language like Japanese or Chinese
+use multiple keystrokes to create a character or sequence of
+characters. Most modern browsers fire <code>input</code> when the
+composing is finished, but many don't fire anything when the character
+is updated <em>during</em> composition. So we poll, whenever the
+editor is focused, to provide immediate updates of the display.</p>
+
+</section>
+</article>

codemirror/doc/logo.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="640">
+  <path d="M292.4 53.2s8.7 18.6-3.6 39.2c-6.2 10.2-163.1 43.6-224.3 128.6-37.5 58.7-95 228.7 88.7 341.2 82.5 42.5 117.5 41.2 117.5 41.2s-55-38.7-20-65 86.2-38.7 100-75c16.2 12.5 42.5 38.7 67.5 36.2-2.5-16.2-8.7-22.5 11.2-25s30-2.5 30-2.5-18.7-15-40-16.2-61.2-42.5-60-60c26.2-15 60-40 80-32.5s40 20 43.7 31.2c0 7.5-3.7 20 12.5 10s12.5-16.2 18.7-30 7.5-16.2-6.2-27.5-46.2-37.5-72.5-30-81.2 28.7-108.7 2.5c11.2-25 28.7-65 20-92.5 16.2-12.5 35-26.2 37.5-48.7 18.7-2.5 58.7-13.7 51.2-33.7S374.9 36.0 293.6 53.5" fill="#fff"/>
+  <path d="M551.9 257.4c13.7-36.2 36.2-97.5 15-100s-45 55-51.2 70-31.2 90-17.5 100 53.7-70 53.7-70" fill="#fff"/>
+  <path d="M435.6 159.9c3.9-6.1 7.2-.8-9.6.4-16.8 1.2-37.0 6.4-40.4 13.8-6.4 13.7-8.6 47.6-33.0 55.1-1.2 8.7 0 28.7 34.3 32.5s35.6-18.7 55.6-18.1 18.1-6.8 11.2-12.5-30.6-43.7-30.6-56.2 8.1-8.1 12.5-15M128.7 536.8s-10.6-28.1 20.6-43.1 59.3-3.1 65 7.5-9.3 53.1-63.1 53.7c-13.1-10.6-22.5-18.1-22.5-18.1" fill="#da687d"/>
+  <g opacity=".7" transform="matrix(1.25 0 0 -1.25 -26.846 640)">
+    <path d="M466.2 369.8c.4-1.5.2-3.1.2-4.8-.0-1.6-.1-3.3-.6-4.9.1-.3-.0-.8-.0-1.2-.4-.5-.1-.9-.2-1.3.6-.6 1.5-1.3 1.1-2.1-.2-.5-.8-.7-1.4-.9-.3-1.4-.7-3.0-1.0-4.6-.0-.4-.0-1.0-.1-1.4-.3-1.0-.6-1.9-.9-3.0-.2-.9.0-2.6-1.0-2.8-.4-1.0-.6-1.8-1.1-2.8-.2-.1-.4.1-.6.0-.3-.3-.2-.8-.5-1.1-.2-.2-.5-.1-.6-.3-.3-.5-.2-1.2-.5-1.9a4.7 4.7 0 0 1-1.1-1.4c-.5-1.1-.6-2.6-1.5-3.5-.2-.2-.7-.3-1.0-.6-.2-.2-.4-.6-.6-.9-.3-.4-.6-1.0-.9-1.5-1.0-1.7-2.3-3.7-3.3-5.6-.1-.3-.2-.8-.3-1.1-.3-.8-.9-1.5-1.2-2.3-.5-1.2-1.3-3.3-2.5-4.4-.1-.1-.4-.2-.6-.4-.1-.2-.1-.5-.3-.8-.0-.1-.4-.1-.5-.3-.2-.2-.3-.4-.4-.6-.4-.3-1.0-.5-1.3-.9-.2-.3-.3-.7-.6-1.1-.3-.4-.7-.7-1.0-1.2-.9-1.2-1.3-2.8-2.7-3.3-.3-.1-.8-.1-1.2-.2-.3.3-.0.8-.1 1.1-.0.2-.2.3-.3.5-.1.4-.3 1.3-.3 1.8.0.5.3.9.3 1.6.0.5-.1 1.2-.1 1.8-.0.3.0.6.0.9-.0.5-.0.8.0 1.4.0.7-.0 1.4-.1 2.1.3 1.7.5 3.0 1.0 4.9.2.8.7 2.3 1.1 3.3.8 1.8 1.6 3.9 2.6 5.9.3.6.8 1.1 1.1 1.8.1.3.2.8.3 1.2 1.6 3.3 3.8 6.2 5.5 9.7 1.4 2.8 2.8 5.4 4.7 8.5.8 1.4 1.5 2.9 2.4 4.0.6.8 1.6 2.4 2.3 3.9.2.5.2 1.0 1.0 1.1.7.9 1.3 2.0 2.1 2.8.2.2.5.3.7.4.2.2.3.5.6.7.5.4 1.4.8 2.0 1.6.1.2.2.4.4.6.4.5 1.1 1.8 1.8 2.0.0.0.2.0.3-.0" fill="#da687d"/>
+  </g>
+  <g opacity=".7" transform="matrix(1.25 0 0 -1.25 -26.846 640)">
+    <path d="M459.8 349.4c.6-1.9.7-4.1.9-6.2-.0-2.1-.1-4.5-.7-6.9.0-.4-.1-1.1-.1-1.6-.5-.7-.2-1.2-.4-1.8.7-.8 1.6-1.6 1.1-2.8-.3-.8-1.1-1.0-1.8-1.4-.6-1.9-1.2-4.2-1.8-6.3-.1-.6-.2-1.3-.4-1.9-.5-1.3-1.1-2.6-1.5-4.1-.4-1.2-.3-3.4-1.6-3.6-.6-1.3-.9-2.3-1.6-3.6-.3-.2-.5.1-.8-.0-.3-.4-.4-1.0-.7-1.4-.2-.2-.5-.2-.7-.5-.4-.6-.3-1.5-.7-2.4a6.5 6.5 0 0 1-1.1-1.3l-.1-.2-.0-.1-.0-.0-.0-.0v-.0l.0.1-.0-.0-.0-.0-.0-.0-.0-.0-.0-.0c-.6-1.6-.8-3.6-1.8-4.9-.3-.4-.8-.5-1.1-.9-.2-.3-.4-.9-.7-1.3-.3-.6-.7-1.4-1.0-2.1-1.0-2.4-2.5-5.2-3.5-8.0-.1-.5-.2-1.1-.3-1.6-.4-1.1-1.0-2.2-1.3-3.3-.6-1.7-1.4-4.7-3.0-6.3-.1-.2-.5-.4-.7-.6-.2-.3-.1-.7-.4-1.1-.1-.1-.4-.2-.6-.4-.2-.3-.3-.6-.5-.9-.5-.5-1.2-.8-1.7-1.4-.3-.4-.5-1.0-.9-1.5-.4-.5-.9-1.1-1.4-1.6l-1.8-2.6c-.5-.8-1.2-1.5-2.0-1.8-.4-.2-1.0-.1-1.5-.2-.3.4.0 1.0.0 1.5-.0.2-.2.5-.2.7-.0.6-.1 1.7-.0 2.3.0.6.5 1.1.7 2.0.1.7-.0 1.5-.0 2.3.0.3.1.7.1 1.2.0.6-.0.9.1 1.7.1.9-.0 1.8-.1 2.7.4 2.1.6 3.8 1.2 6.3.2 1.1.7 3.1 1.2 4.4.4 1.3.9 2.6 1.3 4.0.4 1.4.9 2.8 1.4 4.2.3.9.8 1.7 1.2 2.7.2.5.2 1.1.4 1.7.4 1.2.9 2.5 1.5 3.6a147.5 147.5 0 0 0 1.7 3.3l.9 1.8c.3.5.6 1.1.9 1.7a75.5 75.5 0 0 1 1.8 3.6 129.6 129.6 0 0 0 3.1 5.7 340.1 340.1 0 0 0 3.6 5.8c1.1 1.8 2.2 3.8 3.3 5.3.8 1.1 2.1 3.1 3.0 5.1.3.7.3 1.3 1.1 1.4.9 1.2 1.6 2.6 2.4 3.7.2.2.5.4.8.7.2.3.4.7.6 1.0.5.6 1.6 1.2 2.2 2.5.1.3.1.6.3 1.0.3.8 1.0 2.7 1.7 3.1.0.0.2.0.3.0" fill="#da687d"/>
+  </g>
+  <path d="M520.8 231.2s-10 38.3-5.8 70l5.8-70m11.8-25.9c-.7-2.6-5.7 74.3-4.2 77.0 1.4 2.6 8.9-60.7 4.2-77.0" fill="#fff"/>
+  <path d="M294.0 57.9s5.8 33.2-48.3 50.7-128.8 32.4-183.8 98.3c-55 65.8-65 174.9-27.5 246.6 37.5 71.6 129.1 160.8 294.1 160.8S624.6 487.7 624.6 400.2c0-45.8-25.1-35.6-33.8 7.3-7.8 38.8-80.5 183.6-263.0 183.6-182.5 0-275.8-110.8-287.5-205.8-11.6-95 14.8-176.8 110.7-226.0 95.8-49.1 156.6-29.5 143.3-101.2" fill="#2d2b2c"/>
+  <path d="M248.5 314.5s-10.8 50.0-63.3 74.1c-52.5 24.1-75 37.5-82.5 79.1 20-33.3 78.3-40 110.8-72.5s35-80.8 35-80.8m14.1-115.8s45 58.3 98.3 30c53.3-28.3 25.8-94.1 25-98.3-.8-4.1 5.8 73.3-34.1 86.6-40 13.3-89.1-18.3-89.1-18.3M145.2 547.0s28.3 1.6 49.1-21.6c20.8-23.3 9.1-60 43.3-73.3 34.1-13.3 57.5-5 57.5-5s-60.8 8.3-65.8 43.3-13.3 50.8-26.6 61.6c-13.3 10.8-30.8 12.5-30.8 12.5l-26.6-17.5z" fill="#2d2b2c"/>
+  <path d="M273.7 365.6s50.6-8.4 73.7-60c18.9-42.2 6.2-78.7 6.2-78.7l-25.6 3.7s10.6 30.6 2.5 58.1-26.8 59.3-56.8 76.8m272.6-117.0c-18.0 45.1-44.7 77.5-47.8 75.8-5.6-3.1-.4-42.5 17.6-87.7 18.0-45.1 40.5-79.5 48.8-76.2 8.3 3.2-.6 42.9-18.6 88.1m26.2-90.6c-20.5-11.1-45.8 30.5-66.5 79.1-20.7 48.6-23.1 87.7-7.1 94.7 21.3 9.3 41.4-27.8 62.1-76.4s30-87.5 11.5-97.5" fill="#2d2b2c"/>
+  <path d="M199.4 402.9s12.9 38.7 77.5 30.8c60.8-7.5 86.9-30.9 124.1-54.1 26.6-16.6 25-9.1 28.3-8.3 3.3.8 18.3 10 34.1 8.3.8 8.3-7.4 1.6-10.8 9.1-1.6 5 12.6 28.5 33.3 25 34.1-5.8 24.5-20 31.2-35.8 6.6-15.8 11.2-24.1-22.0-46.6-25.8-23.3-40-17.4-52.5-17.4s-45 17.4-67.5 13.3-36.6-12.5-36.6-12.5l-14.9 16.6s27.4 20.8 59.1 13.3c31.6-7.5 55.0-31.6 82.5-19.1 27.5 12.5 32.8 20.8 41.2 27.0 9.5 7.0 10.4 14.5 3.7 21.2-6.6 6.6.0 11.6-4.1 19.1-4.1 7.5-25 10.8-25 10.8s22.8-29.3-5-31.6c-20-1.6-32.5-28.3-60.8-14.1-40.6 20.3-98.3 55-138.3 59.1-38.9 4.0-53.3-8.3-63.3-31.6-11.6 10-14.1 17.5-14.1 17.5" fill="#2d2b2c"/>
+  <path d="M342.7 411.2s28.3 15 20 47.5-45.8 55-70 65.8c-24.1 10.8-42.1 25.1-24.1 34.1 15 7.5 23.3-11.6 45-15 21.6-3.3 40.8 5 42.5 17.5-9.1-5-15.8-5-15.8-5s7.5 5 8.3 13.3c.8 8.3-.8 4.1-5.8 4.1-12.5 0-14.1-10.8-25-9.1-27.5 2.5-29.1 14.1-44.1 15.8-15 1.6-40-6.6-36.6-25.8 3.3-19.1 29.1-32.5 53.3-42.5 24.1-10 60.8-41.6 55.8-70-5-28.3-26.6-22.5-26.6-22.5l23.3-8.3zm71.0-235.9s11.8 5.9 19.3 35.9c5 10.8 11.6 19.5 17.5 22.0 5.8 2.5-2.5 5-6.6 4.1-4.1-.8-12.9-4.5-18.7.4s-20 18.3-40 15c-20-3.3-37.0-16.0-37.0-16.0s7.5 33.1 52.0 31.0c30.9-1.4 24.1-17.5 45-20.8 20.8-3.3 18.6-13.8 14.1-22.5-7.0-13.7-29.1-17.0-31.6-57.2-2.5-4.1-18.1.5-13.9 8.0m71.2 209.1c1.8 1.8-14.7 39.3-14.7 39.3s-3.3 9.1-12.2 5.9c-9.1-3.3-6.7-9.9-6.7-9.9l21.2-38.5s11.6 2.3 12.5 3.2m23.4-53.3l-4.1 12.5-13.6-10.4 3.6-7.9 14.1 5.8z" fill="#2d2b2c"/>
+  <path d="M356.0 403.7c-2.5 9.1 29.1 62.5 50.8 59.1 21.6-3.3 24.9 3.3 18.3 7.5-6.6 4.1-18.3 5.8-16.6 11.6 1.6 5.8 6.2 11.6-4.5 10-10.8-1.6-32.9-13.3-46.2-35.8-4.1 13.3-5.8 17.5-5.8 17.5s42.5 44.1 85.8 25.8c-7.5-5.8-28.3-4.1-10.8-14.1s30.8-13.3 39.1 2.5c4.1-.8 4.1-37.5-50.8-35-19.1-2.5-45-40-45-59.1-5 5-11.6.8-14.1 10m169.4-184.3s-10.9 32.8-6.3 60l6.3-60m11.2-19.4c-.5-2.0-5.0 57.2-4.0 59.2 1.0 2.0 7.3-46.6 4.0-59.2m-145.6-32.8s47.0-4.1 38.7-22.9c-25.1-56.5-72.9-89.5-161.2-86.2 50-20 92.5-17.5 133.3 17.5 20.4 17.5 29.8 38.8 37.1 55.1 11.6 26 8.2 28.4-4.6 35.7-15.7 8.8-42.7 3.2-43.3.8" fill="#2d2b2c"/>
+  <path d="M395.8 174.2s12.9 8.9 23.1 1.6c4.6-4.8 7.7-7.4-5.4-6.8l-16.1-.6c-11.1-2.2-10.9 1.1-1.5 5.8z" fill="#2d2b2c"/>
+</svg>

codemirror/doc/realworld.html

@@ -0,0 +1,192 @@
+<!doctype html>
+
+<title>CodeMirror: Real-world Uses</title>
+<meta charset="utf-8"/>
+<link rel=stylesheet href="docs.css">
+
+<div id=nav>
+  <a href="https://codemirror.net"><h1>CodeMirror</h1><img id=logo src="logo.png"></a>
+
+  <ul>
+    <li><a href="../index.html">Home</a>
+    <li><a href="manual.html">Manual</a>
+    <li><a href="https://github.com/codemirror/codemirror">Code</a>
+  </ul>
+  <ul>
+    <li><a class=active href="#">Real-world uses</a>
+  </ul>
+</div>
+
+<article>
+
+<h2>CodeMirror real-world uses</h2>
+
+    <p>Create a <a href="https://github.com/codemirror/codemirror">pull
+    request</a> if you'd like your project to be added to this list.</p>
+
+    <ul>
+      <li><a href="http://brackets.io">Adobe Brackets</a> (code editor)</li>
+      <li><a href="http://alm.tools">ALM Tools</a> (TypeScript powered IDE)</li>
+      <li><a href="http://amber-lang.net/">Amber</a> (JavaScript-based Smalltalk system)</li>
+      <li><a href="http://apeye.org/">APEye</a> (tool for testing &amp; documenting APIs)</li>
+      <li><a href="https://github.com/google/appengine-codiad">Appengine Codiad</a></li>
+      <li><a href="https://chrome.google.com/webstore/detail/better-text-viewer/lcaidopdffhfemoefoaadecppnjdknkc">Better Text Viewer</a> (plain text reader app for Chrome)</li>
+      <li><a href="http://blog.bitbucket.org/2013/05/14/edit-your-code-in-the-cloud-with-bitbucket/">Bitbucket</a> (code hosting)</li>
+      <li><a href="https://blogger.googleblog.com/2013/04/improvements-to-blogger-template-html.html">Blogger's theme editor</a></li>
+      <li><a href="http://bluegriffon.org/">BlueGriffon</a> (HTML editor)</li>
+      <li><a href="https://bnfplayground.pauliankline.com/">BNF Playground</a> (grammar workbench)</li>
+      <li><a href="https://github.com/isdampe/BosonEditorExperimental">Boson Editor</a> (code editor)</li>
+      <li><a href="http://cargocollective.com/">Cargo Collective</a> (creative publishing platform)</li>
+      <li><a href="https://developers.google.com/chrome-developer-tools/">Chrome DevTools</a></li>
+      <li><a href="http://clickhelp.co/">ClickHelp</a> (technical writing tool)</li>
+      <li><a href="https://electronjs.org/apps/colon">Colon</a> (A flexible text editor or IDE)</li>
+      <li><a href="http://code.world/">CodeWorld</a> (Haskell playground)</li>
+      <li><a href="http://complete-ly.appspot.com/playground/code.playground.html">Complete.ly playground</a></li>
+      <li><a href="https://codeanywhere.com/">Codeanywhere</a> (multi-platform cloud editor)</li>
+      <li><a href="http://drupal.org/project/cpn">Code per Node</a> (Drupal module)</li>
+      <li><a href="https://codebitt.com/">CodeBitt</a> (Code snippet sharing)</li>
+      <li><a href="http://www.codebugapp.com/">Codebug</a> (PHP Xdebug front-end)</li>
+      <li><a href="http://codefights.com/">CodeFights</a> (practice programming)</li>
+      <li><a href="https://github.com/angelozerr/CodeMirror-Eclipse">CodeMirror Eclipse</a> (embed CM in Eclipse)</li>
+      <li><a href="http://emmet.io/blog/codemirror-movie/">CodeMirror movie</a> (scripted editing demos)</li>
+      <li><a href="http://code.google.com/p/codemirror2-gwt/">CodeMirror2-GWT</a> (Google Web Toolkit wrapper)</li>
+      <li><a href="http://www.crunchzilla.com/code-monster">Code Monster</a> & <a href="http://www.crunchzilla.com/code-maven">Code Maven</a> (learning environment)</li>
+      <li><a href="http://codepen.io">Codepen</a> (gallery of animations)</li>
+      <li><a href="https://coderpad.io/">Coderpad</a> (interviewing tool)</li>
+      <li><a href="http://sasstwo.codeschool.com/levels/1/challenges/1">Code School</a> (online tech learning environment)</li>
+      <li><a href="http://code-snippets.bungeshea.com/">Code Snippets</a> (WordPress snippet management plugin)</li>
+      <li><a href="http://antonmi.github.io/code_together/">Code together</a> (collaborative editing)</li>
+      <li><a href="http://codev.it/">Codev</a> (collaborative IDE)</li>
+      <li><a href="https://www.codevolve.com/">Codevolve</a> (programming lessons as-a-service)</li>
+      <li><a href="http://www.codezample.com">CodeZample</a> (code snippet sharing)</li>
+      <li><a href="http://codio.com">Codio</a> (Web IDE)</li>
+      <li><a href="https://www.codiva.io/">Codiva.io</a> (Online Java Compiler and IDE with auto-completion and error highlighting)</li>
+      <li><a href="http://www.communitycodecamp.com/">Community Code Camp</a> (code snippet sharing)</li>
+      <li><a href="http://www.compilejava.net/">compilejava.net</a> (online Java sandbox)</li>
+      <li><a href="http://www.ckwnc.com/">CKWNC</a> (UML editor)</li>
+      <li><a href="http://www.crossui.com/">CrossUI</a> (cross-platform UI builder)</li>
+      <li><a href="http://rsnous.com/cruncher/">Cruncher</a> (notepad with calculation features)</li>
+      <li><a href="http://www.crudzilla.com/">Crudzilla</a> (self-hosted web IDE)</li>
+      <li><a href="http://cssdeck.com/">CSSDeck</a> (CSS showcase)</li>
+      <li><a href="http://ireneros.com/deck/deck.js-codemirror/introduction/#textarea-code">Deck.js integration</a> (slides with editors)</li>
+      <li><a href="http://www.dbninja.com">DbNinja</a> (MySQL access interface)</li>
+      <li><a href="http://www.ecsspert.com/">eCSSpert</a> (CSS demos and experiments)</li>
+      <li><a href="https://edabit.com">Edabit</a> (coding challenges)</li>
+      <li><a href="http://elm-lang.org/Examples.elm">Elm language examples</a></li>
+      <li><a href="http://eloquentjavascript.net/chapter1.html">Eloquent JavaScript</a> (book)</li>
+      <li><a href="http://emmet.io">Emmet</a> (fast XML editing)</li>
+      <li><a href="https://github.com/espruino/EspruinoWebIDE">Espruino Web IDE</a> (Chrome App for writing code on Espruino devices)</li>
+      <li><a href="http://www.fastfig.com/">Fastfig</a> (online computation/math tool)</li>
+      <li><a href="https://metacpan.org/module/Farabi">Farabi</a> (modern Perl IDE)</li>
+      <li><a href="http://blog.pamelafox.org/2012/02/interactive-html5-slides-with-fathomjs.html">FathomJS integration</a> (slides with editors, again)</li>
+      <li><a href="http://fiddlesalad.com/">Fiddle Salad</a> (web development environment)</li>
+      <li><a href="https://github.com/simogeo/Filemanager">Filemanager</a></li>
+      <li><a href="https://hacks.mozilla.org/2013/11/firefox-developer-tools-episode-27-edit-as-html-codemirror-more/">Firefox Developer Tools</a></li>
+      <li><a href="http://www.firepad.io">Firepad</a> (collaborative text editor)</li>
+      <li><a href="https://gerritcodereview.com/">Gerrit</a>'s diff view and inline editor</li>
+      <li><a href="https://github.com/maks/git-crx">Git Crx</a> (Chrome App for browsing local git repos)</li>
+      <li><a href="https://github.com/github/android">GitHub's Android app</a></li>
+      <li><a href="https://github.com/">Github</a>'s in-browser edit feature</li>
+      <li><a href="https://glitch.com/">Glitch</a> (community-driven app building)</li>
+      <li><a href="http://tour.golang.org">Go language tour</a></li>
+      <li><a href="https://script.google.com/">Google Apps Script</a></li>
+      <li><a href="http://web.uvic.ca/~siefkenj/graphit/graphit.html">Graphit</a> (function graphing)</li>
+      <li><a href="https://hackmd.io">HackMD</a> (Realtime collaborative markdown notes on all platforms)</li>
+      <li><a href="http://www.handcraft.com/">Handcraft</a> (HTML prototyping)</li>
+      <li><a href="http://hawkee.com/">Hawkee</a></li>
+      <li><a href="http://try.haxe.org">Haxe</a> (Haxe Playground) </li>
+      <li><a href="http://haxpad.com/">HaxPad</a> (editor for Win RT)</li>
+      <li><a href="http://megafonweblab.github.com/histone-javascript/">Histone template engine playground</a></li>
+      <li><a href="http://www.homegenie.it/docs/automation_getstarted.php">Homegenie</a> (home automation server)</li>
+      <li><a href="http://icecoder.net">ICEcoder</a> (web IDE)</li>
+      <li><a href="http://ipython.org/">IPython</a> (interactive computing shell)</li>
+      <li><a href="https://joelpinheiro.github.io/itrading/">iTrading</a> (Algorithmic Trading)</li>
+      <li><a href="http://i-mos.org/imos/">i-MOS</a> (modeling and simulation platform)</li>
+      <li><a href="http://www.janvas.com/">Janvas</a> (vector graphics editor)</li>
+      <li><a href="https://code.wetrafa.xyz/">JdBEdit</a> (web IDE)</li>
+      <li><a href="http://extensions.joomla.org/extensions/edition/editors/8723">Joomla plugin</a></li>
+      <li><a href="http://jqfundamentals.com/">jQuery fundamentals</a> (interactive tutorial)</li>
+      <li><a href="http://jsbin.com">jsbin.com</a> (JS playground)</li>
+      <li><a href="http://tool.jser.com/preprocessor">JSER preprocessor</a></li>
+      <li><a href="https://github.com/kucherenko/jscpd">jscpd</a> (code duplication detector)</li>
+      <li><a href="http://jsfiddle.net">JSFiddle</a> (another JS playground)</li>
+      <li><a href="http://www.jshint.com/">JSHint</a> (JS linter)</li>
+      <li><a href="http://jumpseller.com/">Jumpseller</a> (online store builder)</li>
+      <li><a href="http://kl1p.com/cmtest/1">kl1p</a> (paste service)</li>
+      <li><a href="http://www.kodhus.com/kodity/">Kodit</a></li>
+      <li><a href="http://kodtest.com/">Kodtest</a> (HTML/JS/CSS playground)</li>
+      <li><a href="http://try.kotlinlang.org">Kotlin</a> (web-based mini-IDE for Kotlin)</li>
+      <li><a href="http://lighttable.com/">Light Table</a> (experimental IDE)</li>
+      <li><a href="http://liveweave.com/">Liveweave</a> (HTML/CSS/JS scratchpad)</li>
+      <li><a href="https://github.com/TuvaLabs/markdown-delight-editor">Markdown Delight Editor</a> (extensible markdown editor polymer component)</li>
+      <li><a href="http://marklighteditor.com/">Marklight editor</a> (lightweight markup editor)</li>
+      <li><a href="http://www.mergely.com/">Mergely</a> (interactive diffing)</li>
+      <li><a href="http://www.iunbug.com/mihtool">MIHTool</a> (iOS web-app debugging tool)</li>
+      <li><a href="http://mscgen.js.org/index.html">mscgen_js</a> (online sequence chart editor)</li>
+      <li><a href="http://mvcplayground.apphb.com/">MVC Playground</a></li>
+      <li><a href="http://www.navigatecms.com">Navigate CMS</a></li>
+      <li><a href="https://github.com/soliton4/nodeMirror">nodeMirror</a> (IDE project)</li>
+      <li><a href="https://notex.ch">NoTex</a> (rST authoring)</li>
+      <li><a href="https://nteract.io">nteract</a> (interactive literate coding notebook)</li>
+      <li><a href="http://oakoutliner.com">Oak</a> (online outliner)</li>
+      <li><a href="http://www.greycampus.com/opencampus">OpenCampus</a></li>
+      <li><a href="http://clrhome.org/asm/">ORG</a> (z80 assembly IDE)</li>
+      <li><a href="https://github.com/mamacdon/orion-codemirror">Orion-CodeMirror integration</a> (running CodeMirror modes in Orion)</li>
+      <li><a href="http://paperjs.org/">Paper.js</a> (graphics scripting)</li>
+      <li><a href="http://pharaoh.js.org/">Pharaoh</a> (browser &amp; desktop editor for the classroom)</li>
+      <li><a href="http://prinbit.com/">PrinBit</a> (collaborative coding tool)</li>
+      <li><a href="https://www.pramp.com/ref/codemirror">Pramp</a> (free platform to practice mock interviews and coding problems)</li>
+      <li><a href="http://prose.io/">Prose.io</a> (github content editor)</li>
+      <li><a href="https://pypi.python.org/pypi/PubliForge/">PubliForge</a> (online publishing system)</li>
+      <li><a href="http://www.puzzlescript.net/">Puzzlescript</a> (puzzle game engine)</li>
+      <li><a href="https://chrome.google.com/webstore/detail/quantum/hmnlklahndgbhdoclhdnoafhafbhmnkm?hl=en-US">Quantum</a> (code editor for Chrome OS)</li>
+      <li><a href="http://ariya.ofilabs.com/2011/09/hybrid-webnative-desktop-codemirror.html">Qt+Webkit integration</a> (building a desktop CodeMirror app)</li>
+      <li><a href="http://www.quivive-file-manager.com">Quivive File Manager</a></li>
+      <li><a href="http://rascalmicro.com/docs/basic-tutorial-getting-started.html">Rascal</a> (tiny computer)</li>
+      <li><a href="https://www.realtime.io/">RealTime.io</a> (Internet-of-Things infrastructure)</li>
+      <li><a href="http://refork.com/">Refork</a> (animation demo gallery and sharing)</li>
+      <li><a href="http://sagecell.sagemath.org">SageMathCell</a> (interactive mathematical software)</li>
+      <li><a href="https://cloud.sagemath.com/">SageMathCloud</a> (interactive mathematical software environment)</li>
+      <li><a href="https://github.com/szekelymilan/salvare">salvare</a> (real-time collaborative code editor)</li>
+      <li><a href="https://chrome.google.com/webstore/detail/servephp/mnpikomdchjhkhbhmbboehfdjkobbfpo">ServePHP</a> (PHP code testing in Chrome dev tools)</li>
+      <li><a href="http://scala-lang.org/blog/2017/02/20/introducing-scastie.html">Scastie</a> (Scala playground)</li>
+      <li><a href="https://www.shadertoy.com/">Shadertoy</a> (shader sharing)</li>
+      <li><a href="http://www.sketchpatch.net/labs/livecodelabIntro.html">sketchPatch Livecodelab</a></li>
+      <li><a href="http://www.skulpt.org/">Skulpt</a> (in-browser Python environment)</li>
+      <li><a href="https://www.sourcelair.com">SourceLair</a> (in-browser IDE for Django, Node.js, PHP and HTML5)</li>
+      <li><a href="http://snaptomato.appspot.com/editor.html">Snap Tomato</a> (HTML editing/testing page)</li>
+      <li><a href="http://snippets.pro/">Snippets.pro</a> (code snippet sharing)</li>
+      <li><a href="http://www.solidshops.com/">SolidShops</a> (hosted e-commerce platform)</li>
+      <li><a href="http://www.cemetech.net/sc/">SourceCoder 3</a> (online calculator IDE and editor)</li>
+      <li><a href="http://sqlfiddle.com">SQLFiddle</a> (SQL playground)</li>
+      <li><a href="http://www.subte.org/page/programar-ta-te-ti-online/">SubTe</a> (AI bot programming environment)</li>
+      <li><a href="http://xuanji.appspot.com/isicp/">Structure and Interpretation of Computer Programs</a>, Interactive Version</li>
+      <li><a href="http://syframework.alwaysdata.net">SyBox</a> (PHP playground)</li>
+      <li><a href="http://www.tagspaces.org/">TagSpaces</a> (personal data manager)</li>
+      <li><a href="https://textbox.io/">Textbox.io</a> (WYSIWYG rich text editor)</a></li>
+      <li><a href="https://thefiletree.com">The File Tree</a> (collab editor)</li>
+      <li><a href="http://www.mapbox.com/tilemill/">TileMill</a> (map design tool)</li>
+      <li><a href="http://doc.tiki.org/Syntax+Highlighter">Tiki</a> (wiki CMS groupware)</li>
+      <li><a href="http://www.toolsverse.com/products/data-explorer/">Toolsverse Data Explorer</a> (database management)</li>
+      <li><a href="http://blog.englard.net/post/39608000629/codeintumblr">Tumblr code highlighting shim</a></li>
+      <li><a href="http://turbopy.com/">TurboPY</a> (web publishing framework)</li>
+      <li><a href="http://cruise.eecs.uottawa.ca/umpleonline/">UmpleOnline</a> (model-oriented programming tool)</li>
+      <li><a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-7706e7832aa9e2fd0c2decdb5cbef2225692c696/platform/platform-impl/src/com/intellij/openapi/editor/impl/EditorFactoryImpl.java">Upsource</a> (code browser and review tool)</li>
+      <li><a href="https://github.com/mgaitan/waliki">Waliki</a> (wiki engine)</li>
+      <li><a href="http://wamer.net/">Wamer</a> (web application builder)</li>
+      <li><a href="https://github.com/brettz9/webappfind">webappfind</a> (windows file bindings for webapps)</li>
+      <li><a href="http://www.webglacademy.com/">WebGL academy</a> (learning WebGL)</li>
+      <li><a href="http://webglplayground.net/">WebGL playground</a></li>
+      <li><a href="https://www.webkit.org/blog/2518/state-of-web-inspector/#source-code">WebKit Web inspector</a></li>
+      <li><a href="http://www.wescheme.org/">WeScheme</a> (learning tool)</li>
+      <li><a href="https://github.com/b3log/wide">Wide</a> (golang web IDE)</li>
+      <li><a href="http://wordpress.org/extend/plugins/codemirror-for-codeeditor/">WordPress plugin</a></li>
+      <li><a href="https://www.writelatex.com">writeLaTeX</a> (Collaborative LaTeX Editor)</li>
+      <li><a href="http://www.xosystem.org/home/applications_websites/xosystem_website/xoside_EN.php">XOSide</a> (online editor)</li>
+      <li><a href="http://videlibri.sourceforge.net/cgi-bin/xidelcgi">XQuery tester</a></li>
+      <li><a href="http://q42jaap.github.io/xsd2codemirror/">xsd2codemirror</a> (convert XSD to CM XML completion info)</li>
+      <li><a href="http://www.yacas.org/yacas_online/yacas_online.html">Yacas Online</a> (interactive mathematical software)</li>
+    </ul>
+
+</article>
+

codemirror/doc/reporting.html

@@ -0,0 +1,60 @@
+<!doctype html>
+
+<title>CodeMirror: Reporting Bugs</title>
+<meta charset="utf-8"/>
+<link rel=stylesheet href="docs.css">
+
+<div id=nav>
+  <a href="https://codemirror.net"><h1>CodeMirror</h1><img id=logo src="logo.png"></a>
+
+  <ul>
+    <li><a href="../index.html">Home</a>
+    <li><a href="manual.html">Manual</a>
+    <li><a href="https://github.com/codemirror/codemirror">Code</a>
+  </ul>
+  <ul>
+    <li><a class=active href="#">Reporting bugs</a>
+  </ul>
+</div>
+
+<article>
+
+<h2>Reporting bugs effectively</h2>
+
+<div class="left">
+
+<p>So you found a problem in CodeMirror. By all means, report it! Bug
+reports from users are the main drive behind improvements to
+CodeMirror. But first, please read over these points:</p>
+
+<ol>
+  <li>CodeMirror is maintained by volunteers. They don't owe you
+  anything, so be polite. Reports with an indignant or belligerent
+  tone tend to be moved to the bottom of the pile.</li>
+
+  <li>Include information about <strong>the browser in which the
+  problem occurred</strong>. Even if you tested several browsers, and
+  the problem occurred in all of them, mention this fact in the bug
+  report. Also include browser version numbers and the operating
+  system that you're on.</li>
+
+  <li>Mention which release of CodeMirror you're using. Preferably,
+  try also with the current development snapshot, to ensure the
+  problem has not already been fixed.</li>
+
+  <li>Mention very precisely what went wrong. "X is broken" is not a
+  good bug report. What did you expect to happen? What happened
+  instead? Describe the exact steps a maintainer has to take to reproduce
+  the error. We can not fix something that we can not observe.</li>
+
+  <li>If the problem can not be reproduced in any of the demos
+  included in the CodeMirror distribution, please provide an HTML
+  document that demonstrates the problem. The best way to do this is
+  to go to <a href="http://jsbin.com/ihunin/1/edit">jsbin.com</a>, enter
+  it there, press save, and include the resulting link in your bug
+  report.</li>
+</ol>
+
+</div>
+
+</article>

codemirror/doc/upgrade_v2.2.html

@@ -0,0 +1,96 @@
+<!doctype html>
+
+<title>CodeMirror: Version 2.2 upgrade guide</title>
+<meta charset="utf-8"/>
+<link rel=stylesheet href="docs.css">
+
+<div id=nav>
+  <a href="https://codemirror.net"><h1>CodeMirror</h1><img id=logo src="logo.png"></a>
+
+  <ul>
+    <li><a href="../index.html">Home</a>
+    <li><a href="manual.html">Manual</a>
+    <li><a href="https://github.com/codemirror/codemirror">Code</a>
+  </ul>
+  <ul>
+    <li><a class=active href="#">2.2 upgrade guide</a>
+  </ul>
+</div>
+
+<article>
+
+<h2>Upgrading to v2.2</h2>
+
+<p>There are a few things in the 2.2 release that require some care
+when upgrading.</p>
+
+<h3>No more default.css</h3>
+
+<p>The default theme is now included
+in <a href="../lib/codemirror.css"><code>codemirror.css</code></a>, so
+you do not have to included it separately anymore. (It was tiny, so
+even if you're not using it, the extra data overhead is negligible.)
+
+<h3>Different key customization</h3>
+
+<p>CodeMirror has moved to a system
+where <a href="manual.html#option_keyMap">keymaps</a> are used to
+bind behavior to keys. This means <a href="../demo/emacs.html">custom
+bindings</a> are now possible.</p>
+
+<p>Three options that influenced key
+behavior, <code>tabMode</code>, <code>enterMode</code>,
+and <code>smartHome</code>, are no longer supported. Instead, you can
+provide custom bindings to influence the way these keys act. This is
+done through the
+new <a href="manual.html#option_extraKeys"><code>extraKeys</code></a>
+option, which can hold an object mapping key names to functionality. A
+simple example would be:</p>
+
+<pre>  extraKeys: {
+    "Ctrl-S": function(instance) { saveText(instance.getValue()); },
+    "Ctrl-/": "undo"
+  }</pre>
+
+<p>Keys can be mapped either to functions, which will be given the
+editor instance as argument, or to strings, which are mapped through
+functions through the <code>CodeMirror.commands</code> table, which
+contains all the built-in editing commands, and can be inspected and
+extended by external code.</p>
+
+<p>By default, the <code>Home</code> key is bound to
+the <code>"goLineStartSmart"</code> command, which moves the cursor to
+the first non-whitespace character on the line. You can set do this to
+make it always go to the very start instead:</p>
+
+<pre>  extraKeys: {"Home": "goLineStart"}</pre>
+
+<p>Similarly, <code>Enter</code> is bound
+to <code>"newlineAndIndent"</code> by default. You can bind it to
+something else to get different behavior. To disable special handling
+completely and only get a newline character inserted, you can bind it
+to <code>false</code>:</p>
+
+<pre>  extraKeys: {"Enter": false}</pre>
+
+<p>The same works for <code>Tab</code>. If you don't want CodeMirror
+to handle it, bind it to <code>false</code>. The default behaviour is
+to indent the current line more (<code>"indentMore"</code> command),
+and indent it less when shift is held (<code>"indentLess"</code>).
+There are also <code>"indentAuto"</code> (smart indent)
+and <code>"insertTab"</code> commands provided for alternate
+behaviors. Or you can write your own handler function to do something
+different altogether.</p>
+
+<h3>Tabs</h3>
+
+<p>Handling of tabs changed completely. The display width of tabs can
+now be set with the <code>tabSize</code> option, and tabs can
+be <a href="../demo/visibletabs.html">styled</a> by setting CSS rules
+for the <code>cm-tab</code> class.</p>
+
+<p>The default width for tabs is now 4, as opposed to the 8 that is
+hard-wired into browsers. If you are relying on 8-space tabs, make
+sure you explicitly set <code>tabSize: 8</code> in your options.</p>
+
+</article>

codemirror/doc/upgrade_v3.html

@@ -0,0 +1,230 @@
+<!doctype html>
+
+<title>CodeMirror: Version 3 upgrade guide</title>
+<meta charset="utf-8"/>
+<link rel=stylesheet href="docs.css">
+<script src="../lib/codemirror.js"></script>
+<link rel="stylesheet" href="../lib/codemirror.css">
+<script src="../addon/runmode/runmode.js"></script>
+<script src="../addon/runmode/colorize.js"></script>
+<script src="../mode/javascript/javascript.js"></script>
+<script src="../mode/xml/xml.js"></script>
+<script src="../mode/css/css.js"></script>
+<script src="../mode/htmlmixed/htmlmixed.js"></script>
+<script src="activebookmark.js"></script>
+
+<div id=nav>
+  <a href="https://codemirror.net"><h1>CodeMirror</h1><img id=logo src="logo.png"></a>
+
+  <ul>
+    <li><a href="../index.html">Home</a>
+    <li><a href="manual.html">Manual</a>
+    <li><a href="https://github.com/codemirror/codemirror">Code</a>
+  </ul>
+  <ul>
+    <li><a class=active href="#upgrade">Upgrade guide</a>
+    <li><a href="#dom">DOM structure</a></li>
+    <li><a href="#gutters">Gutter model</a></li>
+    <li><a href="#events">Event handling</a></li>
+    <li><a href="#marktext">markText method arguments</a></li>
+    <li><a href="#folding">Line folding</a></li>
+    <li><a href="#lineclass">Line CSS classes</a></li>
+    <li><a href="#positions">Position properties</a></li>
+    <li><a href="#matchbrackets">Bracket matching</a></li>
+    <li><a href="#modes">Mode management</a></li>
+    <li><a href="#new">New features</a></li>
+  </ul>
+</div>
+
+<article>
+
+<h2 id=upgrade>Upgrading to version 3</h2>
+
+<p>Version 3 does not depart too much from 2.x API, and sites that use
+CodeMirror in a very simple way might be able to upgrade without
+trouble. But it does introduce a number of incompatibilities. Please
+at least skim this text before upgrading.</p>
+
+<p>Note that <strong>version 3 drops full support for Internet
+Explorer 7</strong>. The editor will mostly work on that browser, but
+it'll be significantly glitchy.</p>
+
+<section id=dom>
+  <h2>DOM structure</h2>
+
+<p>This one is the most likely to cause problems. The internal
+structure of the editor has changed quite a lot, mostly to implement a
+new scrolling model.</p>
+
+<p>Editor height is now set on the outer wrapper element (CSS
+class <code>CodeMirror</code>), not on the scroller element
+(<code>CodeMirror-scroll</code>).</p>
+
+<p>Other nodes were moved, dropped, and added. If you have any code
+that makes assumptions about the internal DOM structure of the editor,
+you'll have to re-test it and probably update it to work with v3.</p>
+
+<p>See the <a href="manual.html#styling">styling section</a> of the
+manual for more information.</p>
+</section>
+<section id=gutters>
+  <h2>Gutter model</h2>
+
+<p>In CodeMirror 2.x, there was a single gutter, and line markers
+created with <code>setMarker</code> would have to somehow coexist with
+the line numbers (if present). Version 3 allows you to specify an
+array of gutters, <a href="manual.html#option_gutters">by class
+name</a>,
+use <a href="manual.html#setGutterMarker"><code>setGutterMarker</code></a>
+to add or remove markers in individual gutters, and clear whole
+gutters
+with <a href="manual.html#clearGutter"><code>clearGutter</code></a>.
+Gutter markers are now specified as DOM nodes, rather than HTML
+snippets.</p>
+
+<p>The gutters no longer horizontally scrolls along with the content.
+The <code>fixedGutter</code> option was removed (since it is now the
+only behavior).</p>
+
+<pre data-lang="text/html">
+&lt;style>
+  /* Define a gutter style */
+  .note-gutter { width: 3em; background: cyan; }
+&lt;/style>
+&lt;script>
+  // Create an instance with two gutters -- line numbers and notes
+  var cm = new CodeMirror(document.body, {
+    gutters: ["note-gutter", "CodeMirror-linenumbers"],
+    lineNumbers: true
+  });
+  // Add a note to line 0
+  cm.setGutterMarker(0, "note-gutter", document.createTextNode("hi"));
+&lt;/script>
+</pre>
+</section>
+<section id=events>
+  <h2>Event handling</h2>
+
+<p>Most of the <code>onXYZ</code> options have been removed. The same
+effect is now obtained by calling
+the <a href="manual.html#on"><code>on</code></a> method with a string
+identifying the event type. Multiple handlers can now be registered
+(and individually unregistered) for an event, and objects such as line
+handlers now also expose events. See <a href="manual.html#events">the
+full list here</a>.</p>
+
+<p>(The <code>onKeyEvent</code> and <code>onDragEvent</code> options,
+which act more as hooks than as event handlers, are still there in
+their old form.)</p>
+
+<pre data-lang="javascript">
+cm.on("change", function(cm, change) {
+  console.log("something changed! (" + change.origin + ")");
+});
+</pre>
+</section>
+<section id=marktext>
+  <h2>markText method arguments</h2>
+
+<p>The <a href="manual.html#markText"><code>markText</code></a> method
+(which has gained some interesting new features, such as creating
+atomic and read-only spans, or replacing spans with widgets) no longer
+takes the CSS class name as a separate argument, but makes it an
+optional field in the options object instead.</p>
+
+<pre data-lang="javascript">
+// Style first ten lines, and forbid the cursor from entering them
+cm.markText({line: 0, ch: 0}, {line: 10, ch: 0}, {
+  className: "magic-text",
+  inclusiveLeft: true,
+  atomic: true
+});
+</pre>
+</section>
+<section id=folding>
+  <h2>Line folding</h2>
+
+<p>The interface for hiding lines has been
+removed. <a href="manual.html#markText"><code>markText</code></a> can
+now be used to do the same in a more flexible and powerful way.</p>
+
+<p>The <a href="../demo/folding.html">folding script</a> has been
+updated to use the new interface, and should now be more robust.</p>
+
+<pre data-lang="javascript">
+// Fold a range, replacing it with the text "??"
+var range = cm.markText({line: 4, ch: 2}, {line: 8, ch: 1}, {
+  replacedWith: document.createTextNode("??"),
+  // Auto-unfold when cursor moves into the range
+  clearOnEnter: true
+});
+// Get notified when auto-unfolding
+CodeMirror.on(range, "clear", function() {
+  console.log("boom");
+});
+</pre>
+</section>
+<section id=lineclass>
+  <h2>Line CSS classes</h2>
+
+<p>The <code>setLineClass</code> method has been replaced
+by <a href="manual.html#addLineClass"><code>addLineClass</code></a>
+and <a href="manual.html#removeLineClass"><code>removeLineClass</code></a>,
+which allow more modular control over the classes attached to a line.</p>
+
+<pre data-lang="javascript">
+var marked = cm.addLineClass(10, "background", "highlighted-line");
+setTimeout(function() {
+  cm.removeLineClass(marked, "background", "highlighted-line");
+});
+</pre>
+</section>
+<section id=positions>
+  <h2>Position properties</h2>
+
+<p>All methods that take or return objects that represent screen
+positions now use <code>{left, top, bottom, right}</code> properties
+(not always all of them) instead of the <code>{x, y, yBot}</code> used
+by some methods in v2.x.</p>
+
+<p>Affected methods
+are <a href="manual.html#cursorCoords"><code>cursorCoords</code></a>, <a href="manual.html#charCoords"><code>charCoords</code></a>, <a href="manual.html#coordsChar"><code>coordsChar</code></a>,
+and <a href="manual.html#getScrollInfo"><code>getScrollInfo</code></a>.</p>
+</section>
+<section id=matchbrackets>
+  <h2>Bracket matching no longer in core</h2>
+
+<p>The <a href="manual.html#addon_matchbrackets"><code>matchBrackets</code></a>
+option is no longer defined in the core editor.
+Load <code>addon/edit/matchbrackets.js</code> to enable it.</p>
+</section>
+<section id=modes>
+  <h2>Mode management</h2>
+
+<p>The <code>CodeMirror.listModes</code>
+and <code>CodeMirror.listMIMEs</code> functions, used for listing
+defined modes, are gone. You are now encouraged to simply
+inspect <code>CodeMirror.modes</code> (mapping mode names to mode
+constructors) and <code>CodeMirror.mimeModes</code> (mapping MIME
+strings to mode specs).</p>
+</section>
+<section id=new>
+  <h2>New features</h2>
+
+<p>Some more reasons to upgrade to version 3.</p>
+
+<ul>
+  <li>Bi-directional text support. CodeMirror will now mostly do the
+  right thing when editing Arabic or Hebrew text.</li>
+  <li>Arbitrary line heights. Using fonts with different heights
+  inside the editor (whether off by one pixel or fifty) is now
+  supported and handled gracefully.</li>
+  <li>In-line widgets. See <a href="../demo/widget.html">the demo</a>
+  and <a href="manual.html#addLineWidget">the docs</a>.</li>
+  <li>Defining custom options
+  with <a href="manual.html#defineOption"><code>CodeMirror.defineOption</code></a>.</li>
+</ul>
+</section>
+</article>
+
+<script>setTimeout(function(){CodeMirror.colorize();}, 20);</script>

codemirror/doc/upgrade_v4.html

@@ -0,0 +1,144 @@
+<!doctype html>
+
+<title>CodeMirror: Version 4 upgrade guide</title>
+<meta charset="utf-8"/>
+<link rel=stylesheet href="docs.css">
+<script src="activebookmark.js"></script>
+
+<div id=nav>
+  <a href="https://codemirror.net"><h1>CodeMirror</h1><img id=logo src="logo.png"></a>
+
+  <ul>
+    <li><a href="../index.html">Home</a>
+    <li><a href="manual.html">Manual</a>
+    <li><a href="https://github.com/codemirror/codemirror">Code</a>
+  </ul>
+  <ul>
+    <li><a class=active href="#upgrade">Upgrade guide</a>
+    <li><a href="#multisel">Multiple selections</a>
+    <li><a href="#beforeSelectionChange">The beforeSelectionChange event</a>
+    <li><a href="#replaceSelection">replaceSelection and collapsing</a>
+    <li><a href="#changeEvent">change event data</a>
+    <li><a href="#showIfHidden">showIfHidden option to line widgets</a>
+    <li><a href="#module">Module loaders</a>
+    <li><a href="#shareddata">Mutating shared data structures</a></li>
+    <li><a href="#deprecated">Deprecated interfaces dropped</a>
+  </ul>
+</div>
+
+<article>
+
+<h2 id=upgrade>Upgrading to version 4</h2>
+
+<p>CodeMirror 4's interface is <em>very</em> close version 3, but it
+does fix a few awkward details in a backwards-incompatible ways. At
+least skim the text below before upgrading.</p>
+
+<section id=multisel><h2>Multiple selections</h2>
+
+<p>The main new feature in version 4 is multiple selections. The
+single-selection variants of methods are still there, but now
+typically act only on the <em>primary</em> selection (usually the last
+one added).</p>
+
+<p>The exception to this
+is <a href="manual.html#getSelection"><strong><code>getSelection</code></strong></a>,
+which will now return the content of <em>all</em> selections
+(separated by newlines, or whatever <code>lineSep</code> parameter you passed
+it).</p>
+
+</section>
+
+<section id=beforeSelectionChange><h2>The beforeSelectionChange event</h2>
+
+<p>This event still exists, but the object it is passed has
+a <a href="manual.html#event_beforeSelectionChange">completely new
+interface</a>, because such changes now concern multiple
+selections.</p>
+
+</section>
+
+<section id=replaceSelection><h2>replaceSelection's collapsing behavior</h2>
+
+<p>By
+default, <a href="manual.html#replaceSelection"><code>replaceSelection</code></a>
+would leave the newly inserted text selected. This is only rarely what
+you want, and also (slightly) more expensive in the new model, so the
+default was changed to <code>"end"</code>, meaning the old behavior
+must be explicitly specified by passing a second argument
+of <code>"around"</code>.</p>
+
+</section>
+
+<section id=changeEvent><h2>change event data</h2>
+
+<p>Rather than forcing client code to follow <code>next</code>
+pointers from one change object to the next, the library will now
+simply fire
+multiple <a href="manual.html#event_change"><code>"change"</code></a>
+events. Existing code will probably continue to work unmodified.</p>
+
+</section>
+
+<section id=showIfHidden><h2>showIfHidden option to line widgets</h2>
+
+<p>This option, which conceptually caused line widgets to be visible
+even if their line was hidden, was never really well-defined, and was
+buggy from the start. It would be a rather expensive feature, both in
+code complexity and run-time performance, to implement properly. It
+has been dropped entirely in 4.0.</p>
+
+</section>
+
+<section id=module><h2>Module loaders</h2>
+
+<p>All modules in the CodeMirror distribution are now wrapped in a
+shim function to make them compatible with both AMD
+(<a href="http://requirejs.org">requirejs</a>) and CommonJS (as used
+by <a href="http://nodejs.org/">node</a>
+and <a href="http://browserify.org/">browserify</a>) module loaders.
+When neither of these is present, they fall back to simply using the
+global <code>CodeMirror</code> variable.</p>
+
+<p>If you have a module loader present in your environment, CodeMirror
+will attempt to use it, and you might need to change the way you load
+CodeMirror modules.</p>
+
+</section>
+
+<section id=shareddata><h2>Mutating shared data structures</h2>
+
+<p>Data structures produced by the library should not be mutated
+unless explicitly allowed, in general. This is slightly more strict in
+4.0 than it was in earlier versions, which copied the position objects
+returned by <a href="manual.html#getCursor"><code>getCursor</code></a>
+for nebulous, historic reasons. In 4.0, mutating these
+objects <em>will</em> corrupt your editor's selection.</p>
+
+</section>
+
+<section id=deprecated><h2>Deprecated interfaces dropped</h2>
+
+<p>A few properties and methods that have been deprecated for a while
+are now gone. Most notably, the <code>onKeyEvent</code>
+and <code>onDragEvent</code> options (use the
+corresponding <a href="manual.html#event_dom">events</a> instead).</p>
+
+<p>Two silly methods, which were mostly there to stay close to the 0.x
+API, <code>setLine</code> and <code>removeLine</code> are now gone.
+Use the more
+flexible <a href="manual.html#replaceRange"><code>replaceRange</code></a>
+method instead.</p>
+
+<p>The long names for folding and completing functions
+(<code>CodeMirror.braceRangeFinder</code>, <code>CodeMirror.javascriptHint</code>,
+etc) are also gone
+(use <code>CodeMirror.fold.brace</code>, <code>CodeMirror.hint.javascript</code>).</p>
+
+<p>The <code>className</code> property in the return value
+of <a href="manual.html#getTokenAt"><code>getTokenAt</code></a>, which
+has been superseded by the <code>type</code> property, is also no
+longer present.</p>
+
+</section>
+</article>