[CS2] 2.0.0-beta1 docs (#4494)

* Update package versions; remove marked

* Revise docs to use Markdown-It: tables are now GitHub-Flavored Markdown tables, avoid hack of blockquoted code blocks

* Add anchors for sub-sections

* Add syntax highlighting to uneducable code blocks; fix missing italics variant for comments font

* Update docs about breaking changes in Literate CoffeeScript, move Breaking Changes section below Literate CoffeeScript section

* Update docs regarding destructuring default values breaking change

* Update changelog, with spitball release date for beta1

* Fix highlight function return statement

Cakefile

@@ -199,22 +199,36 @@ buildDocs = (watch = no) ->
   codeFor = require "./documentation/v#{majorVersion}/code.coffee"
 
   htmlFor = ->
-    marked = require 'marked'
-    markdownRenderer = new marked.Renderer()
-    markdownRenderer.heading = (text, level) ->
-      "<h#{level}>#{text}</h#{level}>" # Don’t let marked add an id
-    markdownRenderer.code = (code) ->
+    hljs = require 'highlight.js'
+    hljs.configure classPrefix: ''
+    markdownRenderer = require('markdown-it')
+      html: yes
+      typographer: yes
+      highlight: (str, lang) ->
+        # From https://github.com/markdown-it/markdown-it#syntax-highlighting
+        if lang and hljs.getLanguage(lang)
+          try
+            return hljs.highlight(lang, str).value
+          catch ex
+        return '' # No syntax highlighting
+
+
+    # Add some custom overrides to Markdown-It’s rendering, per
+    # https://github.com/markdown-it/markdown-it/blob/master/docs/architecture.md#renderer
+    defaultFence = markdownRenderer.renderer.rules.fence
+    markdownRenderer.renderer.rules.fence = (tokens, idx, options, env, slf) ->
+      code = tokens[idx].content
       if code.indexOf('codeFor(') is 0 or code.indexOf('releaseHeader(') is 0
         "<%= #{code} %>"
       else
-        "<pre><code>#{code}</code></pre>" # Default
+        "<blockquote class=\"uneditable-code-block\">#{defaultFence.apply @, arguments}</blockquote>"
 
     (file, bookmark) ->
       md = fs.readFileSync "#{sectionsSourceFolder}/#{file}.md", 'utf-8'
       md = md.replace /<%= releaseHeader %>/g, releaseHeader
       md = md.replace /<%= majorVersion %>/g, majorVersion
       md = md.replace /<%= fullVersion %>/g, CoffeeScript.VERSION
-      html = marked md, renderer: markdownRenderer
+      html = markdownRenderer.render md
       html = _.template(html)
         codeFor: codeFor()
         releaseHeader: releaseHeader

documentation/examples/breaking_change_destructuring_default_values.coffee

@@ -0,0 +1,3 @@
+{a = 1} = {a: null}
+
+a  # Equals 1 in CoffeeScript 1.x, null in CoffeeScript 2

documentation/sections/breaking_changes.md

@@ -2,20 +2,30 @@
 
 CoffeeScript 2 aims to output as much idiomatic ES2015+ syntax as possible with as few breaking changes from CoffeeScript 1.x as possible. Some breaking changes, unfortunately, were unavoidable.
 
-### Function parameter default values
+<section id="breaking-changes-default-values">
 
-Per the [ES2015 spec regarding default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters), default values are only applied when a parameter value is missing or `undefined`. In CoffeeScript 1.x, the default value would be applied in those cases but also if the parameter value was `null`.
+### Default values for function parameters and destructured elements
+
+Per the [ES2015 spec regarding function default parameters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters) and [destructuring default values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Default_values), default values are only applied when a value is missing or `undefined`. In CoffeeScript 1.x, the default value would be applied in those cases but also if the  value was `null`.
 
 ```
 codeFor('breaking_change_function_parameter_default_values', 'f(null)')
 ```
 
+```
+codeFor('breaking_change_destructuring_default_values', 'a')
+```
+
+</section>
+<section id="breaking-changes-bound-generator-functions">
+
 ### Bound generator functions
 
 Bound generator functions, a.k.a. generator arrow functions, [aren’t allowed in ECMAScript](http://stackoverflow.com/questions/27661306/can-i-use-es6s-arrow-function-syntax-with-generators-arrow-notation). You can write `function*` or `=>`, but not both. Therefore, CoffeeScript code like this:
 
-> ```coffee
-f = => yield this  # Throws a compiler error
+```coffee
+f = => yield this
+# Throws a compiler error
 ```
 
 Needs to be rewritten the old-fashioned way:
@@ -24,38 +34,48 @@ Needs to be rewritten the old-fashioned way:
 codeFor('breaking_change_bound_generator_function')
 ```
 
+</section>
+<section id="breaking-changes-classes">
+
 ### Classes are compiled to ES2015 classes
 
 ES2015 classes and their methods have some restrictions beyond those on regular functions.
 
 Class constructors can’t be invoked without `new`:
 
-> ```coffee
-(class)()  # Throws a TypeError at runtime
+```coffee
+(class)()
+# Throws a TypeError at runtime
 ```
 
 Derived (extended) class `constructor`s cannot use `this` before calling `super`:
 
-> ```coffee
+```coffee
 class B extends A
-  constructor: -> this  # Throws a compiler error
+  constructor: -> this
+  # Throws a compiler error
 ```
 
 Class methods can’t be used with `new` (uncommon):
 
-> ```coffee
+```coffee
 class Namespace
   @Klass = ->
-new Namespace.Klass  # Throws a TypeError at runtime
+new Namespace.Klass
+# Throws a TypeError at runtime
 ```
 
+</section>
+<section id="breaking-changes-bare-super">
+
 ### Bare `super`
 
 Due to a syntax clash with `super` with accessors, bare `super` no longer compiles to a super call forwarding all arguments.
 
-> ```coffee
+```coffee
 class B extends A
-  foo: -> super    # Throws a compiler error
+  foo: -> super
+  # Throws a compiler error
 ```
 
 Arguments can be forwarded explicitly using splats:
@@ -70,15 +90,19 @@ Or if you know that the parent function doesn’t require arguments, just call `
 codeFor('breaking_change_super_without_arguments')
 ```
 
+</section>
+<section id="breaking-changes-super-in-non-class-methods">
+
 ### `super` in non-class methods
 
 In CoffeeScript 1.x it is possible to use `super` in more than just class methods, such as in manually prototype-assigned functions:
 
-> ```coffee
+```coffee
 A = ->
 B = ->
 B extends A
-B.prototype.foo = -> super arguments...  # Throws a compiler error
+B.prototype.foo = -> super arguments...
+# Throws a compiler error
 ```
 
 Due to the switch to ES2015 `super`, this is no longer supported. The above case could be refactored to:
@@ -93,13 +117,26 @@ or
 codeFor('breaking_change_super_in_non-class_methods_refactor_with_class')
 ```
 
+</section>
+<section id="breaking-changes-dynamic-class-keys-exclude-executable-class-scope">
+
 ### Dynamic class keys exclude executable class scope
 
 Due to the hoisting required to compile to ES2015 classes, dynamic keys in class methods can’t use values from the executable class body unless the methods are assigned in prototype style.
 
-> ```coffee
+```coffee
 class A
   name = 'method'
   "#{name}": ->   # This method will be named 'undefined'
   @::[name] = ->  # This will work; assigns to `A.prototype.method`
 ```
+
+</section>
+
+<section id="breaking-changes-literate-coffeescript">
+
+### Literate CoffeeScript now parsed by a Markdown library
+
+The CoffeeScript 1.x implementation of Literate CoffeeScript relies on indentation to tell apart code blocks from documentation, and as such it can get confused by Markdown features that also use indentation like lists. In CoffeeScript 2 this has been refactored to now use [Markdown-It](https://github.com/markdown-it/markdown-it) to detect Markdown sections rather than just looking at indentation. The only significant difference is that now if you want to include a code block in documentation, as opposed to the compiler recognizing that code block as code, it must have at least one line fully unindented. Wrapping it in HTML tags is no longer sufficient.
+
+Code blocks interspersed with lists may need to be refactored. In general, code blocks should be separated by a blank line between documentation, and should maintain a consistent indentation level—so an indentation of one tab (or whatever you consider to be a tab stop, like 2 spaces or 4 spaces) should be treated as your code’s “left margin,” with all code in the file relative to that column.

documentation/sections/changelog.md

@@ -1,5 +1,16 @@
 ## Change Log
 
+```
+releaseHeader('2017-04-14', '2.0.0-beta1', '2.0.0-alpha1')
+```
+
+*   Initial beta release of CoffeeScript 2. No further breaking changes are anticipated.
+*   Destructured objects and arrays now output using ES2015+ syntax whenever possible.
+*   Literate CoffeeScript now has much better support for parsing Markdown, thanks to using [Markdown-It](https://github.com/markdown-it/markdown-it) to detect Markdown sections rather than just looking at indentation.
+*   Calling a function named `get` or `set` now requires parentheses, to disambiguate from the `get` or `set` keywords (which are [disallowed](#unsupported-get-set)).
+*   The compiler now requires Node 7.6+, the first version of Node to support asynchronous functions without requiring a flag.
+
+
 ```
 releaseHeader('2017-02-21', '2.0.0-alpha1', '1.12.4')
 ```

documentation/sections/coffeescript_2.md

@@ -14,7 +14,7 @@ Since the CoffeeScript 2 compiler outputs ES2015+ syntax, it is your responsibil
 
 There are many great task runners for setting up JavaScript build chains, such as [Gulp](http://gulpjs.com/), [Webpack](https://webpack.github.io/), [Grunt](https://gruntjs.com/) and [Broccoli](http://broccolijs.com/). If you’re looking for a very minimal solution to get started, you can use [babel-preset-env](https://babeljs.io/docs/plugins/preset-env/) and the command line:
 
-> ```bash
+```bash
 npm install --global coffeescript@next
 npm install --save-dev coffeescript@next babel-cli babel-preset-env
 coffee -p *.coffee | babel --presets env > app.js

documentation/sections/installation.md

@@ -4,12 +4,12 @@ The command-line version of `coffee` is available as a [Node.js](http://nodejs.o
 
 To install, first make sure you have a working copy of the latest stable version of [Node.js](http://nodejs.org/). You can then install CoffeeScript globally with [npm](http://npmjs.org):
 
-> ```
+```bash
 npm install --global coffeescript@next
 ```
 
 When you need CoffeeScript as a dependency of a project, within that project’s folder you can install it locally:
 
-> ```
+```bash
 npm install --save coffeescript@next
 ```

documentation/sections/introduction.md

@@ -4,6 +4,6 @@ The golden rule of CoffeeScript is: _“It’s just JavaScript.”_ The code com
 
 **Latest Version:** [<%= fullVersion %>](http://github.com/jashkenas/coffeescript/tarball/<%= fullVersion %>)
 
-> ```
+```bash
 npm install -g coffeescript@next
 ```

documentation/sections/operators.md

@@ -24,125 +24,21 @@ codeFor('modulo')
 
 All together now:
 
-<table class="definitions">
-
-<tbody>
-
-<tr>
-
-<th>CoffeeScript</th>
-
-<th>JavaScript</th>
-
-</tr>
-
-<tr>
-
-<td>`is`</td>
-
-<td>`===`</td>
-
-</tr>
-
-<tr>
-
-<td>`isnt`</td>
-
-<td>`!==`</td>
-
-</tr>
-
-<tr>
-
-<td>`not`</td>
-
-<td>`!`</td>
-
-</tr>
-
-<tr>
-
-<td>`and`</td>
-
-<td>`&&`</td>
-
-</tr>
-
-<tr>
-
-<td>`or`</td>
-
-<td>`||`</td>
-
-</tr>
-
-<tr>
-
-<td>`true`, `yes`, `on`</td>
-
-<td>`true`</td>
-
-</tr>
-
-<tr>
-
-<td>`false`, `no`, `off`&emsp;</td>
-
-<td>`false`</td>
-
-</tr>
-
-<tr>
-
-<td>`@`, `this`</td>
-
-<td>`this`</td>
-
-</tr>
-
-<tr>
-
-<td>`of`</td>
-
-<td>`in`</td>
-
-</tr>
-
-<tr>
-
-<td>`in`</td>
-
-<td>_<small>no JS equivalent</small>_</td>
-
-</tr>
-
-<tr>
-
-<td>`a ** b`</td>
-
-<td>`Math.pow(a, b)`</td>
-
-</tr>
-
-<tr>
-
-<td>`a // b`</td>
-
-<td>`Math.floor(a / b)`</td>
-
-</tr>
-
-<tr>
-
-<td>`a %% b`</td>
-
-<td>`(a % b + b) % b`</td>
-
-</tr>
-
-</tbody>
-
-</table>
+| CoffeeScript | JavaScript |
+| --- | --- |
+| `is` | `===` |
+| `isnt` | `!==` |
+| `not` | `!` |
+| `and` | `&&` |
+| `or` | `||` |
+| `true`, `yes`, `on` | `true` |
+| `false`, `no`, `off`&emsp; | `false` |
+| `@`, `this` | `this` |
+| `of` | `in` |
+| `in` | _no JS equivalent_ |
+| `a ** b` | `Math.pow(a, b)` |
+| `a // b` | `Math.floor(a / b)` |
+| `a %% b` | `(a % b + b) % b` |
 
 ```
 codeFor('aliases')