Editting of docs across the board
This includes spelling updates, clarifications, a couple new methods and larger rewrites of the Config and Contributing Guides
diff --git a/docs/Api_Methods.md b/docs/Api_Methods.md
index 2cd80d2..1bfa6ae 100644
--- a/docs/Api_Methods.md
+++ b/docs/Api_Methods.md
@@ -6,7 +6,7 @@
var MQ = MathQuill.getInterface(2);
```
-MathQuill overwrites the global `MathQuill` variable when loaded. You can undo that with `.noConflict()` (similar to [`jQuery.noConflict()`](http://api.jquery.com/jQuery.noConflict)):
+By default, MathQuill overwrites the global `MathQuill` variable when loaded. If you do not want this behavior, you can use `.noConflict()` (similar to [`jQuery.noConflict()`](http://api.jquery.com/jQuery.noConflict)):
```html
<script src="/path/to/first-mathquill.js"></script>
@@ -20,21 +20,21 @@
</script>
```
-(Warning: This lets different copies of MathQuill each power their own math fields, but using different copies on the same DOM element won't work. Anyway, .noConflict() is primarily to help you reduce globals.)
+This lets different copies of MathQuill each power their own math fields, but using different copies on the same DOM element won't work. `noConflict()` is intended to help you reduce globals.
# Constructors
## MQ.StaticMath(html_element)
-Creates a non-editable MathQuill with the contents of the HTML element and returns a [static MathField object](http://mathquill.readthedocs.org/en/latest/Api_Methods/#mathfield-methods).
+Creates a non-editable MathQuill initialized with the contents of the HTML element and returns a [static MathField object](http://mathquill.readthedocs.org/en/latest/Api_Methods/#mathfield-methods).
-If the element is already a static MathField, this will return a new static Mathfield object with the same ID. If the element is a different type of MathQuill element, this will return null.
+If the given element is already a static MathField, this will return a new static Mathfield object with the same ID. If the element is a different type of MathQuill element, this will return null.
## MQ.MathField(html_element, config)
-Creates an editable MathQuill with the contents of the HTML element and returns an [editable MathField object](http://mathquill.readthedocs.org/en/latest/Api_Methods/#editable-mathfield-methods).
+Creates an editable MathQuill initialized with the contents of the HTML element and returns an [editable MathField object](http://mathquill.readthedocs.org/en/latest/Api_Methods/#editable-mathfield-methods).
-If the element is already an editable MathField, this will return a new editable Mathfield object with the same ID. If the element is a different type of MathQuill element, this will return null.
+If the given element is already an editable MathField, this will return a new editable Mathfield object with the same ID. If the element is a different type of MathQuill element, this will return null.
## MQ(html_element)
@@ -47,6 +47,10 @@
MQ(otherSpan) // => null
```
+## MQ.config(config)
+
+Globally updates the [configuration](http://mathquill.readthedocs.org/en/latest/Config/#setting-configuration) to the new config.
+
# Comparing MathFields
## Checking Type
@@ -86,18 +90,18 @@
# MathField Methods
-These are methods that every MathField has. These are the only methods that static fields have and a subset of the methods that editable fields have.
+The following are methods that every MathField has. These are the only methods that static fields have and a subset of the methods that editable fields have.
## revert()
-Any element that has been MathQuill-ified can be reverted:
+Any element that has been turned into a MathQuill element can be reverted:
```html
<span id="revert-me" class="mathquill-static-math">
some <code>HTML</code>
</span>
```
```js
-MQ($('#revert-me')[0]).revert().html(); // => 'some <code>HTML</code>'
+mathfield.revert().html(); // => 'some <code>HTML</code>'
```
## reflow()
@@ -171,7 +175,7 @@
## movetoDirEnd(direction)
-Moves the cursor to the end of the mathfield in the direction specified. The direction can be one of `MQ.L` or `MQ.R`. These are constants that obey the contract that `MQ.L === -MQ.R` and vice versa. This function may be easier to use than [moveToLeftEnd or moveToRightEnd](http://mathquill.readthedocs.org/en/latest/Api_Methods/#movetoleftend-movetorightend) if used in the [`moveOutOf` handler](http://mathquill.readthedocs.org/en/latest/Config/#outof-handlers) when setting the [configuration of a mathField](http://mathquill.readthedocs.org/en/latest/Config/#setting-configuration).
+Moves the cursor to the end of the mathfield in the direction specified. The direction can be one of `MQ.L` or `MQ.R`. These are constants, where `MQ.L === -MQ.R` and vice versa. This function may be easier to use than [moveToLeftEnd or moveToRightEnd](http://mathquill.readthedocs.org/en/latest/Api_Methods/#movetoleftend-movetorightend) if used in the [`moveOutOf` handler](http://mathquill.readthedocs.org/en/latest/Config/#outof-handlers) when setting the [configuration of a mathField](http://mathquill.readthedocs.org/en/latest/Config/#setting-configuration).
```javascript
var config = {
@@ -200,6 +204,10 @@
mathField.typedText('x=-b\\pm \\sqrt b^2 -4ac');
```
+## config(new_config)
+
+Changes the config of the mathField to the new [configuration](http://mathquill.readthedocs.org/en/latest/Config/#setting-configuration).
+
## dropEmbedded(pageX, pageY, options) **[Experimental](http://mathquill.readthedocs.org/en/latest/Api_Methods/#note-on-experimental-features)**
Insert a custom embedded element at the given coordinates, where `options` is an object like:
diff --git a/docs/Config.md b/docs/Config.md
index 42d8424..e0a66a0 100644
--- a/docs/Config.md
+++ b/docs/Config.md
@@ -11,7 +11,7 @@
charsThatBreakOutOfSupSub: '+-=<>',
autoSubscriptNumerals: true,
autoCommands: 'pi theta sqrt sum',
- autoOperatorNames: 'sin cos etc',
+ autoOperatorNames: 'sin cos',
substituteTextarea: function() {
return document.createElement('textarea');
},
@@ -23,11 +23,11 @@
});
```
-On initialization, pass the configuration object, structured like the one above as the second argument to `MQ.MathField(HTML_ELEMENT, CONFIG)`.
+On initialization, pass the configuration object, structured like the one above as the second argument to [`MQ.MathField(html_element, config)`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#mqmathfieldhtml_element-config).
-To change the options later on, use `mathField.config(NEW_CONFIG)`.
+To change the options later on, use [`mathField.config(new_config)`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#confignewconfig).
-Global defaults for a page may be set with `MQ.config(NEW_CONFIG)`.
+Global defaults may be set with [`MQ.config(NEW_CONFIG)`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#mqconfig).
# Configuration Options
@@ -35,15 +35,19 @@
If `spaceBehavesLikeTab` is true the keystrokes {Shift-,}Spacebar will behave like {Shift-,}Tab escaping from the current block (as opposed to the default behavior of inserting a Space character).
+The animated demo on mathquill.com has this behavior.
+
## leftRightIntoCmdGoes
-By default, the Left and Right keys move the cursor through all possible cursor positions in a particular order: right into a fraction puts the cursor at the left end of the numerator, right out of the numerator puts the cursor at the left end of the denominator, right out of the denominator puts the cursor to the
-right of the fraction; symmetrically, left into a fraction puts the cursor at the right end of the denominator, etc. Note that right out of the numerator to the left end of the denominator is actually leftwards (and downwards, it's basically wrapped). If instead you want right to always go right, and left to always go left, you can set `leftRightIntoCmdGoes` to `'up'` or `'down'` so that left and right go up or down (respectively) into commands, e.g. `'up'` means that left into a fraction goes up into the numerator, skipping the denominator; symmetrically, right out of the numerator skips the denominator and puts the cursor to the right of the fraction, which unlike the default behavior is actually rightwards (the drawback is the denominator is always skipped, you can't get to it with just Left and Right, you have to press Down); which is the same behavior as the [Desmos calculator](https://www.desmos.com/calculator). `'down'` instead means it is the
-numerator that is always skipped, which is the same behavior as the Mac OS X built-in app Grapher.
+This allows you to change the way the left and right keys move the cursor when there are items of different height, like fractions.
+
+By default, the Left and Right keys move the cursor through all possible cursor positions in a particular order: right into a fraction puts the cursor at the left end of the numerator, right out of the numerator puts the cursor at the left end of the denominator, right out of the denominator puts the cursor to the right of the fraction. Symmetrically, left into a fraction puts the cursor at the right end of the denominator, etc.
+
+If instead you want right to always visually go right, and left to always go visually left, you can set `leftRightIntoCmdGoes` to `'up'` or `'down'` so that left and right go up or down (respectively) into commands. For example, `'up'` means that left into a fraction goes up into the numerator and right out of the numerator skips the denominator and puts the cursor to the right of the fraction. This behavior can be seen in the [Desmos calculator](https://www.desmos.com/calculator). If this property is set to `'down'` instead, the numerator is harder to navigate to, like in the Mac OS X built-in app Grapher.
## restrictMismatchedBrackets
-If `restrictMismatchedBrackets` is true then you can type [a,b) and [a,b), but if you try typing `[x}` or `\langle x|`, you'll get `[{x}]` or `\langle|x|\rangle` instead. This lets you type `(|x|+1)` normally; otherwise, you'd get `\left( \right| x \left| + 1 \right)`.
+If `restrictMismatchedBrackets` is true then you can type [a,b) and (a,b], but if you try typing `[x}` or `\langle x|`, you'll get `[{x}]` or `\langle|x|\rangle` instead. This lets you type `(|x|+1)` normally; otherwise, you'd get `\left( \right| x \left| + 1 \right)`.
## sumStartsWithNEquals
@@ -55,26 +59,37 @@
## charsThatBreakOutOfSupSub
-`charsThatBreakOutOfSupSub` sets the chars that when typed, "break out" of superscripts and subscripts: for example, typing `x^2n+y` normally results in the LaTeX `x^{2n+y}`, you have to hit Down or Tab (or Space if `spaceBehavesLikeTab` is true) to move the cursor out of the exponent and get
-the LaTeX `x^{2n}+y`; this option makes `+` "break out" of the exponent and type what you expect. Problem is, now you can't just type `x^n+m` to get the LaTeX `x^{n+m}`, you have to type `x^(n+m` and delete the paren or something. (Doesn't apply to the first character in a superscript or subscript, so typing
-`x^-6` still results in `x^{-6}`.)
+`charsThatBreakOutOfSupSub` takes a string of the chars that when typed, "break out" of superscripts and subscripts.
+
+Normally, to get out of a superscript or subscript, a user has to navigate out of it with the directional keys, a mouse click, tab, or Space if [`spaceBehavesLikeTab`](http://mathquill.readthedocs.org/en/latest/Config/#spacesbehavesliketab) is true. For example, typing `x^2n+y` normally results in the LaTeX `x^{2n+y}`. If you wanted to get the LaTeX `x^{2n}+y`, the user would have to manually move the cursor out of the exponent.
+
+If this option was set to `'+-'`, `+` and `-` would "break out" of the exponent. This doesn't apply to the first character in a superscript or subscript, so typing `x^-6` still results in `x^{-6}`. The downside to setting this options is that in order to type `x^{n+m}`, a workaround like typing `x^(n+m` and then deleting the `(` is required.
## autoCommands
-`autoCommands`, a space-delimited list of LaTeX control words (no backslash, letters only, min length 2), defines the (default empty) set of "auto-commands", commands automatically rendered by just typing the letters without typing a backslash first.
+`autoCommands` defines the set of commands automatically rendered by just typing the letters without typing a backslash first.
+
+This takes a string formatted as a space-delimited list of LaTeX commands. Each LaTeX command must be at least letters only with a minimum length of 2 characters.
+
+For example, with `autoCommands` set to `'pi theta'`, the word 'pi' automatically converts to the pi symbol and the word 'theta' automatically converts to the theta symbol.
## autoOperatorNames
-`autoOperatorNames`, a list of the same form (space-delimited letters-only each length>=2), and overrides the set of operator names that automatically become non-italicized when typing the letters without typing a backslash first, like `sin`, `log`, etc. (Defaults to [the LaTeX built-in operator names](http://latex.wikia.com/wiki/List_of_LaTeX_symbols#Named_operators:_sin.2C_cos.2C_etc.), but with additional trig operators like `sech`, `arcsec`, `arsinh`, etc.)
+`autoOperatorNames` overrides the set of operator names that automatically become non-italicized when typing the letters without typing a backslash first, like `sin`, `log`, etc.
+
+This defaults to [the LaTeX built-in operator names](http://latex.wikia.com/wiki/List_of_LaTeX_symbols#Named_operators:_sin.2C_cos.2C_etc.) with additional trig operators like `sech`, `arcsec`, `arsinh`, etc. If you want some of these italicized after setting this property, you will have to add them to the list.
+
+Just like [`autoCommands`](http://mathquill.readthedocs.org/en/latest/Config/#autocommands) above, this takes a string formatted as a space-delimited list of LaTeX commands.
## substituteTextarea
-`substituteTextarea`, a function that creates a focusable DOM element, called when setting up a math field. It defaults to `<textarea autocorrect=off .../>`, but for example, [Desmos](https://www.desmos.com/calculator) substitutes `<span tabindex=0></span>` on iOS to suppress the built-in virtual keyboard in favor of a custom math keypad that
-calls the MathQuill API. Unfortunately there's no universal [check for a virtual keyboard](http://stackoverflow.com/q/2593139/362030), you can't even [detect a touchscreen](http://www.stucox.com/blog/you-cant-detect-a-touchscreen/) (notably [Modernizr gave up](https://github.com/Modernizr/Modernizr/issues/548)) and even if you could, Windows 8 and ChromeOS devices have both physical keyboards and touchscreens and you can connect physical keyboards to iOS and Android devices with Bluetooth, so touchscreen != virtual keyboard. Desmos currently sniffs the user agent for iOS, so Bluetooth keyboards just don't work in Desmos on iOS, the trade offs are up to you.
+`substituteTextarea` is a function that creates a focusable DOM element that is called when setting up a math field. Overwriting this may be useful for hacks like suppressing built-in virtual keyboards. It defaults to `<textarea autocorrect=off .../>`.
+
+For example, [Desmos](https://www.desmos.com/calculator) substitutes `<span tabindex=0></span>` on iOS to suppress the built-in virtual keyboard in favor of a custom math keypad that calls the MathQuill API. Unfortunately there's no universal [check for a virtual keyboard](http://stackoverflow.com/q/2593139/362030) or [way to detect a touchscreen](http://www.stucox.com/blog/you-cant-detect-a-touchscreen/) and even if you could a touchscreen != virtual keyboard (Windows 8 and ChromeOS devices have both physical keyboards and touchscreens and iOS and Android devices can have Bluetooth keyboards). Desmos currently sniffs the user agent for iOS, so Bluetooth keyboards just don't work in Desmos on iOS. The trade offs are up to you.
# Handlers
-Handlers are called directly on the `handlers` object passed in, preserving the `this` value, so you can do stuff like:
+Handlers are called after a specified event. They are called directly on the `handlers` object passed in, preserving the `this` value, so you can do stuff like:
```js
var MathList = P(function(_) {
_.init = function() {
@@ -111,7 +126,7 @@
`moveOutOf(direction, mathField)`, `deleteOutOf(direction, mathField)`, `selectOutOf(direction, mathField)`, `upOutOf(mathField)`, `downOutOf(mathField)`
-The `*OutOf` handlers are called when Left/Right/Up/Down/Backspace/Del/Shift-Left/Shift-Right is pressed but the cursor is at the left/right/top/bottom edge and so nothing happens within the math field. For example, when the cursor is at the left edge, pressing the Left key causes the `moveOutOf` handler to be called with `MQ.L` and the math field API object as arguments, and Backspace causes `deleteOutOf` to be called with `MQ.L` and the API object as arguments, etc.
+The `*OutOf` handlers are called when a cursor movement would cause the cursor to leave the MathQuill mathField. These let you integrate cursor movement seamlessly between your code and MathQuill. For example, when the cursor is at the right edge, pressing the Right key causes the `moveOutOf` handler to be called with `MQ.R` and the mathField API object. Pressing Backspace causes `deleteOutOf` to be called with `MQ.L` and the mathField.
## enter(mathField)
@@ -119,13 +134,15 @@
## edit(mathField)
-This is called when the contents of the field might have been changed by stuff being typed, or deleted, or written with the API, etc. (Deprecated aliases: `edited`, `reflow`.) Note that this may be called when nothing has actually changed.
+This is called when the contents of the field might have been changed. This will be called with any edit, such as something being typed, deleted, or written with the API. Note that this may be called when nothing has actually changed.
+
+Deprecated aliases: `edited`, `reflow`.
# Changing Colors
-To change the foreground color, set both `color` and the `border-color` because some MathQuill symbols are implemented with borders, not text.
+To change the foreground color, set both `color` and the `border-color` because some MathQuill symbols are implemented with borders instead of pure text.
-For example, to style as white-on-black instead of black-on-white:
+For example, to style as white-on-black instead of black-on-white use:
#my-math-input {
color: white;
diff --git a/docs/Contributing.md b/docs/Contributing.md
index 01376a9..96496e1 100644
--- a/docs/Contributing.md
+++ b/docs/Contributing.md
@@ -1,95 +1,65 @@
-# Contributing
+# Building from Source
-## Building and Testing
+Install [Node](http://nodejs.org/#download) if needed. Then run `make`. `make` installs all of the needed dependencies and creates the full build folder.
-To hack on MathQuill, you're gonna want to build and test the source files
-you edit. In addition to `make`, MathQuill uses some build tools written on
-[Node](http://nodejs.org/#download), so you will need to install that before
-running `make`. (Once it's installed, `make` automatically does `npm install`,
-installing the necessary build tools.)
+For development on MathQuill, run `make dev`. This will skip minifying MathQuill, which can be annoyingly slow.
-- `make` builds `build/mathquill.{css,js,min.js}`
-- `make dev` won't try to minify MathQuill (which can be annoyingly slow)
-- `make test` builds `mathquill.test.js` (used by `test/unit.html`) and also
- doesn't minify
-- `make basic` builds `mathquill-basic.{js,min.js,css}` and
- `font/Symbola-basic.{eot,ttf}`; serve and load them instead for a stripped-
- down version of MathQuill for basic mathematics, without advanced LaTeX
- commands. Specifically, it doesn't let you type LaTeX backslash commands
- with `\` or text blocks with `$`, and also won't render any LaTeX commands
- that can't by typed without `\`. The resulting JS is only somewhat smaller,
- but the font is like 100x smaller. (TODO: reduce full MathQuill's font size.)
+## Building a Smaller MathQuill
-## Understanding The Source Code
+`make basic` builds a stripped-down version of MathQuill for basic mathematics, without advanced LaTeX commands. Specifically, it doesn't let you type LaTeX backslash commands with `\` or text blocks with `$`, and also won't render any LaTeX commands that can't by typed without `\`. `mathquill-basic.{js,min.js,css}` and `font/Symbola-basic.{eot,ttf}`; serve and load them instead for a stripped- down version of MathQuill for basic mathematics, without advanced LaTeX commands. Specifically, it doesn't let you type LaTeX backslash commands with `\` or text blocks with `$`, and also won't render any LaTeX commands that can't by typed without `\`. The resulting JS is only somewhat smaller, but the font is like 100x smaller. (TODO: reduce full MathQuill's font size.)
-All the CSS is in `src/css`. Most of it's pretty straightforward, the choice of
-font isn't settled, and fractions are somewhat arcane, see the Wiki pages
-["Fonts"](http://github.com/mathquill/mathquill/wiki/Fonts) and
-["Fractions"](http://github.com/mathquill/mathquill/wiki/Fractions).
+# Testing
-All the JavaScript that you actually want to read is in `src/`, `build/` is
-created by `make` to contain the same JS cat'ed and minified.
+Run `make test`, which builds `mathquill.test.js`. Open `test/unit.html` in your browser to see the result of the unit tests. Open `test/visual.html` to see how a variety of expressions are rendering on your branch.
-There's a lot of JavaScript but the big picture isn't too complicated, there's 2
-thin layers sandwiching 2 broad but modularized layers:
+# Understanding The Source Code
-- At the highest level, the public API is a thin wrapper around calls to:
-- "services" on the "controller", which sets event listeners that call:
-- methods on "commands" in the "edit tree", which call:
-- tree- and cursor-manipulation methods, at the lowest level, to move the
- cursor or edit the tree or whatever.
+All the CSS is in `src/css`. The choice of font isn't settled, and fractions are somewhat arcane, see the Wiki pages ["Fonts"](http://github.com/mathquill/mathquill/wiki/Fonts) and ["Fractions"](http://github.com/mathquill/mathquill/wiki/Fractions).
-More specifically:
+All the JavaScript that you actually want to read is in `src/`. `build/` is created by `make` to contain the same JS concatenated and minified.
-(In comments and internal documentation, `::` means `.prototype.`.)
+## Architecture
-- At the lowest level, the **edit tree** of JS objects represents math and text
- analogously to how [the HTML DOM](http://www.w3.org/TR/html5-author/introduction.html#a-quick-introduction-to-html) represents a web page.
- + (Old docs variously called this the "math tree", the "fake DOM", or some
- combination thereof, like the "math DOM".)
- + `tree.js` defines base classes of objects relating to the tree.
- + `cursor.js` defines objects representing the cursor and a selection of
- math or text, with associated HTML elements.
-- Interlude: a **feature** is a unit of publicly exposed functionality, either
- by the API or interacted with by typists. Following are the 2 disjoint
- categories of features.
-- A **command** is a thing you can type and edit like a fraction, square root,
- or "for all" symbol, ∀. They are implemented as a class of node objects
- in the edit tree, like `Fraction`, `SquareRoot`, or `VanillaSymbol`.
- + Each command has an associated **control sequence** (as termed by Knuth;
- in the LaTeX community, commonly called a "macro" or "command"), a token
- in TeX and LaTeX syntax consisting of a backslash then any single
- character or string of letters, like `\frac` or <code>\ </code>. Unlike
- loose usage in the LaTeX community, where `\ne` and `\neq` (which print
- the same symbol, ≠) might or might not be considered the same command,
- in the context of MathQuill they are considered different "control
- sequences" for the same "command".
-- A **service** is a feature that applies to all or many commands, like typing,
- moving the cursor around, LaTeX exporting, LaTeX parsing. Note that each of
- these varies by command (the cursor goes in a different place when moving into
- a fraction vs into a square root, they export different LaTeX, etc), cue
- polymorphism: services define methods on the controller that call methods on
- nodes in the edit tree with certain contracts, such as a controller method
- called on initialization to set listeners for keyboard events, that when the
- Left key is pressed, calls `.moveTowards` on the node just left of the cursor,
- dispatching on what kind of command the node is (`Fraction::moveTowards` and
- `SquareRoot::moveTowards` can insert the cursor in different places).
- + `controller.js` defines the base class for the **controller**, which each
- math field or static math instance has one of, and to which each service
- adds methods.
-- `publicapi.js` defines the global `MathQuill.getInterface()` function, the
- `MQ.MathField()` etc. constructors, and the API objects returned by
- them. The constructors, and the API methods on the objects they return, call
- appropriate controller methods to initialize and manipulate math field and
- static math instances.
+There's 2 thin layers sandwiching 2 broad, modularized layers:
-Misc.:
+At the highest level, the public API is a thin wrapper around calls to [services](http://mathquill.readthedocs.org/en/latest/Contributing/#service) on the controller. These set event listeners that call methods on [commands](http://mathquill.readthedocs.org/en/latest/Contributing/#command) in the [edit tree](http://mathquill.readthedocs.org/en/latest/Contributing/#edit-tree). Those commands call tree and cursor manipulation methods to do actions like move the cursor or edit the tree.
-`intro.js` defines some simple sugar for the idiomatic JS classes used
-throughout MathQuill, plus some globals and opening boilerplate.
+## Edit Tree
-Classes are defined using [Pjs](https://github.com/jneen/pjs), and the variable `_` is used by convention as
-the prototype.
+At the lowest level, the **edit tree** of JS objects represents math and text analogously to how [the HTML DOM](http://www.w3.org/TR/html5-author/introduction.html#a-quick-introduction-to-html) represents a web page.
-`services/*.util.js` files are unimportant to the overall architecture, you can
-ignore them until you have to deal with code that is using them.
+`tree.js` defines base classes of objects relating to the tree.
+
+`cursor.js` defines objects representing the cursor and a selection of math or text, with associated HTML elements.
+
+Old docs variously called this the "math tree", the "fake DOM", or some combination thereof, like the "math DOM".
+
+## Command
+
+A **command** is a thing a user can type and edit like a fraction, square root, or "for all" symbol, ∀. They are implemented as a class of node objects in the edit tree, like `Fraction`, `SquareRoot`, or `VanillaSymbol`.
+
+Each command has an associated **control sequence** (commonly called a "macro" or "command"). This is a token in TeX and LaTeX syntax consisting of a backslash then any single character or string of letters, like `\frac` or <code>\ </code>. Unlike loose usage in the LaTeX community, where `\ne` and `\neq` might or might not be considered the same command, in the context of MathQuill they are considered different "control sequences" for the same "command".
+
+## Service
+
+A **service** is a feature that applies to all or many actions, such as typing, moving the cursor around, LaTeX exporting, or LaTeX parsing. Each of these actions vary by command. For example, the cursor goes in a different place when moving into a fraction vs into a square root and they each export different LaTeX.
+
+Services define methods on the controller that call methods on nodes in the edit tree with certain contracts, such as a controller method called on initialization to set listeners for keyboard events, that when the Left key is pressed, calls `.moveTowards` on the node just left of the cursor, dispatching on what kind of command the node is (`Fraction::moveTowards` and `SquareRoot::moveTowards` can insert the cursor in different places).
+
+`controller.js` defines the base class for the **controller**, which each math field or static math instance has one of, and to which each service adds methods.
+
+## API
+
+`publicapi.js` defines the global `MathQuill.getInterface()` function, the mathField constructors, and the API objects returned by them. The constructors, and the API methods on the objects they return, call appropriate controller methods to initialize and manipulate math field and static math instances.
+
+## Other Components
+
+`services/*.util.js` files are unimportant to the overall architecture. You can largely ignore them until you have to deal with code that is using them.
+
+`intro.js` defines some simple sugar for the idiomatic JS classes used throughout MathQuill, plus some globals and opening boilerplate.
+
+## Conventions
+
+Classes are defined using [Pjs](https://github.com/jneen/pjs), and the variable `_` is used by convention as the prototype.
+
+In comments and internal documentation, `::` means `.prototype.`.
diff --git a/docs/Getting_Started.md b/docs/Getting_Started.md
index 8d0d410..72d1add 100644
--- a/docs/Getting_Started.md
+++ b/docs/Getting_Started.md
@@ -15,7 +15,7 @@
var MQ = MathQuill.getInterface(2);
```
-All [API methods](http://mathquill.readthedocs.org/en/latest/Api_Methods/) will be called on `MQ`.
+All [API methods](http://mathquill.readthedocs.org/en/latest/Api_Methods/) will be called on [`MQ`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#api-interface).
You can also [build from the source code](http://mathquill.readthedocs.org/en/latest/Contributing/#building-and-testing).
@@ -27,7 +27,7 @@
## Render Static Math
-Call `MQ.StaticMath` on the HTML element.
+Call [`MQ.StaticMath`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#mqstaticmathhtml_element) on the HTML element.
```html
<p>Solve <span id="problem">ax^2 + bx + c = 0</span></p>
@@ -39,7 +39,7 @@
## Editable Math
-To create an editable math field, call `MQ.MathField` with the HTML element and the [config](http://mathquill.readthedocs.org/en/latest/Config/). The following example shows a mathfield created on the answer span with a handler to check the answer every time an edit may occur.
+To create an editable math field, call [`MQ.MathField`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#mqmathfieldhtml_element-config) with the HTML element and the [config](http://mathquill.readthedocs.org/en/latest/Config/). The following example shows a mathfield created on the answer span with a handler to check the answer every time an edit may occur.
```html
<p><span id="answer">x=</span></p>
@@ -58,9 +58,9 @@
## Get and Set Math
-The recommended way to retrieve and store the contents of the math field is to call `mathField.latex()`. `mathField.html()` can be used to retrieve the contents of the mathField as static HTML.
+The recommended way to retrieve and store the contents of the math field is to call [`mathField.latex()`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#latex). [`mathField.html()`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#html) can be used to retrieve the contents of the mathField as static HTML.
-A mathField will be initialized with the text that was in the span, interpreted as LaTex. This can be updated later by calling `mathField.latex(latexString)`. Content can be added as it would be by someone typing with [`typedText()`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#typedtexttext),
+A mathField will be initialized with the text that was in the span, interpreted as LaTex. This can be updated later by calling [`mathField.latex(latexString)`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#latexlatex_string). Content can be added as it would be by someone typing with [`typedText(string)`](http://mathquill.readthedocs.org/en/latest/Api_Methods/#typedtexttext),
# Join the Community
