Annotating code samples with file names

[emberjs]

Annotating code samples with file names

[locks]

Thanks for the ping!

I was actually instructed to open a new RFC for the pod structure so all the details can be hashed out.
This will enable ember-cli to then make pod structure the default, which IIRC is the current intent.
That's my rationale for using it in the file paths.

I'm confused by your example @stevekinney, since globals are to be deprecated, but I would include the
file path anyway, it's very easy to get lost otherwise if you're new to it.
I've also been including the imports and anything i feel necessary (e.g. https://github.com/emberjs/guides/pull/8/files#diff-98f6b706ad0759bf694f2cb81ce0d495R74) to make it self-contained.

[stevekinney]

Sounds good. (Yea, a big point is to get rid of the globals—I was only using it as an example where the file name might not be important.)

[joostdevries]

@stevekinney excellent point. my thoughts:

• use foo and bar for pointless stuff.
• whether or not we advise pods in the guides is something I'd like @tomdale and @stefanpenner s take on.

[stefanpenner]

whether or not we advise pods in the guides is something I'd like @tomdale and @stefanpenner s take on.

i would like to , but their are several different and potentially confusing manifestations of pods. Maybe not yet? ... @tomdale thoughts?

[locks]

@stefanpenner I'll open an RFC for pod structure this week as suggested by @wycats, so we clear it up. Sounds good?

[stefanpenner]

@stefanpenner I'll open an RFC for pod structure this week as suggested by @wycats, so we clear it up. Sounds good?

yes. Also, relevant POD related ember-cli issues: https://github.com/ember-cli/ember-cli/labels/pod Worth reviewing for the RFC.

[stevekinney]

#13 is tangentially related. How do we want to call various controllers, routes, etc. outside of code samples? Refer to them by file name? controller:application? Keep the current format?

[tomdale]

I don't have a strong opinion either way. All I'd ask is:

1. Make sure the guides and Ember CLI generators are in alignment.
2. Make sure any remaining issues with pods are hashed out.

If in doubt, let's start with non-pods and switch over. Versioned guided give us a lot more flexibility to change in the future. I don't want this guide revamp to end up getting blocked on pod implementation details.

[joostdevries]

Related, maybe it's smart to hint people to use ember generate wherever possible.

[nicolechung]

Does the POC of Ember cli work with a pods structure? http://jsbin.com/zonuhofufo/1/edit?html,output

[trek]

I have thoughts on where file names should go. http://commonmark.org/ defines the area we normally put the language label in "fenced code" as simply "metadata".

So, where we normally put

```javascript
var someCode;

Could actually contain any data we'd like. We have a custom highlighter that outputs particular markup/styles for specific languages.

The spec allows you to put any meta data in that location. Language is just a common use.

Instead of comments to denote file names, I'd prefer if we did this:

```app/templates/foo.hbs
{{rock-on}}

This should do three things:

• continue to detect bare named language fences
• begin to detect language name from file path fences
• output nice markup/style that decorates an HTML code block something that shows file location

[stevekinney]

@trek Wow, I really like that idea.

[trek]

Can you rope in @gregone and/or @danmcclain to help with the visual design and CSS for a change like this?

[locks]

@trek 👍 had thought of something similar myself, but didn't know about the meta data thing.

[joostdevries]

@trek Looks amazing. I actually think the original issue here has been resolved (we will not use POD syntax for now). Maybe it's best to either rename this issue or close & open a new one for the new code blocks

[danmcclain]

How's something like this (don't mind the colors for now...unless you like them, then it was intentional 😉)

[locks]

👍
On 5 Mar 2015 18:45, "Dan McClain" [email protected] wrote:

How's something like this (don't mind the colors for now...unless you like
them, then it was intentional [image: 😉])
[image: ember js - templates the application template 2015-03-05 13-45-05]
https://cloud.githubusercontent.com/assets/144138/6511903/e7978fd2-c33d-11e4-9135-4b579526f74e.png

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

[danmcclain]

The markup is super basic for it too, all we have to add is

<thead>
  <tr>
    <td colspan="2">File name</td>
  </tr>
</thead>

To the top of the <table> generated by the highlighter. The screenshot I posted was one without any styles applied. We can tweak the look futher if needed

[joostdevries]

👍

[trek]

actually think the original issue here has been resolved

moved to #30