Improve readme

Add good README and CONTRIBUTING files.

Auditors: alpert

CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing to KaTeX
+
+We welcome pull requests to KaTeX. If you'd like to add a new symbol, or try to
+tackle adding a larger feature, keep reading. If you have any questions, or want
+help solving a problem, feel free to stop by the [#katex room on
+freenode](http://webchat.freenode.net/?channels=katex).
+
+## Helpful contributions
+
+If you'd like to contribute, try contributing new symbols or functions that
+KaTeX doesn't currently support. The wiki has a page which lists [all of the
+supported
+functions](https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX). You
+can check there to see if we don't support a function you like, or try your
+function in the interactive demo at
+[http://khan.github.io/KaTeX/](http://khan.github.io/KaTeX/).
+
+#### Single symbols
+
+There are many individual symbols that KaTeX doesn't yet support. Read through
+the [symbols.js](symbols.js) file for more information on how to add a symbol.
+
+To figure out the unicode symbol for the symbol you are trying to add, try using
+the symbol in MathJax to see what unicode symbol it outputs. An interactive
+MathJax shell can be found [here](http://fiddle.jshell.net/YpqVp/41/show/).
+
+To figure out what group your symbol falls into, look through the symbols list
+to find other symbols of a similar kind. (e.g. if you were adding `\neq`, look
+for `=`). If you cannot find anything similar, or are unsure, you can try using
+your symbol in TeX surrounded by other different kinds of symbols, and seeing
+whether your spacing matches the spacing that TeX produces.
+
+Once your symbol works, check the JavaScript console to make sure you don't get
+a message like "Can't find character metrics for _" when you render your symbol.
+If you do, check out [extract_ttfs.py](metrics/extract_ttfs.py).
+
+#### Adding new functions
+
+Most functions are handled in the [functions.js](functions.js) file. Read the
+comments in there to get started. If the function you want to add has similar
+output to an existing function, see if you can add a new line to that file to
+get it to work.
+
+If your function isn't similar to an existing function, you'll need to add a
+line to `functions.js` as well as adding an output function in
+[buildTree.js](buildTree.js).
+
+## Testing
+
+Local testing can be done by running the node server in `server.js`. Run `make
+setup` to insteall dependencies, and then `make serve` to start the server.
+
+This will host an interactive editor at
+[http://localhost:7936/](http://localhost:7936/) to play around with and test
+changes.
+
+#### Jasmine tests
+
+The JavaScript parser and some of the tree
+builder is tested with Jasmine. These tests can be run either using node with
+`make test`, or in the browser by visiting
+[http://localhost:7936/test/test.html](http://localhost:7936/test/test.html).
+
+The Jasmine tests should be run after every change, even the addition of small
+symbols. However, [Travis](https://travis-ci.org/Khan/KaTeX/) will run these
+tests when you submit a pull request, in case you forget.
+
+If you make any changes to Parser.js, add jasmine tests to ensure they work.
+
+#### Huxley tests
+
+To ensure the final output looks good, we use
+[Huxley](https://github.com/chenglou/node-huxley) tests, which screenshot
+different expressions. These tests can be run by using the [Huxley
+docker](https://github.com/Khan/KaTeX/tree/master/dockers/HuxleyTests).
+
+The Huxley tests should be run if you add anything more significant than
+individual symbols. These tests are not automatically run, so please remember!
+If the new images are different (meaning they are not byte-by-byte the same as
+the old ones), inspect them visually. If there are no visible changes, that is
+okay. If things change in a way consistent with your additions, explain what
+changed and why. Otherwise, figure out what is causing the changes and fix it!
+
+If you add a feature that is dependent on the final output looking the way you
+created it, add a huxley test. See
+[Huxleyfile.json](test/huxley/Huxleyfile.json).
+
+#### Testing in other browsers
+
+KaTeX supports all major browsers, including IE 8 and newer. Unfortunately, it
+is hard to test new changes in many browsers. If you can, please test your
+changes in as many browsers as possible. In particular, if you make CSS changes,
+try to test in IE 8, using [modern.ie](http://modern.ie) VMs.
+
+## Style guide
+
+Code
+
+ - 4 spaces for indentation
+ - 80 character line length
+ - commas last
+
+In general, try to make your code blend in with the surrounding code.
+
+## License
+
+KaTeX is licenced under the [MIT License](http://opensource.org/licenses/MIT).

README.md

@@ -1,15 +1,42 @@
-# KaTeX [![Build Status](https://travis-ci.org/Khan/KaTeX.svg?branch=master)](https://travis-ci.org/Khan/KaTeX)
+# [<img src="https://khan.github.io/KaTeX/katex-logo.svg" width="130" alt="KaTeX">](http://khan.github.io/KaTeX/) [![Build Status](https://travis-ci.org/Khan/KaTeX.svg?branch=master)](https://travis-ci.org/Khan/KaTeX)
 
-Fast math!
+KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the web.
 
-To run locally
+ * **Fast:** KaTeX renders its math synchronously and doesn't need to reflow the page. See how it compares to a competitor in [this speed test](http://jsperf.com/katex-vs-mathjax/).
---------------
+ * **Print quality:** KaTeX’s layout is based on Donald Knuth’s TeX, the gold standard for math typesetting.
-    make setup
+ * **Self contained:** KaTeX has no dependencies and can easily be bundled with your website resources.
-    make serve
+ * **Server side rendering:** KaTeX produces the same output regardless of browser or environment, so you can pre-render expressions using Node.js and send them as plain HTML.
 
-* [Test page](http://localhost:7936/)
+KaTeX supports all major browsers, including Chrome, Safari, Firefox, Opera, and IE 8 - IE 11.
-* [Unit tests](http://localhost:7936/test/test.html)
 
-License
+## Usage
--------
+
-[MIT License](http://opensource.org/licenses/MIT)
+Download the built files from [the releases page](https://github.com/khan/katex/releases). Include the `katex.min.js` and `katex.min.css` files on your page:
+
+```html
+<link rel="stylesheet" type="text/css" href="/path/to/katex.min.css">
+<script src="/path/to/katex.min.js" type="text/javascript"></script>
+```
+
+Call `katex.render` with a TeX expression and a DOM element to render into:
+
+```js
+katex.render("c = \\pm\\sqrt{a^2 + b^2}", element);
+```
+
+To generate HTML on the server, you can use `katex.renderToString`:
+
+```js
+var html = katex.renderToString("c = \\pm\\sqrt{a^2 + b^2}");
+// '<span class="katex">...</span>'
+```
+
+Make sure to include the CSS and font files, but there is no need to include the JavaScript.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+KaTeX is licenced under the [MIT License](http://opensource.org/licenses/MIT).