Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Marko v3: Support concise (Jade-like) syntax #211

Closed
patrick-steele-idem opened this Issue Jan 20, 2016 · 40 comments

Comments

Projects
None yet
10 participants
@patrick-steele-idem
Copy link
Contributor

patrick-steele-idem commented Jan 20, 2016

With a few tweaks to the current parser, we could simultaneously support a new concise, Jade-like syntax. A sampling of the proposed syntax is shown below:

<!-- Basic JavaScript constructs -->
var colors=['red', 'green', 'blue']

<!-- Placeholders, looping and conditionals -->
ul if(notEmpty(colors)) 
    li for(color in colors)
        | <b>${color}</b>
div else | No colors!

<!-- Custom tags with wrapped attributes -->
greeting [name="Frank"
    message-count=10]

<!-- Macros -->
macro navLink(href, title, isActive)
    li class=(isActive ? 'active' : null)
        <!-- HTML-JS parsing mode in the same document -->
        <a href="href">
            ${title}
        </a>

ul
    navLink href="/" title="Home" isActive=true
    navLink('/about', 'About', false)

@patrick-steele-idem patrick-steele-idem self-assigned this Jan 20, 2016

@patrick-steele-idem patrick-steele-idem added this to the 3.0-alpha milestone Jan 20, 2016

@yomed

This comment has been minimized.

Copy link
Contributor

yomed commented Jan 20, 2016

Is there clamoring for jade-like syntax? I guess the current HTML-like syntax makes marko somewhat opinionated, but I didn't think that was problematic.

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 20, 2016

From various interactions I have found that there are a lot of people who would consider using Marko, but much prefer the Jade syntax. On the flip side there are a lot of developers that dislike the Jade-style syntax because it is too far removed from real HTML.

With that in mind, Marko has a lot of benefits that are independent of the input syntax/dialect:

  • High performance and minimal runtime
  • Custom tags
  • Extensible at compile-time
  • Async rendering
  • CommonJS modules as compile output
  • Marko Widgets support
  • etc.

The input template is relatively small (but important) piece of Marko. I believe that if we can offer a Jade-like dialect for Marko then we will be able to attract additional developers to the project.

It's of course worth pointing out the negatives of supporting an alternate dialect:

  • Fragmentation within the Marko community
  • Development cost of supporting a two dialects (hopefully a minimal, one time cost)

Regarding "Fragmentation within the Marko community", my thinking that is better to grow the community. In addition, I want to keep the two dialects very similar such that there is a direct and perfect translation between the two. In fact, we could easily provide tools for converted from one dialect to the other with no change in behavior or loss of information.

Regarding "Development cost of supporting a two dialects", I do feel like development effort is not too burdensome and it will be a single parser that supports both dialects.

We are leaning towards using an alternate .jarko file extension for Marko with the Jade-like syntax. All of the Marko documentation would use the non-concise syntax and there would be one page of documentation that would explain the rules for the concise syntax for those who want to use it.

I opened the issue to invite discussion so if you have any other thoughts please share.

@yomed

This comment has been minimized.

Copy link
Contributor

yomed commented Jan 20, 2016

I agree with your main points - I think as long as the new parser is generic enough to easily support multiple syntaxes, neither fragmentation nor maintenance costs should really be an issue. jarko sounds funny too, so that's a plus.

@philidem

This comment has been minimized.

Copy link
Member

philidem commented Jan 21, 2016

I was on the fence about this at first but there a lot of people that are passionate about Jade so there must be some merit for its success. One of the subtle but elegant things about the jarko dialect that has been proposed is that you could drop in normal HTML or Marko and it would just work because the parser would know to switch to HTML/Marko mode when it sees an opening tag.

If Jarko was available, I would definitely give a try to see if it would grow on me. I might enjoy not having to type all of those < and > characters.

Also, does anyone feel like the Jarko name is a bad idea? Could it lead to confusion? The alternative might be that we refer to it as concise Marko but I am not sure if that is better.

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 21, 2016

