Remove !!!

[ForbesLindesay]

The !!! syntax as a shorthand for doctype is a really terrible mistake. It's hardly any faster to type and much harder to read when people are seeing a jade template for the first time.

The 5 as a shorthand for html is just ludicrous. It makes even less sense now as 5 is going to be the "perpetual" version for html.

[vendethiel]

Meh. That's used in a lot of different places/engines, so I don't see that being a worth bc break

[tj]

you're so angry :p

[buschtoens]

Though I always liked the quick !!! 5, I see your point. doctype html is more expressive.

But I'd really like to wait with removing this until there is at least one release, where this is deprecated, so nothing will break directly.

[ForbesLindesay]

@visionmedia Not angry, just arguing my case succinctly. The !!! are yours not mine :p

@silvinci the extra release really don't add any value. People don't update their code until it actually breaks. We could make it break with a nicer error message, along the lines of !!! is deprecated, use doctype and 5 is a deprecated doctype, use html. Without breaking things, people won't change them. I also want to get all the breaking changes into a single release. There are going to be at least 4 major breaking changes in that release, so adding one more is not that expensive. I'll update the fix-jade bot to fix anyone's public repos with a pull request, and I'll add a proper migration guide to the wiki before releasing.

[buschtoens]

@ForbesLindesay Ah, okay then. :) I love how you care for us and have a bot helping us. :D
Do you think we can squeeze in a preprocessor (#1272)? :P

[rlidwka]

People don't update their code until it actually breaks. We could make it break with a nicer error message

They do if some software is outputting swear words to stdout/stderr without breaking anything. At least node.js core and express.js are known to do this for a few releases before breaking things.

[ForbesLindesay]

We're not node, it's a lot easier for people to just not update their version of jade if they have a problem.

[sintaxi]

Agree with the change, though very unfortunate not having a deprecation warning since this will break approximately everything written with Jade. !!! has been in nearly every documented example of jade since the inception of the library.

[matejkramny]

+1 broke all my websites since upgrade to 1.0

Matej Kramny

On 7 Jan 2014, at 04:42 am, Brock Whitten notifications@github.com wrote:

Agree with the change, though very unfortunate not having a deprecation
warning since this will break approximately everything written with Jade.
!!! has been in nearly every documented example of jade since the inception
of the library.

—
Reply to this email directly or view it on
GitHubhttps://github.com//pull/1270#issuecomment-31713028
.

[buschtoens]

+1-ing doesn't help anymore. The change is already pushed to npm. ;)

I'd recommend writing a quick script, that runs through all .jade files and looks for !!! at indentation level 0 and replaces it with doctype html.

var regex = /^(?:!!!|doctype 5)\s*$/gi;

[matejkramny]

well, had to try :).
Alternatively, holding off on previous version works too.

I also found that v1 gets annoyed by a space after an element
e.g.
p.someclass(space here)

produces an error (as it should, now back to designers telling them to use correct syntax.)

Matej Kramny

On Tuesday, 7 January 2014 at 10:43, Jan Buschtöns wrote:

+1-ing doesn't help anymore. The change is already pushed to npm. ;)
I'd recommend writing a quick script, that runs through all .jade files and looks for !!! at indentation level 0 and replaces it with doctype html.

