Docs improvements (#4367)

* The generated JavaScript for the examples in the docs ends up within index.html, so we don’t need the intermediate generated .js files committed in the repo; also, even while .gitignored they should be under `docs`, with the rest of the generated files, not under `documentation`, where the source files are.

* Add “Existential Operator” to the table of contents. Closes #4361

* Updated output due to newer version of highlight.js

* Generated the JavaScript for the docs examples should be synchronous, so that index.html isn’t generated before the JavaScript is

* In “Try CoffeeScript,” if you press the tab key it should type a tab character. Closes #3342.

* Rename doc example folders from `js` and `coffee` to just `examples`

* Add missing `yield` to the list of keywords to highlight until highlight.js catches up; update the class used to match highlight.js’ `keyword`

* `cake doc:site` should watch the example files too, not just index.html.js

* Remove examples folder, including underscore.coffee; remove link to annotated underscore.coffee

documentation/examples/aliases.coffee

@@ -0,0 +1,11 @@
+launch() if ignition is on
+
+volume = 10 if band isnt SpinalTap
+
+letTheWildRumpusBegin() unless answer is no
+
+if car.speed < limit then accelerate()
+
+winner = yes if pick in [47, 92, 13]
+
+print inspect "My name is #{@name}"

documentation/examples/array_comprehensions.coffee

@@ -0,0 +1,10 @@
+# Eat lunch.
+eat food for food in ['toast', 'cheese', 'wine']
+
+# Fine five course dining.
+courses = ['greens', 'caviar', 'truffles', 'roast', 'cake']
+menu i + 1, dish for dish, i in courses
+
+# Health conscious meal.
+foods = ['broccoli', 'spinach', 'chocolate']
+eat food for food in foods when food isnt 'chocolate'

documentation/examples/block_comment.coffee

@@ -0,0 +1,4 @@
+###
+SkinnyMochaHalfCaffScript Compiler v1.0
+Released under the MIT License
+###

documentation/examples/cake_tasks.coffee

@@ -0,0 +1,9 @@
+fs = require 'fs'
+
+option '-o', '--output [DIR]', 'directory for compiled code'
+
+task 'build:parser', 'rebuild the Jison parser', (options) ->
+  require 'jison'
+  code = require('./lib/grammar').parser.generate()
+  dir  = options.output or 'lib'
+  fs.writeFile "#{dir}/parser.js", code

documentation/examples/chaining.coffee

@@ -0,0 +1,6 @@
+$ 'body'
+.click (e) ->
+  $ '.box'
+  .fadeIn 'fast'
+  .addClass '.active'
+.css 'background', 'white'

documentation/examples/classes.coffee

@@ -0,0 +1,21 @@
+class Animal
+  constructor: (@name) ->
+
+  move: (meters) ->
+    alert @name + " moved #{meters}m."
+
+class Snake extends Animal
+  move: ->
+    alert "Slithering..."
+    super 5
+
+class Horse extends Animal
+  move: ->
+    alert "Galloping..."
+    super 45
+
+sam = new Snake "Sammy the Python"
+tom = new Horse "Tommy the Palomino"
+
+sam.move()
+tom.move()

documentation/examples/comparisons.coffee

@@ -0,0 +1,3 @@
+cholesterol = 127
+
+healthy = 200 > cholesterol > 60

documentation/examples/conditionals.coffee

@@ -0,0 +1,9 @@
+mood = greatlyImproved if singing
+
+if happy and knowsIt
+  clapsHands()
+  chaChaCha()
+else
+  showIt()
+
+date = if friday then sue else jill

documentation/examples/constructor_destructuring.coffee

@@ -0,0 +1,5 @@
+class Person
+  constructor: (options) ->
+    {@name, @age, @height = 'average'} = options
+
+tim = new Person name: 'Tim', age: 4

documentation/examples/default_args.coffee

@@ -0,0 +1,2 @@
+fill = (container, liquid = "coffee") ->
+  "Filling the #{container} with #{liquid}..."

documentation/examples/do.coffee

@@ -0,0 +1,4 @@
+for filename in list
+  do (filename) ->
+    fs.readFile filename, (err, contents) ->
+      compile filename, contents.toString()

documentation/examples/embedded.coffee

@@ -0,0 +1,3 @@
+hi = `function() {
+  return [document.title, "Hello JavaScript"].join(": ");
+}`

documentation/examples/existence.coffee

@@ -0,0 +1,6 @@
+solipsism = true if mind? and not world?
+
+speed = 0
+speed ?= 15
+
+footprints = yeti ? "bear"

documentation/examples/expansion.coffee

@@ -0,0 +1,4 @@
+text = "Every literary critic believes he will
+        outwit history and have the last word"
+
+[first, ..., last] = text.split " "

documentation/examples/expressions.coffee

@@ -0,0 +1,9 @@
+grade = (student) ->
+  if student.excellentWork
+    "A+"
+  else if student.okayStuff
+    if student.triedHard then "B" else "B-"
+  else
+    "C"
+
+eldest = if 24 > 21 then "Liz" else "Ike"

documentation/examples/expressions_assignment.coffee

@@ -0,0 +1 @@
+six = (one = 1) + (two = 2) + (three = 3)

documentation/examples/expressions_comprehension.coffee

@@ -0,0 +1,3 @@
+# The first ten global properties.
+
+globals = (name for name of window)[0...10]

documentation/examples/expressions_try.coffee

@@ -0,0 +1,6 @@
+alert(
+  try
+    nonexistent / undefined
+  catch error
+    "And the error is ... #{error}"
+)

documentation/examples/fat_arrow.coffee

@@ -0,0 +1,6 @@
+Account = (customer, cart) ->
+  @customer = customer
+  @cart = cart
+
+  $('.shopping_cart').on 'click', (event) =>
+    @customer.purchase @cart

documentation/examples/functions.coffee

@@ -0,0 +1,2 @@
+square = (x) -> x * x
+cube   = (x) -> square(x) * x

documentation/examples/generators.coffee

@@ -0,0 +1,8 @@
+perfectSquares = ->
+  num = 0
+  loop
+    num += 1
+    yield num * num
+  return
+
+window.ps or= perfectSquares()

documentation/examples/heredocs.coffee

@@ -0,0 +1,5 @@
+html = """
+       <strong>
+         cup of coffeescript
+       </strong>
+       """

documentation/examples/heregexes.coffee

@@ -0,0 +1,9 @@
+OPERATOR = /// ^ (
+  ?: [-=]>             # function
+   | [-+*/%<>&|^!?=]=  # compound assign / compare
+   | >>>=?             # zero-fill right shift
+   | ([-+:])\1         # doubles
+   | ([&|<>])\2=?      # logic / shift
+   | \?\.              # soak access
+   | \.{2,3}           # range or splat
+) ///