Initially I didn't think it was a good idea, but I feel like the concise syntax might grow on me as well. It would need proper editor support for good syntax highlighting. I suspect that if I were to use the concise syntax then I might have a hard time switching back to the non-concise syntax. I like that the concise syntax allows the normal HTML syntax to be mixed in. This allows regular HTML to be pasted in without having to take the time to reformat it.

I'm very curious to se what the community thinks as well. I'm willing to put this out there as an experiment to see what others gravitate to.

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 21, 2016

I dunno. Back in my day we didn't need these newfangled languages to write HTML. We wrote our <blink> tags uphill both ways and we never complained about it. 😛

In all seriousness though, the development cost of supporting another dialect is something that should be well considered. I'd really hate to see Marko development slowed or delayed due to the support of a (fringe) dialect. Yeah, I said it.

Also, consider that Marko is already an HTML-like syntax, and it sounds like you'd be creating a "jade-like" syntax. Since Marko is an abstraction of HTML, and Jade is already an abstraction of HTML, Jarko would therefore be an abstraction of an abstraction. Talk about fringe.

Sass (or Less) is a good example of a useful abstraction—the benefits of using Less or Sass to write CSS are huge (variables, nesting, extensions, modularization)—and they are still mainly pure CSS at their core. But with Jade, you're basically just talking about laziness and simple dialect. I don't see the benefit beyond the popularity/adoption points. Just my 2¢.

@laggingreflex

This comment has been minimized.

Copy link

laggingreflex commented Jan 21, 2016

+1 Btw the name Jade is changing to Pug with v2 so jarko might not be a good idea. Also I think this concise syntax is a lot different from Jade (better in that sense), so it shouldn't be named after it, it should have its own identity. "concise-marko" sounds perfect. or if it's too long, maybe "cmarko"?

@philidem

This comment has been minimized.

Copy link
Member

philidem commented Jan 21, 2016

I am aware of the rename to "pug" but a lot of people are still going to remember it as Jade. The name "mug" was also proposed (which kind of fits in nicely with the coffee/java/javascript theme).

What are your thoughts on "mug" as the dialect name?

As far as as the development effort to support another dialect, I think @patrick-steele-idem has done a lot of great work to make the effort minimal so I don't think that is a big concern (but maybe we'd learn differently after experimenting a little). The event-based parser would emit the same events for both dialects so might not be that bad.

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 21, 2016

.pugo

Just kidding. Mug is better.

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 21, 2016

There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

@tindli

This comment has been minimized.

Copy link
Contributor

tindli commented Jan 21, 2016

Following the discussion, I want to add a few pros/cons I have found... (some are already mentioned)

Pros:

  1. Gain additional attraction from the dev community; Everything that looks familiar will improve the adoption rate of Marko - as Marko is still growing, this is important
  2. Makes life easier by putting over legacy code written in Jade; we all know that putting something over without changes seldom works flawlessly... but it should be less work than porting over existing markup into Marko v3....
  3. Easy to get started for people who worked already with Jade... similar to point 1.

Cons:

  1. "Readability" While Jade offers a sparse syntax, I do not really think it offers much more "readability" than Marko v3... I think template statements do not really "raise from the environment"; it makes it really hard to see what is really going on without looking at it in detail... on the other hand, Jade might reduce "noise" by having less stuff that has to be written ("<", ">"...) - it both has its advantages...
  2. "Fragmentation" what are the examples written in - with JavaScript server and client side we left the times when there were different languages (and the mental overhead between switching between them). Now with different template languages we kinda "sacrifice" that...
  3. Implementation (+ testing) overhead + maintenance... strongly depends how it is implemented... I am confident that the Marko devs can do a great job here.... but it should be considered nevertheless....

Marko v3's main selling point is "as close to HTML" as possible... one could ask if this is really "enough" to have it... why not consider Jade-like as the only template syntax? If there will be a way to easy auto-convert Marko v3 into Jade (and back?) why not have jarko the only syntax and allow people to auto convert over Marko v2 into Jarko (if compatibility is an issue)?

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 21, 2016

