Deprecate implicit text-only for script and style #1036

Merged
merged 3 commits into from May 25, 2013

Projects

None yet

10 participants

@ForbesLindesay
Member

closes #875

If we can remove this feature (probably in 0.32.0) then it will simplify a lot of code and significantly reduce the amount you have to learn when you're new to node.

The first step to removing it is to deprecate it and discourage people from using it, so this pull request logs a warning whenever someone relies on this feature. Dealing with the fallout from this will also help to gauge how many people we're going to annoy by removing this feature.

Crucially, once we actually remove the feature altogether, we will be able to write templates that do things like:

script
  import foo.js

which would be enormously useful.

@ForbesLindesay
Member

I will merge this if there are no complaints by 2013-05-25T12:00:00Z

I realize this will be a pain for some people, I'll see about creating an automated tool to help fix this for people.

@ForbesLindesay
Member

We can reduce pain now by encouraging people to use:

npm install fix-jade -g
fix-jade

which will automatically make the necessary change for all jade files in a directory (recursively).

@vendethiel
Contributor

thanks for what you do :-)

@stuartpb
Contributor

I think this change should be accompanied by a bot that files a pull request on all Node projects using Jade with the fix-jade output, like the bot somebody wrote to update all projects using the 'sys' module when it changed to 'util' in node 0.3.0 (praised at a Seattle Node meetup a few months back with "now THAT is how you introduce breaking changes!")

Granted that was 2.5 years and a few orders of magnitude of Node projects on Github ago, so it may not be as feasible now as it was then.

@ForbesLindesay
Member

@stuartpb that would be awesome, the question is how do we find them? I don't think the GitHub search API is sufficient. If people want to submit pull requests into fix-jade then hopefully we can start running it as a bot to submit pull requests. Unfortunately even once you have a repository there's a fair bit of work to be done in order to make the pull requests with the GitHub API.

I'm going to merge this now. We can encourage people to run fix-jade themselves, which is not very time consuming to do, and if it seems to be a problem we can work on creating a bot.

@ForbesLindesay ForbesLindesay merged commit 63c7397 into master May 25, 2013

1 check passed

default The Travis CI build passed
Details
@ForbesLindesay ForbesLindesay deleted the deprecate/implicit-text-only branch May 25, 2013
@stuartpb
Contributor