documentation/examples/interpolation.coffee

@@ -0,0 +1,4 @@
+author = "Wittgenstein"
+quote  = "A picture is a fact. -- #{ author }"
+
+sentence = "#{ 22 / 7 } is a decent approximation of π"

documentation/examples/modules.coffee

@@ -0,0 +1,22 @@
+import 'local-file.coffee'
+import 'coffee-script'
+
+import _ from 'underscore'
+import * as underscore from 'underscore'
+
+import { now } from 'underscore'
+import { now as currentTimestamp } from 'underscore'
+import { first, last } from 'underscore'
+import utilityBelt, { each } from 'underscore'
+
+export default Math
+export square = (x) -> x * x
+export class Mathematics
+  least: (x, y) -> if x < y then x else y
+
+export { sqrt }
+export { sqrt as squareRoot }
+export { Mathematics as default, sqrt as squareRoot }
+
+export * from 'underscore'
+export { max, min } from 'underscore'

documentation/examples/modulo.coffee

@@ -0,0 +1,4 @@
+-7 % 5 == -2 # The remainder of 7 / 5
+-7 %% 5 == 3 # n %% 5 is always between 0 and 4
+
+tabs.selectTabAtIndex((tabs.currentIndex - count) %% tabs.length)

documentation/examples/multiple_return_values.coffee

@@ -0,0 +1,5 @@
+weatherReport = (location) ->
+  # Make an Ajax request to fetch the weather...
+  [location, 72, "Mostly Sunny"]
+
+[city, temp, forecast] = weatherReport "Berkeley, CA"

documentation/examples/object_comprehensions.coffee

@@ -0,0 +1,4 @@
+yearsOld = max: 10, ida: 9, tim: 11
+
+ages = for child, age of yearsOld
+  "#{child} is #{age}"

documentation/examples/object_extraction.coffee

@@ -0,0 +1,11 @@
+futurists =
+  sculptor: "Umberto Boccioni"
+  painter:  "Vladimir Burliuk"
+  poet:
+    name:   "F.T. Marinetti"
+    address: [
+      "Via Roma 42R"
+      "Bellagio, Italy 22021"
+    ]
+
+{poet: {name, address: [street, city]}} = futurists

documentation/examples/objects_and_arrays.coffee