why not consider Jade-like as the only template syntax?

Please, no. Abstraction languages come and go—they are in a sense fads. HTML is universally known and familiar to most developers.

@adammcarth

This comment has been minimized.

Copy link

adammcarth commented Jan 21, 2016

I'm with @danrichman. I think ditching the proper HTML-like syntax all together would be a mistake, at least at this stage. That said, I'm all for giving the jade-like syntax a go. If you can bake both of them into a universal Marko compiler, I think it's going to be a really great move @patrick-steele-idem. Let people decide how they want to use Marko.

There are some drawback's you guys might want to consider though:

(1) As Marko matures and the user base grows, the ambiguity of questions online could get quite confusing for developers. Consider someone researching how to do something in Marko, and they scour through StackOverflow, videos, blog posts etc... 50% of answers with one syntax, 50% with the other syntax. People are going to end up with some kind of psuedo marko language in their app, where they have a mixture of the compact syntax and traditional syntax. That's a bad experience for everyone.
(2) More documentation, and it's going to have to be really well written to avoid confusion.
(3) Ultimately there's probably going to have to be two seperate docs - one for traditional Marko, the other for compact.

I think you can get around both of those issues with really well defined documentation, and pushing out the message early on that there's two syntax options with Marko. But for that to happen, we all need to be up for that challenge. Personally I hate Jade syntax with a passion, but damn, it's 2016. I'll willing to give new things a try.

@tindli

This comment has been minimized.

Copy link
Contributor

tindli commented Jan 22, 2016

Just to be clear:

Having Jade-like (jarko/mug) as the default would mean to prepend every plain text with a specific well-defined symbol (e.g. a dot)... otherwise plain text would be mis-interpreted as a tag (original Jade uses pipes for plain text)

Regular HTML like syntax would of course be allowed as well (and mixed in within jarko):

. This has to be prefixed
<div>
  No worries here
</div>
@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 22, 2016

Jade is a rabbit hole. Could be a third-party option, but as a core feature? I dunno. One of the selling points of Jade, according to its own website is...

Jade is a terse and simple templating language with a strong focus on performance and powerful features.

This is a good reason to avoid Jade actually. Something more powerful is always coming along. Why would we want more powerful features if Marko is intentionally trying to adhere to the Rule of Least Power?

The Rule of Least Power
http://www.w3.org/2001/tag/doc/leastPower

When designing computer systems, one is often faced with a choice between using a more or less powerful language for publishing information, for expressing constraints, or for solving some problem. This finding explores tradeoffs relating the choice of language to reusability of information. The "Rule of Least Power" suggests choosing the least powerful language suitable for a given purpose.

[...]

Good Practice: Use the least powerful language suitable for expressing information, constraints or programs on the World Wide Web.

I was under the impression that Marko was designed to adhere to the Rule of Least Power. By promoting Jade, it's no longer adhering to that rule.

See also:

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 22, 2016

As @tindli mentioned. We have no intentions to get rid of the HTML syntax. We are only trying to figure out if the HTML dialect can coexist with the concise syntax. We have the following options:

  1. Only allow concise syntax for a separate file extension (e.g. .jarko)
  2. Allow concise syntax and HTML syntax in same file (starting out in concise mode is probably the only good option)
  3. Don't bother with concise syntax at all

Supporting mixed dialects in the same file (option 2) almost works perfectly exactly when a developer who prefers HTML wants to put plain text at the root (outside an HTML tag). The parser would need to start out in concise mode and that would cause the first word of the plain text to be "incorrectly" interpreted as a tag name (it needs to be prefixed)

There's also still some debates around the concise syntax. @tindli pointed out that . might be a better choice since you don't have to press the shift key (easier to type). I would much prefer to avoid the shift key.

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 22, 2016

I was under the impression that Marko was designed to adhere to the Rule of Least Power. By promoting Jade, it's no longer adhering to that rule.

