No dedicated documentation

[TimothyGu]

I am sure this is on someone's TODO list but just adding a bug to track it. By dedicated documentation, I mean a website with all the API methods, options, etc., like Jade's.

[mde]

When you say dedicated docs, do you mean something beyond the README? Are you thinking GH pages, or an actual site?

[TimothyGu]

Are you thinking GH pages, or an actual site?

Either one is fine. My hope is that there is a nice page with all the things about EJS (v2) that pops up first on Google, not this, not this, and not this.

[mde]

Good call. Thanks for opening this issue to get the ball rolling.

[dougwilson]

Btw, if you can get tj to move the repo, it would go a long way getting people to the right place. You can delete this one, have tj move his t you here, and then just replace it's contents with your current git code. This way the tj/ejs URL would redirect here and all the issues would too :)

[TimothyGu]

@dougwilson +1

[mde]

I didn't really want to take that approach because I wanted to be super respectful of TJ's authorship of v1, and because the v2 is actually an older version of EJS of mine (circa 2008 or so) with a completely different implementation and its own commit history. I suppose it would be possible to do something like that and preserve the history of both repos.

[dougwilson]

Ah. I didn't realize they don't even share the same history, though :) I just saw a really large number of commits here, haha. The other repo could probably at least have a notice added to the top of the readme, if not already there. The biggest thing is I see that people keep filing new issues over there, but at least I see you're watching to repo :D

[mde]

I did add a notice to the top of the README, but it could be made more obvious. Maybe replace the entire README.

[dougwilson]

Ah, yea, but it's probably confusing. It sounds like you're just pointing people to some future module. It should probably be clearer that your module replaces that and issues shouldn't even be filed there (unless you plan to make 1.x bug fix releases or something).

[TimothyGu]

Even more confusing: https://www.npmjs.com/package/ejs2

[mde]

@dougwilson Good call. Probably just blowing the README away and replacing it with nothing but a single clear message that says v2 has replaced v1 completely, and no further maintenance is happening there.

@TimothyGu Oh, wow. This is pretty terrible. Maybe we can convince him to unpublish.

[TimothyGu]

@mde simontabor/serenity-ejs#2

Back to the original topic of documentation. I can add some JSDoc inline docs and maybe move the documentation in README to a GH pages. I'll submit a PR when I finished.

[puzrin]

Can you advice a safe & simple way, to distinguish between 2.x and older versions? Needed for transparent legacy support.

[mde]

@TimothyGu This is great. I'm back and forth with the owner of ejs.co, but the cost might be prohibitively high.

[mde]

@puzrin, I assume you mean something other than the package.json? You want something that lives on the exported object?

[puzrin]

https://github.com/nodeca/mincer/blob/master/lib/mincer/engines/less_engine.js#L99 see example for less (it's ugly, i know).

Sometime it's not acceptable to have strict versions dependencies. So, adapter has to detect library version somehow, to make proper call. Library can be passed via params, we can't rely on require('ejs/package.json')

var ejs; // here can be v1.x or v2.x

/* How to distinguish? */

I'm asking in docs, because question seems related to "migration guide"

[mde]

I've done something like this before, making it part of the build/release process:

https://github.com/mde/timezone-js/blob/master/src/date.js#L58

It makes total sense for client-side use. Could you open a GH Issue for this?

[mde]

Looks like we'll be getting ejs.co for our doc site. I have just have to finalize the payment arrangements.

[TimothyGu]

@mde oh wow, thanks

[mde]

@puzrin, versioning-detection issue here: #30

[puzrin]

@mde thanks!

[TimothyGu]

Syntax documentation done in #29.

API documentation in JSDoc form done in #45.

[mde]

Site is on the way. First cut of it lives here for now: https://github.com/mde/ejs-site

[mde]

New site is up at http://ejs.co -- not much there yet, basically just brochureware with a copy of what's in the README. But a step in the right direction.

[TimothyGu]

@mde Already looking nice though. Nice job! :)

[RyanZim]

@mde Do you still have push access to tj/ejs?

If so, how about putting a notice like this at the top of the README:

This repo is UNMAINTAINED

EJS v2 is now being actively developed at https://github.com/mde/ejs

Please report all issues there.

If you are upgrading from v1, you may want to look an the CHANGELOG for v2.

[kjkent]

It would be great to see the existing documentation built upon. Perhaps as a result of features being added/removed over the years, or perhaps that it's easy to forget while writing docs that others may not have the same insights/familiarity, some of the existing wording is not very comprehensible unless already familiar with the topic. An example:

• Layouts:

  EJS does not specifically support blocks, but layouts can be implemented by including headers and footers...

  There's a bunch of open issues, PRs, comments regarding reusing layouts, the deprecation of partial, introduction of include, but no clear explanation of what limitation is being expressed by 'does not specifically support blocks'. It's the first sentence in a section about creating layouts. As a page can be composed of more than header/footer/main content, what's being said here? An unaware person would likely look to the include docs to find out:

• Include:

  Includes are relative to the template with the include call. (This requires the 'filename' option.) For example if you have "./views/users.ejs" and "./views/user/show.ejs" you would use <%- include('user/show'); %>.

  You'll likely want to use the raw output tag (<%-) with your include to avoid double-escaping the HTML output.

  But... what can I include? The docs suggest other EJS files, but the first sentence of the Layouts section tells me EJS doesn't specifically support blocks, which presumably means the EJS I'm including must have some constraints.

Both of the above sections skip a few links in the 'what, why, where, when, how' chain of understanding; both discussing very specific syntax without a explaining the basic function and use cases. Working on the docs is a time investment that pays back in less "how does this work?" issues being filed, and a much nicer time for users.