@ForbesLindesay I don't know how, but I do know it's been done before (the guy who wrote the bot was at the aforementioned Seattle Node meetup: unfortunately, I didn't catch his name). Step one to figuring out how such a thing would be accomplished would probably be finding one of said bot's pull requests and finding the approach / author from there.

@stuartpb
Contributor

Also, how isn't the Github search API sufficient? https://github.com/search?q=extension%3Ajade

@ForbesLindesay
Member

The problem with that is that it only provides the first 100 pages, and there's no way of getting more. That means we'd only get coverage of about 10% of all repos with jade files in them.

I've now written some code that retrieves a list of all repositories that are owned by someone who's starred jade. That seems like a good start.

@jade-bot jade-bot referenced this pull request in esdiscuss/esdiscuss.org May 26, 2013
Merged

Update jade files [bot-update#1] #39

@stuartpb
Contributor

Argh! Github's public-facing search API has different capabilities than their search page? That's regrettable. I'll see what can be done wrt that.

In the meantime I'd also add all the repositories of modules on npmjs.org that list jade as a dependency (if that isn't a strict subset of repos by users starring jade).

@ForbesLindesay
Member

That's not a bad suggestion, but most of the users of jade probably aren't in npm anyway as they will be the final finished applications.

It's not that their search API provides any less functionality than their search page. It's that neither provides the ability to run a search with more than 100 pages of results.

@ForbesLindesay
Member

@jade-bot is go!!!

@ForbesLindesay
Member

The first one not under my control gets closed without merging 😞

dennisreimann/Codeshelver#24

This was referenced May 26, 2013
@ForbesLindesay
Member

One of these is now merged 😄

@binarykitchen

thanks for that solid work. just seen these warnings and trying to fix my jade templates now.

but i'm not clear what to do. for example i have this:

script
    var settings=!{clientSettings};

how would you fix this? if i move var settings=!{clientSettings}; to a separate js file then i cannot include dynamic variables anymore like clientSettings in the above example. it wouldn't work.

any hints welcome!

@stuartpb
Contributor

Same way you fix all script blocks with the new change - explicitly treat them as text blocks with a dot.

script.
    var settings=!{clientSettings};
@binarykitchen

ah, thanks. must have missed that out in the jade documentation. maybe worth adding a link in the warning?

@ForbesLindesay
Member

The message is:

Implicit textOnly for script and style is deprecated. Use script. or style. instead.

That's actually pretty self contained (i.e. add a . and everything will be fine), I'm not convinced it's worth adding anything more to that. Also it'll be dropped entirely in a version or two's time (i.e. within the next month).

Hopefully the automated pull requests should help spread the word about the fix that needs to be applied.

@wereHamster
Contributor

Why does it warn on single-line tag/text, e.g. script var x = 1;? I expect it to work same as any other tag, like h1 text here.

@wereHamster
Contributor

The fix-jade script and the bot make wrong suggestions, like this one here: https://github.com/jcw/adhoq/pull/1/files#L2R14

@ForbesLindesay
Member

Yes, sorry about that. It is a bug and I'll accept pull requests that fix it to either repository. Unfortunately I finals in the next week so I'm not going to get time to look at this myself until Friday.

@binarykitchen

@ForbesLindesay understand but sorry, usability of your warning could be a little better. in the linux console you have no text formatting. it will be interpreted as a whole:

Implicit textOnly for script and style is deprecated. Use script. or style. instead.

I read "Use script." with a dot at the end and interpreted that dot as the end of a sentence. And I didn't interpret it as a jade syntax.

How about this?

Implicit textOnly for script and style is deprecated. Append a dot after the syntax script or style like "script." or "style."

Something like this. Just make it clear for environments that have no text formatting like the console that the dot is part of the syntax.

@ForbesLindesay
Member

It should look like:

Implicit textOnly for `script` and `style` is deprecated.  Use `script.` or `style.` instead.

I didn't mean to have it be markdown formatted. I think most devs would recognize the `` characters as being code. Do they not show up in your console?

@binarykitchen

Oh ok. You're right, they appear like that in my console:

Implicit textOnly for `script` and `style` is deprecated.  Use `script.` or `style.` instead.

Still, I didn't interpret it correctly the first time I read it. Maybe I was too tired, grins ... up to you if you want to make it more clear for those who do not know the . dot trick

@ForbesLindesay
Member

I am keen to make it more clear. A significant portion of the reasoning for introducing this change was actually that it'll lead more people to find out about the . trick. It's been available for a long time and works on all elements, not just scripts and styles. This way the . trick will be used in practically every example so people will be much more likely to learn about its existence.

Improving the http://jade-lang.com/ website is very high priority at the moment. The api section needs to have .render and .renderFile added and the "documentation" should become "language" and be moved to the website rather than the readme.

The readme should then just be a much shorter document with "installation", "basic API", "example/basic syntax" and "license".

@jamiesteven

@ForbesLindesay You're correct that it would be more helpful if it was clearer! 👍 I've just started receiving this error after doing an npm update, and didn't know that adding a '.' would solve.

@stuartpb
Contributor
stuartpb commented Jun 2, 2013

Improving the http://jade-lang.com/ website is very high priority at the moment. The api section needs to have .render and .renderFile added and the "documentation" should become "language" and be moved to the website rather than the readme.

I'd be interested in doing this (with the little I know about Jade- essentially just what's in the readme + the Naltatis demo page). How is the site set up? Jekyll on gh-pages?

The readme should then just be a much shorter document with "installation", "basic API", "example/basic syntax" and "license".