@danrichman For Marko v3 syntax and the concise Jade-like syntax would parse into exactly the same AST (the same internal representation). Therefore, there would be no difference in power. The Jade-like syntax is just HTML without < and > and indentation is used to control nesting and there is one extra prefix symbol to escape out of indentation mode...everything else is identical. Neither dialect brings any extra power to the table.

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 22, 2016

@patrick-steele-idem Isn't there more to Jade than that? Conditionals, extends, etc. Wouldn't Jade developers just end up demanding those more powerful features?

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 22, 2016

@patrick-steele-idem Isn't there more to Jade than that? Conditionals, extends, etc. Wouldn't Jade developers just end up demanding those more powerful features?

@danrichman maybe starting this conversation with "Jade" was a bad idea. We are less interested in the features of Jade and more interested in the concise syntax that it offers.

Wouldn't Jade developers just end up demanding those more powerful features?

Marko has all those features (and more) already, but in just a different form. For example, Marko doesn't have support for an extends keyword, but it does offer a layout taglib for doing the same thing in a cleaner and more extensible way (I would argue, at least). Marko has conditionals, looping, custom tags, etc.

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 22, 2016

I meant that by supporting the Jade syntax, you're going to open yourself up to demands for supporting the specific (less clean) Jade-forms of those and other features—particularly as Jade becomes more complex over time. I don't know how this would be avoided. At some point, you know someone is going come along and demand more support for the Jade syntax to trigger those various features.

As in..

Hey Patrick, if would be great if the Jarko syntax could do XYZ just like in Jade.

It's a slippery slope. Where do Marko devs draw the line? Can I get a nickel for each such request? :)

@Rob-pw

This comment has been minimized.

Copy link

Rob-pw commented Jan 22, 2016

Just chiming in.. Please avoid overcomplicating marko at all costs, keep the core simple then allow extension if desired. I won't be using any of the html-like syntax anyway, in our environment the users specify mark-up over which we have no control, we will just be exposing widgets for them to hook into using attributes.

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 22, 2016

Good points @danrichman

Maybe we should deviate more from Jade to make the distinction clear. We are not trying to be Jade (I think the rules for Jade are overly complicated and error-prone), but we are trying to potentially appeal to people who like a minimal syntax and that don't like typing a lot of redundant symbols.

I'm going to give the concise syntax some more thought over the weekend and will share more later.

Thank you, all, for your feedback!

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 22, 2016

For what it's worth, some opinionated Angular devs seemed to be largely against the idea of using Jade in Angular. For starters, they say mixing the two syntaxes in Angular documentation, examples, and in templates is way more confusing than the simplicity that the syntax is supposed to provide in the first place.

See: What's the use of Jade or Handlebars when writing AngularJs apps

Q: "...As far as I can tell, it would make most sense to create the templates in Angular using proper HTML...The reason for this confusion is that a lot of the examples I find on GitHub make use of Jade, and it seems counter intuitive for me."

A: Those who unquestioningly favour Jade in an Angular environment fail to understand that view logic belongs on the client, and business logic on the server, just as the OP commented.

Don't do it unless you have a very good reason to do it. In engineering, a system with fewer moving parts is a more reliable system, and a system where interface boundaries (client/server) are respected is more maintainable over the long term, so default to the simplest architecture and clean division of labour if possible. If you have overriding reasons, do what you must, but caveat emptor.

Recently I reviewed some code where straight Angular templating would have done a far better job than mixing in Jade, just through maintaining simplicity.

Aside from template extension, Jade brings nothing worthwhile to the table that Angular doesn't already supply. Let's be honest: Using the sound principle of "favour composition over inheritance" (i.e. partials), you shouldn't ever need template extensibility. Jade is hardly "easier to parse" than HTML. They are but trivially different, while Jade adds another level of indirection - best avoided.