—
Reply to this email directly or view it on GitHub (#1270 (comment)).

[buschtoens]

If you find this to be an error, I suggest opening a new issue. However, I configured my editor to strip all trailing whitespace on save.

[matejkramny]

The issue is with my designers…

they tend to do silly stuff like

p(class="hello world")

and leaving a space at the end of the brackets (facepalm), bad indentation etc.
Would be awesome (for me) if all these were contraband :P

Matej Kramny

On Tuesday, 7 January 2014 at 10:48, Jan Buschtöns wrote:

If you find this to be an error, I suggest opening a new issue. However, I configured my editor to strip all trailing whitespace on save.

—
Reply to this email directly or view it on GitHub (#1270 (comment)).

[buschtoens]

Haha yeah. I recommend using some sort of live-parsing. So your designers get immediate visual feedback (i.e. Does that p.someClass look good here?) and instantly see an error thrown, when they f*cked up the syntax.

[matejkramny]

hmm i imagine it isn't worth the trouble unless it was written into jade and possibly under option as strict mode..

when i discover they do that i send them to the documentation and ask them to fix it. few weeks ago i told them i won't accept any code that is using the incorrect syntax, which seems to work.

yeah when there's an error i have to remote myself to their PC and fix it manually… They're doing a good job otherwise though, check it out http://eventmost.com

Matej Kramny

On Tuesday, 7 January 2014 at 10:53, Jan Buschtöns wrote:

Haha yeah. I recommend using some sort of live-parsing. So your designers get immediate visual feedback (i.e. Does that p.someClass look good here?) and instantly see an error thrown, when they f*cked up the syntax.

—
Reply to this email directly or view it on GitHub (#1270 (comment)).

[buschtoens]

Ouch, don't change font-weight on user interaction (:hover). It's jumpy.
Otherwise okay. :D

[matejkramny]

hmm thanks, will add it to their todo list :)

Matej Kramny

On Tuesday, 7 January 2014 at 11:03, Jan Buschtöns wrote:

Ouch, don't change font-weight on user interaction (:hover). It's jumpy.
Otherwise okay. :D

—
Reply to this email directly or view it on GitHub (#1270 (comment)).

[sintaxi]

I've prepared a patch release to restore the previous doctype functionality. It replaces it with deprecation warnings until people have time to update their applications. Please consider pulling, it will save us a lot of trouble.

#1374

[stuartpb]

I entirely and full-heartedly disagree with the deprecation of !!!. Here's why.

• A Jade file with "!!!" at the top is cleaner and distinctly visually differentiated from a Jade file that doesn't have "!!!" at the top, like a subtemplate. Before this change, if I had a folder full of thumbnails at 3px font, I could still pick out my layout template in a second. With this change, it's lost in the noise, looking just like any other keyword.
• Having some kind of header at the top of a file demarcated with magic number characters is a well-understood established practice (examples: #!, %YAML 1.2, the <! in <!DOCTYPE), and is in fact easier to understand than having what appears to be a normal tag name that you need to understand the special case for.
• Using "doctype" as a non-punctuated keyword makes it look like a tag, which it is totally not. If I put a doctype halfway down in my document's body, that's an error.

Deprecating !!! by itself as an implicit <!DOCTYPE html>? Sure, okay, make everybody declare the html directive explicitly, fine. (We've put up with decades of obvious #!/bin/sh headers, that's no biggie.) But don't make doctype a required keyword. By a simple understanding of Jade's rules, doctype html should mean <doctype html>, and throwing a special-case exception right off the bat doesn't help make things clearer.

[rlidwka]

A file with "!!!" at the top is cleaner and distinctly visually differentiated from a file that doesn't have "!!!" at the top, like a subtemplate.

Why should it be differentiated?

Having some kind of header at the top of a file demarcated with unfamiliar characters is a completely normal and expected practice

Doctype is a part of an output, not a header. At least, it's not a jade header. You can place doctype in the middle of the text freely.

Using "doctype" as a non-punctuated keyword makes it look like a tag, which it is totally not.

Same for "extend", "include", "mixin" and other keywords. So what? Are they all need to be removed because they aren't tags?

By a simple understanding of Jade's rules, doctype html should mean

And "block foobar" should mean <block foobar>, right? That's not how jade works.

[stuartpb]

A file with "!!!" at the top is cleaner and distinctly visually differentiated from a file that doesn't have "!!!" at the top, like a subtemplate.

Why should it be differentiated?

Because you render starting from base templates (templates you include a doctype at the top of), and include subtemplates (templates you don't include a doctype at the top of). If you try to render starting from a subtemplate, or include a base template, you're doing something wrong, and having it look different at the top is a clear distinction.

Doctype is a part of an output, not a header. At least, it's not a jade header. You can place doctype in the middle of the text freely.

Yeah, and then your HTML parsing of that output is going to fail. (I don't know how hard the HTML5 parser will crash if you do this; point is, it's bad HTML.)

Using "doctype" as a non-punctuated keyword makes it look like a tag, which it is totally not.

Same for "extend", "include", "mixin" and other keywords. So what? Are they all need to be removed because they aren't tags?

extend, include, mixin are keywords whose behavior and use isn't anything even remotely like tags, and they're keywords you use if you know all of Jade's fancy features. doctype is a keyword that has a ever so slightly different behavior from what you would expect from a non-special-cased doctype, kind of like how script and style used to implicitly treat their content as text-only before 0.32.

And, further to the point that's been made in the last couple weeks (I really wish I'd caught wind of this in October, unfortunately I was busy writing Chatphrase, blissfully using !!!s left and right all the while), you don't break years of backwards compatibility because "people don't recognize our magic number". They'll figure it out.

[rlidwka]

If you try to render starting from a subtemplate, or include a base template, you're doing something wrong, and having it look different at the top is a clear distinction.

I'm rendering "subtemplates" only, and each template is extending a base one. No includes. What exactly am I doing wrong?

Yeah, and then your HTML parsing of that output is going to fail.

My point was: doctype has nothing to do with jade, it's html header. In jade it's the same control sequence like all others.

you don't break years of backwards compatibility

There was no backward compatibility. I changed my templates at least two times over the last year because of jade updates. If you're worrying about compatibility, you can avoid using newer jade versions like mocha does.

[stuartpb]

If you try to render starting from a subtemplate, or include a base template, you're doing something wrong, and having it look different at the top is a clear distinction.

I'm rendering "subtemplates" only, and each template is extending a base one. No includes. What exactly am I doing wrong?

Nothing. The point is, you have a base type of Jade you start or end at, and a type of Jade you don't. One has a doctype, one doesn't, and you don't, in the same line of inclusion/extension, use another !!! template.

There was no backward compatibility

!!!
html
  head
    meta(charset="utf-8")
    title Example
  body
    p Hello world!

This, and thousands of plain templates like it, have been backwards-compatible for years. True, Jade has broken BC on some specific features that some people use (like implicit inline style/script), but nothing that breaks every well-formed Jade template since the beginning, regardless of complexity.

I'm in an e-mail conversation with a designer who's just learning Jade now. At this point, he's not using blocks, or extends, or inlines, or anything like that: he's just using it to block out his HTML with variables. This breaks the basics that he has just learned.

[rlidwka]

Nothing. The point is, you have a base type of Jade you render, and a type of Jade you don't. One has a doctype, one doesn't, and you don't, in the same line of inclusion/extension, mix the two.

I'm looking at one project right now... There are a base layout. There are a couple of base templates inherited from that layout. There are templates inherited from base templates. There are mixins in separate files.

I fail to see why a base layout should look any different than all other files.

This breaks the basics that he has just learned.

How is it differ from implicit inline scripts you mentioned? I saw them used very widely as well.

[stuartpb]

I fail to see why a base layout should look any different than all other files.

See the re-worded explanation.

This breaks the basics that he has just learned.

How is it differ from implicit inline scripts you mentioned? I saw them used very widely as well.

Usually sites will do scripts and styles in separate files, and look at inlines as bad practice.

[sintaxi]

Ok, correct me if you think this is wrong.

This deprecation is bad for new people coming to Jade (post v1) as it seems likely they will run into either documentation or code that has the !!! & 5 doctype.

This deprecation punishes early adopters (pre v1) who almost certainly have applications that this will needlessly break.

Considering that this makes up 100% of Jade users, the question must be asked, who does it benefit to have this removed? My best guess is that it is for a long term benefit by reducing the API surface area. If so, can someone somehow quantify this benefit? Is there something in the roadmap that will need the !!! cleaned up? Or is there implementation complexity that needs to be reduced? If so, please share.

From mine, and what appears to be others perspective, the cost vs benefit was not properly weighted before making this change, and it would be better for everyone involved if the !!! & 5 doctype were added back into the codebase, removed from the documentation, and then never spoken of again.

[ForbesLindesay]

!!! 5 punishes all new users as it's a WTF moment where you go why the hell does that mean doctype html. Docs don't get updated if they still work. Now that they don't work, I have every confidence people will be updating docs/examples all over the place.

It does hurt many early adopters, but those people had plenty of time to voice their concerns before the code was released.

It's too late now for all the reasons I have discussed in #1374. If you genuinely believe that this deprecation was not handled properly and that this represents a problem, I have outlined what needs to be done to create a version that properly documents the breaking features in a pre 1.0.0 release. Alternatively, if you don't believe that and instead just find it inconveniences you, I suggest locking your version numbers to pre 1.0.0 releases and enjoying that version of jade instead. It mostly worked pretty well, but I suspect most people will prefer the newer versions with all the bug fixes and better features.

[sintaxi]

This is very disappointing. I hoped you would be more reasonable.

[stuartpb]

!!! 5 punishes all new users as it's a WTF moment where you go why the hell does that mean doctype html.

And what is your source for this conclusion, exactly? What real person have you spoken to that had a hard time with this syntax? Of the people I've shown Jade, nobody has had problems understanding the idea of !!! at the top of a file standing in for the DOCTYPE declaration.

It does hurt many early adopters, but those people had plenty of time to voice their concerns before the code was released. It's too late now for all the reasons I have discussed in #1374.

#1374 (comment)