Docs for tagged template literals

[greghuc]

Docs for #4352. Demonstrates use of tagged template literals.

[greghuc]

So the new 'tagged template literal' code example isn't working inline on the documentation page, for:

• the "load" button: Coffeescript-errors with "Error on line 8: unexpected string".
• the "run: text" button: Javascript-errors with "Uncaught SyntaxError: Unexpected token }"

I'm wondering if there's an issue with the CS compiler used as part of the documentation page. The code example correctly compiles and runs with ./bin/coffee file.coffee, so the problems are documentation-specific.

[greghuc]

On a similar note, the "load" button is also failing for the next backtick example (added in #4369), which looks like:

function time() {
  return `The time is ${new Date().toLocaleTimeString()}`;
}

[GeoffreyBooth]

Did you rebuild the browser compiler? cake build:browser I think it is.

[GeoffreyBooth]

You should add a note that the output is ES2015, and the runtime must support tagged template literals (or another tool like Babel converts it down). Also we need to add this feature to the list of ES opt-in features mentioned in the new introduction.

[greghuc]

@GeoffreyBooth I've fixed all the doc issues, though feel free to tweak:

• Broken "load" button: fixed by cake:build:browser
• Broken "run: text" button: fixed, but didn't get to root cause. I made the code example more like other ones on the page by double-quoting string variables, and shortening the tagged template literal so it didn't break across two lines. And it magically works..
• I added a note in the intro about needing runtime support for tagged template literals.

[GeoffreyBooth]

@greghuc I made some fixes to be more consistent in style with the rest of the docs, then I went and made some editorial changes 😄 Nothing too drastic: in the intro, I figured we might as well lump generator functions and tagged template literals in the same list; and in the explanation for the tagged template literals section, I thought it needed to be clearer that CoffeeScript was outputting ES2015 and leaving it to the runtime to do the interpolation, rather than CoffeeScript handling it. That still might not be clear enough.

Anyway I don’t mean for these changes to be the final word, so please let me know if you think any changes I made worsened things 😄

[GeoffreyBooth]

Also upperCaseExpr feels awfully complex for an example, is there any function we could replace it with that’s simpler?

[lydell]

String.raw is a simple function.

---

I like the documentation as it is now in this PR. Still, I wonder if we should explain how tagged template literals work or leave learning JavaScript to the user. It doesn't matter much to me – I just wanted to hear your thoughts.

[greghuc]

I tweaked the explanation text to be less clunky: I moved the "outputting ES2015 warning" part to the end, and rejigged it. So the first part explains what a tagged template literal does, and the second part gives the ES2015 warning. I think it's clearer, but feel free to change.

I now like the documentation as it stands.

Regarding whether "we should explain how tagged template literals work", I think we should, but only in general terms. We've done this in two sentences, but I'd imagine any developer who wants to use tagged template literals would read the MDN page. They take some time to get your head round.

Regarding examples, I think the complexity of upperCaseExpr is the best (simplest) that we can expect. Take a look at the look at these examples, and these other examples: most are more complicated than upperCaseExpr.

I have the impression that tagged template literals are primarily a 'black-box' tool for developers writing templating libraries. So you can have an html/regex templating library that's called very cleanly using a tagged template literal. But no-one (but the library developer) sees inside the 'tag' function, which hides all the complexity. That's why upperCaseExpr and all other tag functions are complicated.

[GeoffreyBooth]

What I don’t like is the sentence that says “Coffeescript will interpret this ‘function plus string’ combination as an ES2015 tagged template literal, and behave accordingly”. First off, the spelling is “CoffeeScript”, but secondly, it implies that CoffeeScript is doing the interpolation like it does for regular interpolated strings; in this case, we’re relying on the runtime to do that.

[greghuc]

Feel free to make any changes you want :-) My internet connectivity will be very sporadic over the next few days, so I’m not going to be doing any more work on this.

…

On 25 Nov 2016, at 16:45, Geoffrey Booth ***@***.***> wrote: What I don’t like is the sentence that says “Coffeescript will interpret this ‘function plus string’ combination as an ES2015 tagged template literal, and behave accordingly”. First off, the spelling is “CoffeeScript”, but secondly, it implies that CoffeeScript is doing the interpolation like it does for regular interpolated strings; in this case, we’re relying on the runtime to do that. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4372 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFGSTrWoHGCX6QoxPXoeAIHQMPTQSw-hks5rBxCcgaJpZM4K7F4R>.

[GeoffreyBooth]

Okay, I rewrote a bit more, hewing closer to @greghuc’s original text but hopefully making the distinction clearer between what CoffeeScript is doing versus what the runtime is doing. @lydell, what do you think? If this looks good to you I think we’re done.

Once this is merged in, I think we can release 1.12. I have a PR open against highlight.js to enable its support for triple backticks, and they recently accepted another PR of mine for new CoffeeScript keywords; but neither PR is in the released highlight.js yet. I was thinking that I could update my local node_modules to use my patched highlight.js to generate the new v1/index.html with proper syntax highlighting, and commit that as part of the 1.12 release. This won’t be reproduceable, but hopefully highlight.js will catch up to us before the next release. Or I could change the highlight.js in package.json to point toward my fork, but that seems messy.

Anyway 1.12 would feature tagged template literals, triple backticks/escaped backticks, and for…from.

[lydell]

All looks good to me!

The plan for 1.12.0 looks good as well. I'd go with the alternative of using the best highlight.js version available locally, and leave package.json as is for now. While doing the release PR, would you mind checking if https://github.com/jashkenas/coffeescript/wiki/%5BHowto%5D-Hacking-on-the-CoffeeScript-Compiler#11-preparing-a-new-release needs updating along the way? (I'm thinking if the new docs setup is different or something.)

[GeoffreyBooth]

@lydell will do. I guess we should also add for…from to the note at top about ES code?

[lydell]

Yes.