There is one valid, specialised case for server-side templating: Optimisation, remembering that premature optimisation is generally a Bad Thing. Where performance is truly at issue, and you have the server capacity to spare to handle this, server side templating can assist. This applies to products like Twitter and Basecamp, where the cost of doing a lot of server side work is offset by the gains of reduced requests to the server.

@scttdavs

This comment has been minimized.

Copy link
Contributor

scttdavs commented Jan 22, 2016

I just wanted to chime in on our team and experience with marko. We like marko and what it offers, but we were definitely not a fan of the syntax when we started using it. I think it would be a much more enjoyable experience to have the concise syntax, as you are putting it.

I also don't think it would be a slippery slope to supporting all jade features. The biggest gripe is that it is a pain to write in and look at, especially as files grow in size and complexity. That is why languages like jade and haml are so popular. I don't think I've used marko and ever thought "this could use some more features from x language". I have thought, however, that the template looked cluttered and hard to read/scan. But then again, I've used haml and jade for years, so the HTML like syntax seems like a step backward to me.

@philidem

This comment has been minimized.

Copy link
Member

philidem commented Jan 22, 2016

@danrichman thanks for pointing us to the Angular discussion. I imagine it might be more confusing using two distinct templating engines (not just different dialects) to build a page as is the case when doing server-side rendering of page built for Angular. I was never a fan of Angular because of the inability to pre-compile templates and I think they kind of created that problem themselves and I don't think they have a good solution. I don't think Marko has that issue since the client and server templating language will be same (regardless of whether it's the concise or non-concise dialect).

Thanks @scttdavs! Good to hear from the Jade camp :) I've always had an easier time reading HTML with all of the extra braces but I am sure that is more due to what I am use to. I think I have always rationalized typing a few extra characters for the sake of readability. It might be time to retrain my brain so that I can get faster readability and less typing.

I'm still in favor of offering a new concise syntax as an experiment and give people the challenge to try it for a little while to see if we can change some opinions. I'm curious how my own productivity would be impacted...

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 22, 2016

Thanks for sharing your thoughts @scttdavs

But then again, I've used haml and jade for years, so the HTML like syntax seems like a step backward to me.

I have heard a lot of similar comments from people who like Jade. From what I have gathered, those who have used Jade or HAML (and stuck with it) would have a really hard time going back to HTML.

For my own benefit, I took the time to find some real world Marko templates from the eBay code base and converted them by hand over to the concise syntax. I picked samples that were on the large/complex side and am finding that the HTML-based templates just look more complex than they really are and it takes me longer to make sense of the code. I'm starting to feel that the concise syntax is something that can grow on you, but that most people (me included) initially dislike it. I'm going to continue to experiment with the concise syntax. Thanks again for sharing your thoughts.

@tindli

This comment has been minimized.

Copy link
Contributor

tindli commented Jan 22, 2016

@patrick-steele-idem 👍 thanks for experimenting with real-world examples! Curious about the outcome.

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 22, 2016

Here's the rub.. Less and Sass are similar abstractions of CSS. Yet, neither abstraction is a core plugin of Lasso despite the fact that every front-end developer will tell you that Less and Sass make CSS so much easier to manage. And it's not a problem since any developer can just install lasso-sass or lasso-less....or lasso-jade (for JS) if they prefer.

So, why would Jade for Marko be any different? Why not just make it a third-party plugin? (If it becomes crazy popular, then maybe one day it becomes a core plugin).