@@ -0,0 +1,17 @@
+song = ["do", "re", "mi", "fa", "so"]
+
+singers = {Jagger: "Rock", Elvis: "Roll"}
+
+bitlist = [
+  1, 0, 1
+  0, 0, 1
+  1, 1, 0
+]
+
+kids =
+  brother:
+    name: "Max"
+    age:  11
+  sister:
+    name: "Ida"
+    age:  9

documentation/examples/objects_reserved.coffee

@@ -0,0 +1,3 @@
+$('.account').attr class: 'active'
+
+log object.class

documentation/examples/overview.coffee

@@ -0,0 +1,28 @@
+# Assignment:
+number   = 42
+opposite = true
+
+# Conditions:
+number = -42 if opposite
+
+# Functions:
+square = (x) -> x * x
+
+# Arrays:
+list = [1, 2, 3, 4, 5]
+
+# Objects:
+math =
+  root:   Math.sqrt
+  square: square
+  cube:   (x) -> x * square x
+
+# Splats:
+race = (winner, runners...) ->
+  print winner, runners
+
+# Existence:
+alert "I knew it!" if elvis?
+
+# Array comprehensions:
+cubes = (math.cube num for num in list)

documentation/examples/parallel_assignment.coffee

@@ -0,0 +1,4 @@
+theBait   = 1000
+theSwitch = 0
+
+[theBait, theSwitch] = [theSwitch, theBait]

documentation/examples/patterns_and_splats.coffee

@@ -0,0 +1,3 @@
+tag = "<impossible>"
+
+[open, contents..., close] = tag.split("")

documentation/examples/prototypes.coffee

@@ -0,0 +1,2 @@
+String::dasherize = ->
+  this.replace /_/g, "-"

documentation/examples/range_comprehensions.coffee

@@ -0,0 +1 @@
+countdown = (num for num in [10..1])

documentation/examples/scope.coffee

@@ -0,0 +1,5 @@
+outer = 1
+changeNumbers = ->
+  inner = -1
+  outer = 10
+inner = changeNumbers()

documentation/examples/slices.coffee

@@ -0,0 +1,9 @@
+numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+start   = numbers[0..2]
+
+middle  = numbers[3...-2]
+
+end     = numbers[-2..]
+
+copy    = numbers[..]

documentation/examples/soaks.coffee

@@ -0,0 +1 @@
+zip = lottery.drawWinner?().address?.zipcode

documentation/examples/splats.coffee

@@ -0,0 +1,25 @@
+gold = silver = rest = "unknown"
+
+awardMedals = (first, second, others...) ->
+  gold   = first
+  silver = second
+  rest   = others
+
+contenders = [
+  "Michael Phelps"
+  "Liu Xiang"
+  "Yao Ming"
+  "Allyson Felix"
+  "Shawn Johnson"
+  "Roman Sebrle"
+  "Guo Jingjing"
+  "Tyson Gay"
+  "Asafa Powell"
+  "Usain Bolt"
+]
+
+awardMedals contenders...
+
+alert "Gold: " + gold
+alert "Silver: " + silver
+alert "The Field: " + rest

documentation/examples/splices.coffee

@@ -0,0 +1,3 @@
+numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+numbers[3..6] = [-3, -4, -5, -6]

documentation/examples/strings.coffee

@@ -0,0 +1,6 @@
+mobyDick = "Call me Ishmael. Some years ago --
+  never mind how long precisely -- having little
+  or no money in my purse, and nothing particular
+  to interest me on shore, I thought I would sail
+  about a little and see the watery part of the
+  world..."

documentation/examples/switch.coffee

@@ -0,0 +1,10 @@
+switch day
+  when "Mon" then go work
+  when "Tue" then go relax
+  when "Thu" then go iceFishing
+  when "Fri", "Sat"
+    if day is bingoDay
+      go bingo
+      go dancing
+  when "Sun" then go church
+  else go work

documentation/examples/switch_with_no_expression.coffee

@@ -0,0 +1,8 @@
+score = 76
+grade = switch
+  when score < 60 then 'F'
+  when score < 70 then 'D'
+  when score < 80 then 'C'
+  when score < 90 then 'B'
+  else 'A'
+# grade == 'C'

documentation/examples/try.coffee

@@ -0,0 +1,7 @@
+try
+  allHellBreaksLoose()
+  catsAndDogsLivingTogether()
+catch error
+  print error
+finally
+  cleanUp()

documentation/examples/while.coffee

@@ -0,0 +1,10 @@
+# Econ 101
+if this.studyingEconomics
+  buy()  while supply > demand
+  sell() until supply > demand
+
+# Nursery Rhyme
+num = 6
+lyrics = while num -= 1
+  "#{num} little monkeys, jumping on the bed.
+    One fell out and bumped his head."