This would also provide an opportunity for buffing up that API documentation in the readme.

@ForbesLindesay
Member

It's actually a node.js based system using express. I then use stop to turn it into a static site to host on gh-pages. Essentially it just runs the express app and then downloads all the content by parsing HTML for href and src attributes.

The source for the website is here.

To install:

npm install

To run at http://localhost:3000/

node src/server.js

To build static site to serve on gh-pages:

npm run build

Stop is configured via this file which is the only file that's specific to generating static sites.

Yes, the readme could have much nicer API docs if it didn't have quite so much stuff in it. It's way way too long to be a single page without a sticky table of contents that indicates where you are in the document.

@elisee
elisee commented Jun 4, 2013

What's the proper syntax for updating script!= javascript? Is it script!= javascript.?

I tried it because that's what the jade-bot offered to merge into express-expose but I get a non-sensical error when parsing my Jade template on the last line of my template:

 Line 39: Unexpected token )
  at throwError (...\node_modules\jade\node_modules\with\node_modules\lexical-scope\node_modules\astw\node_modules\esprima\esprima.js:1156:21)

Is jade-bot/express-expose@6b41eda wrong or am I hitting an unrelated bug?

@vendethiel
Contributor

it's wrong

@stuartpb
Contributor
stuartpb commented Jun 4, 2013