If Jade were a core feature (never mind it's an added layer of architecture to maintain), then the question is where does that leave all the documentation, tutorials and shared examples? Do you have a competing ecosystem of documentation?

I'm starting to feel that the concise syntax is something that can grow on you, but that most people (me included) initially dislike it

I think this is probably the key point here, if anything. Anything distasteful will grow on you, eventually. Jade is being added to make Marko more accessible to the Jade crowd.

But, by making it a core feature, the risk is perhaps making Marko initially disliked by the majority of non-Jade users, which would be counterproductive. I suppose Jade could be generally avoided in the documentation, but then what's the point of having it be a core feature in the first place?

If the only reason for adding Jade-like syntax is to appease the population of Jade developers, then that implies that Jade would make a very good non-core plugin. Wouldn't that make everyone happy? People who want Jade can easily install the plugin and people who don't just follow the documentation and the HTML they are familiar with (without the mysterious . before lines of text to turn off the seemingly non-essential Jade syntax).

If the Jade-like syntax were the de facto syntax, then that would imply that the documentation, tutorials and shared examples would all be in the Jade-like syntax or some confusing mixture of the two. But, of course, doing so would turn off all the people who dislike Jade at first glance (yourself included). Is it worth it to make it a core feature then? I dunno. Seems like a third-party plugin to me, just like Less or Sass is for Lasso.

@yomed

This comment has been minimized.

Copy link
Contributor

yomed commented Jan 22, 2016

@danrichman I like that idea. If templating syntax can be abstracted out into a plugin, then marko could ship with the html-syntax plugin by default. Developers could install jade-syntax which would be responsible for its own documentation and maintenance. Plus, there is some room to experiment with new syntaxes in the future.

Eventually you need to consider what plugins should be moved to core, but it seems like we're pretty far from that point right now.

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 22, 2016

Hey @danrichman, I definitely understand where you are coming from and share your concern about documentation.

As a point of comparison, Markdown is kind of a similar story. Markdown is a concise version of HTML, but it lets you drop into HTML mode at anytime. Therefore, with Markdown you can use the concise Markdown syntax to produce HTML documents or you can use regular old HTML. With that approach you kind of get the best of both worlds and everyone is happy. The HTML within Markdown files is in no way limited by the support for a concise Markdown syntax. It's worth noting that you can't switch to concise Markdown mode within an HTML tag.

What if Marko supported something similar and allowed both concise HTML and regular HTML within the same Marko file? This could not be done with a plugin and, instead, it would require a more flexible template parser. Sure, you could use two separate parsers (or two separate plugins), but that would be a lot of duplicate code when one happens to be a superset of the other (assuming blended mode).

If we want to ever support the blended mode within the same .marko file by default then it would need to happen before the next major release. The benefit of supporting the blended mode by default is that we would have a consistent file extension (i.e. .marko) that "works for everyone". We have until the v3 release to decide.

If we are good with not supporting a blended mode, then we could release support for a blended mode using a different file extension at any point in the future (or never).

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 22, 2016

Seems like it could be risky to get married to a particular syntax in the core when, for all we know, a more popular or easier abbreviated HTML syntax might come along 2 or 3 years from now and make Jade obsolete. For instance, some people prefer Slim syntax over Jade because Slim is less cryptic. By making Jade core, nobody gets to use Slim.

In 2006 Sass was the ultimate CSS abstraction. But then Less was released in 2009 and of course now there is a choice between the two and people have their opinions about each language—even though they are nearly identical in almost every way and their syntaxes are only trivially different from CSS.

@patrick-steele-idem maybe there's a way to keep it more separated within projects. Could there be a flag at the top of individual templates to enable such an optional Jade-like syntax, for those who want it? Or is it just all or none?

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 23, 2016

Very sorry to be such a downer here 😄 but thought of another issue.

The tendency to mix Marko syntax within a large company, like eBay, could add significant risk.

Since Jade is an individual preference, this can cause issues to develop over time within a large team or organization using Marko. For instance, someone in one area of a large team or company (say eBay) prefers Jade and then they leave the company or go on vacation. A non-Jade employee—perhaps even days, months or even years later—might have to jump into those Jade files at any given time and be able to quickly troubleshoot them. A critical fix that should've taken minutes to troubleshoot ends up dragging out into far longer (perhaps hours) because the next employee to open up the files isn't familiar with the Jade syntax and can't get the complex files to build properly. In that case, the benefit of saving a few keystrokes became a liability for that company. It's a barrier to code completion, for a templating language that was intended to tear down barriers.

Actually, the same is true even within a small team, but if it's risky to mix a template syntaxes within a large company then one solution is to force all eBay developers to learn and use Jade in all of the codebase and documentation. But then the idea of it being optional would be an illusion.

As teams then attempt to avoid those inconsistencies and inevitably make team-wide standardizations to Jade, it ends up being a distasteful barrier to entry (newcomers and new hires getting up to speed, for instance) as well code sharing and information sharing. It promotes a lack of standardization because the standard would actually be Jade with documentation, tutorials and examples pretending it's HTML.

As an aside, I went to the Jade playground and tried pasting in a chunk of deeply nested/indented HTML code and I still can't get it to render the same HTML using their . or | syntax. Can we see an example of a chunk of nested HTML-preserving Jade? My initial experience suggests that this move to Jade may lead to lower adoption rates once people realize that Marko v3 is really Jade disguised as HTML. I would point out that even Jade contributors admit that Jade often makes a bad first impression.

@adammcarth

This comment has been minimized.

Copy link

adammcarth commented Jan 24, 2016

The tendency to mix Marko syntax within a large company, like eBay, could add significant risk.

@danrichman Agreed, but to use an earlier example, I think no more risk than an online newspaper using Markdown to collaborate on articles. One tech savvy journalist could start off by using HTML to draft the document with, while another journalist with no HTML experience could come along and feel inclined to either a) use HTML also, or b) use Markdown and we end up with a psuedo document.

Either way, this I think the arguments currently being presented are internal issues and beyond the scope of what Marko should have to consider.

Jade is being added to make Marko more accessible to the Jade crowd.

There also seems to be a general misconception (I think) that the Marko Concise option is being added purely for Jade user's. I think that's wrong. I hate Jade, but I feel as if I would at least give the concise option a legitimate chance - maybe even using it often in cases where I need to draft HTML quickly (in front of a client, or scaffolding for instance).

If we add this, I think it has to be shipped together under the same file name and no additional plugins required.

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 24, 2016

@adammcarth Well, if a journalist messes up a Markdown tag, the worst thing that happens is the text looks a little funny—it's one of the features of Markdown (looks publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions) and the CMS prevents them from doing any real damage to the site. If you mess up the Jarko syntax, the code fails.

Markdown isn't cryptic like Jade is. Markdown is purposefully readable as is. Jade's cryptic syntax is why some people prefer Slim over Jade.

Technically, the Markdown comparison is the opposite of what's being proposed here with Jade. When mixing Markdown and HTML, you have to opt-in to Markdown. You write standard HTML and if you want to use Markdown, you just start using the Markdown tags and enable a Markdown attribute. Easy peasy. Markdown doesn't interfere with your ability to write HTML. That really does make everyone happy.

For example...

# Heading 1

<div class="something" markdown="1">
  ## Heading 2
  Some **bold** text. Some <em>emphasis</em>.
  <div class="something-else">
    This is easy. I don't have to change my habits.
  </div>
</div>

The markdown="1" attribute is how you opt-in to Markdown when you want to use Markdown tags within an HTML tag. Everything is treated as plain text if you forget that attribute. HTML is a first-class citizen in Markdown.

With Jade, it's the other way around. Should you want to indent your HTML or plain text, you'll need to opt-out of Jade.

For example...

.  <div class="something">
.    <h2>Heading 2</h2>
.    Some <b>bold</b> text. Some <em>emphasis</em>.
.    <div class="something-else">
.      Why do I have to put
.      periods everywhere?
.    </div>
.  </div>

If you want to wrap that chunk of indented HTML with a Jade-generated <div></div> tag, you have to indent your periods like this.

#container.col
 .  <div class="something">
 .    <h2>Heading 2</h2>
 .    Some <b>bold</b> text. Some <em>emphasis</em>.
 .    <div class="something-else">
 .      Why do I have to put
 .      periods everywhere?
 .    </div>
 .  </div>

Feels almost like we're being punished for using HTML.

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 24, 2016

Hey @danrichman. That would be awful if periods were required for regular HTML, but fortunately that option is not on the table :) With mixed mode support, the following document would be a completely valid Marko template and parse hopefully as you would expect:

<div class="something">
  <!-- Everything inside this tag will be parsed as HTML -->
  <h2>Heading 2</h2>
  Some <b>bold</b> text. Some <em>emphasis</em>.
  <div class="something-else">
    Good thing there are no
    more periods.
  </div>
</div>
<!-- You can also use the concise, indentation-based dialect in the same document!: -->
div class="something"
    h2 - Heading 2
    - Some <b>bold</b> text. Some <em>emphasis</em>.
    div.something-else
        ---
        Good thing there are no
        more periods.
        ---

NOTE: The sample template above uses the latest syntax that I am experimenting with. It has a lot of advantages over Jade and should feel very natural.

Does that look good to? Best of both worlds?

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 24, 2016

@patrick-steele-idem Whew. Yes! That does look good. Sorry, I was really getting worried after trying to paste HTML into the Jade playground and coming up with nothing but errors. 💦

However, to allay further fears, can you show us how the top pure HTML would look if someone should choose to wrap it in a Jade-generated <div> tag, like #another-div?

Would the periods be necessary then?

The reason I ask is because just like a mixed HTML/Markdown example, someone may want to come along and insert HTML inside someone's #another-div Jade tag. And I don't understand how they could allow Jade to wrap their chunk of nested HTML without using periods. Thanks so much.

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Jan 24, 2016

@danrichman There will never be periods. I think the following sample template would be what you are looking for and it would also be completely valid:

#another-div
    <div class="something">
        <!-- Everything inside this tag will be parsed as HTML -->
        <h2>Heading 2</h2>
        Some <b>bold</b> text. Some <em>emphasis</em>.
        <div class="something-else">
            Good thing there are no
            more periods.
        </div>
    </div>
    span.foo - Hello ${data.name}!

The above Marko template would render the following HTML:

<div id="another-div">
    <div class="something">
        <!-- Everything inside this tag will be parsed as HTML -->
        <h2>Heading 2</h2>
        Some <b>bold</b> text. Some <em>emphasis</em>.
        <div class="something-else">
            Good thing there are no
            more periods.
        </div>
    </div>
    <span class="foo">
        Hello ${data.name}!
    </span>
</div>

The problem with Jade is that you can't simply paste in valid HTML code into a Jade document and expect things to work. We can definitely do better than Jade. If we get this right then I see no reason why anyone would want to use Jade.

@danrichman

This comment has been minimized.

Copy link

danrichman commented Jan 24, 2016

@patrick-steele-idem Fantastic. I don't know how you did it, but you've managed to create something way better than Jade. Awesome job.

Ok. I'm on board. 👍

Sorry for all the frenetic comments above. I had mistakenly gotten the impression that we were bastardizing HTML. Clearly that's not the case. I'm impressed.

The real beauty of your example is that it actually allows people to slowly dip their toe into the concise syntax—it's the best of both worlds. I can start with a single line and wrap all my HTML with it. And then I can use that single line to tip-toe into another line, and another if I please.. and so on. It’s really hard to dive into the whole Jade syntax at once. But you’ve managed to make it seemingly painless.

If we get this right then I see no reason why anyone would want to use Jade.

Yup. Completely agree. This looks awesome. Carry on.

patrick-steele-idem added a commit that referenced this issue Feb 1, 2016

@patrick-steele-idem

This comment has been minimized.

Copy link
Contributor Author

patrick-steele-idem commented Feb 1, 2016

Marko v3 now supports mixed mode parsing to allow the concise syntax and the HTML syntax within the same document. When the alpha release is published (hopefully soon) we will continue to gather feedback.

All docs will continue to use the HTML syntax since that is more approachable to new users.

@cameronapak

This comment has been minimized.

Copy link

cameronapak commented Dec 5, 2018

Thanks for doing this. Just randomly stumbled upon this thread, and it makes me happy to see the dialog that brought the Jade-like sytax into the Marko world.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.