Docs improvements

[GeoffreyBooth]

Miscellaneous improvements to the v1 docs:

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. Ignoring the generated example files will help avoid merge conflicts between the v1 and v2 docs.

I found a bug as part of working on that: the exec call that was generating those intermediate JavaScript files was happening asynchronously, so it would really take two rounds of cake doc:site to get updated examples into the generated index.html. I changed exec to be synchronous.

The existential operator section really should get its own entry in the table of contents. Closes #4361.

In “Try CoffeeScript,” if you press the tab key it should type a tab character. Currently it just changes the focus to an HTML element I can’t find, which is clearly “broken” behavior. There was a PR for this, #3342, that I used code from to implement this; plus a touch of CSS to make it pretty. #3342 was closed because people had elaborate plans for implementing CodeMirror, which never happened; until it does, I think the tab key should just work.

I also updated the output to reflect the newer version of highlight.js. My pull request highlightjs/highlight.js#1357 was accepted, so as soon as that project issues a new release it will support CoffeeScript’s newer keywords.

[GeoffreyBooth]

P.S. Should we remove the examples folder? By now there are plenty of examples of CoffeeScript across the Web, and it’s a burden to maintain this folder. The only file in examples people are likely to ever find is underscore.coffee, which is linked to from the “Examples” section of the docs; but even that is presumably out of date compared with the current Underscore.

[lydell]

I like all of the improvements in this PR, and would vote for removing the examples folder (including underscore.coffee).

[GeoffreyBooth]

@lydell Okay, I’ve removed the examples, and the link to the annotated underscore.coffee. Perhaps we should create a new repo in the coffeescript org specifically for underscore.coffee? I kind of like that example. Then we can restore the link to it, and it can have a life of its own if people want to update it.

[GeoffreyBooth]

@jashkenas I hope you don’t mind, but I’m going to merge this in so that #4368 and #4369 can be reviewed more easily. If there’s anything in this PR you disagree with let’s discuss and I’m happy to revert/revise. I’m also happy to create a new repo under coffeescript/underscore.coffee if you want.

As soon as those two PRs are approved, and as soon as the docs for tagged template literals are written and approved, we can release 1.12.0. I’ve submitted some merge requests to highlight.js to fix highlighting for modules, for…from, await and triple backticks; but I doubt they’ll do a new release soon. I could generate a new index.html using my local version of highlight.js and commit that.

[jashkenas]

Yeah, removing the examples sounds just fine if you like.

[GeoffreyBooth]

@jashkenas Do you want to create a new repo for underscore.coffee? Perhaps under https://github.com/coffeescript?

[jashkenas]

Nah — we can just delete it.

[GeoffreyBooth]

Okay. Any notes on #4368 and #4369?

Once those are merged and we get docs for tagged template literals from @greghuc, I think we can release 1.12.