I think the bot is wrong in that script!= javascript should work without change (since that's how all the other non-text-only tags work, and the only thing this change does is make script and style work like the other tags).

@elisee
elisee commented Jun 4, 2013

@stuartpb I'm still getting a deprecation warning though, so either the warning itself is spurious (which might well be the case) or there is some change to make.

@ForbesLindesay
Member

Hi @elisee sorry about this, it's a bug in the current version of jade and it's entirely my fault. We don't have any test cases for:

script foo()

or

script!= code

so I didn't notice the deprecation warning showing up when it shouldn't.

I'll fix it in the next version of Jade but I'm afraid I have exams for the next couple of days. I'll get right on it Friday.

@stuartpb
Contributor

note to self to look into this

@tsgautier

I'm getting this warning now - but I don't even know in which file is the offending code. It would be helpful if the warning could point out where the deprecated usage exists so I could find and fix it.

@elisee
elisee commented Jun 5, 2013

@ForbesLindesay ok thanks for the details, good to know it's nothing to worry about and that I don't have to make any changes.

@ForbesLindesay
Member

@tsgautier

just searching for script or style should find you the files that might have offending tags. Alternatively:

npm install fix-jade -g
fix-jade

will recursively look for and attempt to automatically fix any files with problems in (and list all the files that had problems). I wouldn't recommend using it without version control though in case it gets something wrong.

@elisee

No problem, obviously you would need to fix it if you had something like:

script
  foo()

You would then need to change it to:

script.
  foo()
@YukonSaint

Can you tell me how to convert the following code:

script(type='text/javascript', src='/assets/js/vendor/underscore-min.js')

Or do I need to convert it at all?

FYI - I realize that "Implicit textOnly for script and style is deprecated. Use script. or style. instead." might make plenty of sense to Jade contributors and experienced Jade developers. But for someone who is fairly new to Jade it's very confusing. One or two quick examples in the release notes would be an enormous help.

@stuartpb
Contributor
stuartpb commented Jun 6, 2013

@MattSavino: You don't need to convert it, and indeed you shouldn't even get a deprecation warning for script tags with src attributes.

@stuartpb
Contributor
stuartpb commented Jun 6, 2013

As for a different warning for script and src, maybe this:

"(file): lines (first)-(last): Using text content under a (script / style) element without . is deprecated. Use (script. / style.) instead. (script/style) will be changed to interpret content the same as all other tags in Jade 0.32.0."

@stuartpb
Contributor
stuartpb commented Jun 6, 2013

Alternately, if the Jade site is beefed up, the change could be explained in detail on a documentation page and the deprecation warning could just be changed to a hyperlink like "See http://jade-lang.org/textonlytags.html".

@stuartpb
Contributor
stuartpb commented Jun 6, 2013

I don't have much experience with the Jade parser, but would #1063 tighten up the deprecation context correctly?

I removed the script+src attribute check because that should really have its own warning, since this case is prohibited by the HTML5 spec.

@ForbesLindesay
Member

OK, I like that new suggestion for a beefed up warning message and I'm happy to have that.

I think the beefing up of the jade site might take slightly more time. I don't want to have random pages that are only used as a place to link to from a deprecation warning. Also, urls won't end with file extensions so it would be something like jade0lang.org/textonlytags/

I agree, I was using the src check to try and catch all the scripts that didn't have blocks, I just didn't account for those with inline blocks. Your solution is much neater.

I quite like the idea of rejecting scripts that have bodies and an src attribute as a compilation error at some future point, but it should be left to further down the line.

@ForbesLindesay
Member

tbh the easiest thing is probably just to write a blog post on the subject. I'll sort it out at some point.

@stuartpb
Contributor
stuartpb commented Jun 8, 2013

That's kind of what I was thinking http://jade-lang.org/breaking-changes would be - like a doc page that lists breaking changes that have been made in Jade, with each change getting its own blog-post-like section.

@stuartpb
Contributor
stuartpb commented Jun 8, 2013

Does this change also mean the include filter for .js files that wrap them in <script> tags is going to be dropped?

@ForbesLindesay
Member

It's not something I plan on doing in the near future, but I do plan on making filters explicit in some way so that it'll be possible to include a file and just get the plain text of a markdown doc or js file or whatever. That will be the next major breaking change.

I think encouraging people then to switch from what would be something like:

include js:foo/bar.js

to something like

script
  include foo/bar.js

may be a good idea. I don't think this would need to include deprecation warngings right away though.

@stuartpb
Contributor

Wouldn't include:js make more sense, since filters have traditionally been colon-prefixed (and filenames can technically have colons in them)?

@ForbesLindesay
Member

Yes, probably, I haven't settled on any final syntax yet. I'll open an issue so it can be discussed before anything is decided.

@jescalan
Contributor

Hey @ForbesLindesay - can we get at least which file/line the error is coming from in the deprecation warning? Just upgraded on a big project and getting shit tons of these warnings, but no idea where to find them or change them. I'm aware of projects like fix-jade, but I'd like to be able to just jump in and make these changes myself.

@ForbesLindesay
Member

Yes, patch welcome

@jescalan jescalan pushed a commit to jescalan/jade that referenced this pull request Jun 16, 2013
Jeff Escalante add filename and line number to implicit textOnly warning as discusse…
…d in #1036
b9fce6a
@piuccio piuccio pushed a commit to piuccio/ariatemplates that referenced this pull request Jun 28, 2013
Fabio Crisci fix #592 warning for deprecated jad feature
Remove warnings due to pugjs/pug#1036
8220f59
@piuccio piuccio referenced this pull request in ariatemplates/ariatemplates Jun 28, 2013
Closed

Warning for deprecated jade feature #592

@piuccio piuccio pushed a commit to piuccio/ariatemplates that referenced this pull request Jun 28, 2013
Fabio Crisci fix #592 warning for deprecated jade feature
Remove warnings due to pugjs/pug#1036
6f7dd02
@piuccio piuccio pushed a commit to piuccio/ariatemplates that referenced this pull request Jul 1, 2013
Fabio Crisci fix #592 warning for deprecated jade feature
Remove warnings due to pugjs/pug#1036
688ffed
@piuccio piuccio pushed a commit to ariatemplates/ariatemplates that referenced this pull request Jul 5, 2013
@divdavem Fabio Crisci + divdavem fix #592 warning for deprecated jade feature
Remove warnings due to pugjs/pug#1036
d76630e
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment