start talking about polymer.dart

start talking about polymer.dart

BUG=
R=jmesserly@google.com

Committed: 2e7be28

[sethladd, 2013-09-04 15:49:53]

here's the formal CL

[mem, 2013-09-04 17:39:55]

Looks really good. Some editing comments.

mem

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
File src/site/articles/web-ui/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/index.markdown:53: Upgrade to Polymer.dart today!
I'm surprised we're encouraging people to upgrade now. That wasn't the
impression I had yesterday.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/index.markdown:62: [Polymer.dart](/polymer-dart/), with
many fixes and improvements.
with -> which provides

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/index.markdown:64: The contents of this page apply only
to Web UI, which is now deprecated.
The contents of this page apply only -> The information on this page applies
only ...

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
File src/site/articles/web-ui/spec.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/spec.markdown:25: </aside>
Same changes as from web-ui/index.html

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
File src/site/articles/web-ui/summary.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/summary.markdown:24: </aside>
Same changes as from web-ui/index.html

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
File src/site/articles/web-ui/tools.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/tools.markdown:17: </aside>
Same changes as from web-ui/index.html

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
File src/site/docs/tutorials/custom-elements/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
src/site/docs/tutorials/custom-elements/index.markdown:56: including tips on
porting Web UI apps to polymer.dart
is polymer.dart supposed to be Polymer.dart? I think it's capitalized it in
other places.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
File src/site/docs/tutorials/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
src/site/docs/tutorials/index.markdown:165: </aside>
Did you look at what this looks like in the browser? I'm concerned this doesn't
format well in a tab. I added a single sentence to this rather than the whole
aside. But if it looks all right I'm fine with the whole bit of text.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
File src/site/docs/tutorials/templates/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
src/site/docs/tutorials/templates/index.markdown:66: target="_blank">code
repo</a> on github.
again, what is the appropriate capitalization of polymer.dart?

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
File src/site/docs/tutorials/web-ui/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
src/site/docs/tutorials/web-ui/index.markdown:69: target="_blank">code repo</a>
on github.
again, what is the appropriate capitalization of polymer.dart?

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
File src/site/polymer-dart/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:81: across the modern web.
If I'm coming to this without ever seeing Web UI before, this paragraph doesn't
help me. A sentence or two about what it will do for me here would be nice. I
like the language from the polymer project home page:
     A set of comprehensive UI and utility components for building web
applications.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:94: Create your own HTML tags that
encapsulate
tags that -> tags to

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:105: Live, two-way bindings for Dart
objects and DOM nodes.
for Dart objects -> between Dart objects

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:131: Below is a very simple custom element.
More advanced custom elements
remove "very"

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:164: Sync object models and DOM nodes with
live, two-way data binding.
Synchronize DOM nodes and object models using live, two-way data binding.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:168: element's `<template>`. When the count
field changes, the text also
should count be in code font?

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:197: Control the UI with declarative
conditionals and loops on templates.
Don't mention loops here. You've got that in a section by itself below.

Hows about:
Instantiate UI elements with declarative template conditionals.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:233: Loop through a collection, rendering a
template for every item in the collection.
you're not really rendering a template so much as instantiating it. right?

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:263: Reuse and share custom elements with
pub, the Dart package manager.
The term pub is overloaded. It's both the tool and the repo site. Should
probably be specific about which one you are referring to. 

Link the word pub to 
https://www.dartlang.org/docs/dart-up-and-running/contents/ch04-tools-pub.html

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:284: the Dart package manager. Add the
following to
the Dart package manager -> the Dart shared package repository.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:310: for developers upgrading from
The list isn't really "here".

[Upgrading to polymer.dart from Web UI](upgrading-to-polymer-from-web-ui.html)
provides a non-exhaustive set of tips to help you upgrade.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:318: latest Firefox, and latest Chrome for
Android.
does it pass?

Polymer.dart works with ...

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:322: Polymer project.
first use of the term polyfill. What is it?

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:345: to learn how to contribute patches.
to inspect the code and contribute patches.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:359: * Index iteration available as
variable inside of loops
Weird to have a list of one.

Also the wording is awkward. Perhaps....Value of index variable available inside
of loops.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:363: One of Polymer.dart's goal is to make
the entire Polymer project available
One of our goals is to make ... or
One of our goals is that Polymer.dart provides the entire Polymer project to
Dart developers.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:398: video featuring some of the leads of
the
some of the leads -> lead members

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
File src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:26: Not the old
and new value. You have to use mirrors to get the new value.
-> field name, not the old and new value.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:58: * Similar to
boot.js required to be in `<head>`, your .dart script
Just as boot.js is required to be in ....

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:63: is now set
as a getter property on the class for the custom element. e.g.:
is now set as a  getter property -> is now a getter property

[sethladd, 2013-09-04 21:11:02]

thanks!

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
File src/site/articles/web-ui/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/index.markdown:53: Upgrade to Polymer.dart today!
I'll take it out.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/index.markdown:62: [Polymer.dart](/polymer-dart/), with
many fixes and improvements.
On 2013/09/04 17:39:55, mem wrote:
> with -> which provides

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/index.markdown:64: The contents of this page apply only
to Web UI, which is now deprecated.
On 2013/09/04 17:39:55, mem wrote:
> The contents of this page apply only -> The information on this page applies
> only ...

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
File src/site/articles/web-ui/spec.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/spec.markdown:25: </aside>
On 2013/09/04 17:39:55, mem wrote:
> Same changes as from web-ui/index.html

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
File src/site/articles/web-ui/summary.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/summary.markdown:24: </aside>
On 2013/09/04 17:39:55, mem wrote:
> Same changes as from web-ui/index.html

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
File src/site/articles/web-ui/tools.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/articles/web-...
src/site/articles/web-ui/tools.markdown:17: </aside>
On 2013/09/04 17:39:55, mem wrote:
> Same changes as from web-ui/index.html

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
File src/site/docs/tutorials/custom-elements/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
src/site/docs/tutorials/custom-elements/index.markdown:56: including tips on
porting Web UI apps to polymer.dart
I've been trying to use polymer.dart unless it's the first work in a sentence.
What feels better?

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
File src/site/docs/tutorials/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/docs/tutorial...
src/site/docs/tutorials/index.markdown:165: </aside>
seems to look fine.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
File src/site/polymer-dart/index.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:81: across the modern web.
Good point. I moved the reference to Web UI down.

The masthead says: Build structured, encapsulated, client-side web apps with
Dart and web components.

The problem with using polymer's statement verbatim is that there aren't yet
dart ports for the UI and utility components.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:94: Create your own HTML tags that
encapsulate
On 2013/09/04 17:39:55, mem wrote:
> tags that -> tags to

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:105: Live, two-way bindings for Dart
objects and DOM nodes.
On 2013/09/04 17:39:55, mem wrote:
> for Dart objects -> between Dart objects

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:131: Below is a very simple custom element.
More advanced custom elements
On 2013/09/04 17:39:55, mem wrote:
> remove "very"

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:164: Sync object models and DOM nodes with
live, two-way data binding.
On 2013/09/04 17:39:55, mem wrote:
> Synchronize DOM nodes and object models using live, two-way data binding.
> 

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:168: element's `<template>`. When the count
field changes, the text also
On 2013/09/04 17:39:55, mem wrote:
> should count be in code font?

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:197: Control the UI with declarative
conditionals and loops on templates.
On 2013/09/04 17:39:55, mem wrote:
> Don't mention loops here. You've got that in a section by itself below.
> 
> Hows about:
> Instantiate UI elements with declarative template conditionals.

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:233: Loop through a collection, rendering a
template for every item in the collection.
On 2013/09/04 17:39:55, mem wrote:
> you're not really rendering a template so much as instantiating it. right?

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:263: Reuse and share custom elements with
pub, the Dart package manager.
On 2013/09/04 17:39:55, mem wrote:
> The term pub is overloaded. It's both the tool and the repo site. Should
> probably be specific about which one you are referring to. 
> 
> Link the word pub to 
> https://www.dartlang.org/docs/dart-up-and-running/contents/ch04-tools-pub.html

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:284: the Dart package manager. Add the
following to
On 2013/09/04 17:39:55, mem wrote:
> the Dart package manager -> the Dart shared package repository.

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:310: for developers upgrading from
On 2013/09/04 17:39:55, mem wrote:
> The list isn't really "here".
> 
> [Upgrading to polymer.dart from Web UI](upgrading-to-polymer-from-web-ui.html)
> provides a non-exhaustive set of tips to help you upgrade.

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:318: latest Firefox, and latest Chrome for
Android.
"is tested" doesn't imply passing or failing, so I was trying to be more subtle.
It should be passing. :)

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:322: Polymer project.
On 2013/09/04 17:39:55, mem wrote:
> first use of the term polyfill. What is it?

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:345: to learn how to contribute patches.
On 2013/09/04 17:39:55, mem wrote:
> to inspect the code and contribute patches.

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:359: * Index iteration available as
variable inside of loops
agreed... what else do we need in this list?

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:363: One of Polymer.dart's goal is to make
the entire Polymer project available
On 2013/09/04 17:39:55, mem wrote:
> One of our goals is to make ... or
> One of our goals is that Polymer.dart provides the entire Polymer project to
> Dart developers.

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/index.markdown:398: video featuring some of the leads of
the
On 2013/09/04 17:39:55, mem wrote:
> some of the leads -> lead members

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
File src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:26: Not the old
and new value. You have to use mirrors to get the new value.
On 2013/09/04 17:39:55, mem wrote:
> -> field name, not the old and new value.
> 

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:58: * Similar to
boot.js required to be in `<head>`, your .dart script
On 2013/09/04 17:39:55, mem wrote:
> Just as boot.js is required to be in ....

Done.

https://chromiumcodereview.appspot.com/23619013/diff/1/src/site/polymer-dart/...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:63: is now set
as a getter property on the class for the custom element. e.g.:
On 2013/09/04 17:39:55, mem wrote:
> is now set as a  getter property -> is now a getter property

Done.

[Jennifer Messerly, 2013-09-04 22:01:31]

lgtm by the way

I'm fine with either Polymer.dart or polymer.dart. The former is nice because
it's a proper name and Polymer itself is normally capitalized. The latter is the
convention used by many JS libraries such as node.js. Strangely, "polymer.js"
originally referred to the file, but people are now using it to mean the JS
version of Polymer (as opposed to the Dart version). Confusing :)

If it was me I would lean towards "Polymer.dart", but that's just my 2 cents :)

[Jennifer Messerly, 2013-09-05 04:04:18]

a few comments here. Also sent you a version which changes:
* organize bullets into a categories
* add links to apidocs, pub where appropriate
* add links to issues
* clarify some of the points
* add a few more notes :)

https://chromiumcodereview.appspot.com/23619013/diff/16001/src/site/polymer-d...
File src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown (right):

https://chromiumcodereview.appspot.com/23619013/diff/16001/src/site/polymer-d...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:40: if
necessary. See [https://code.google.com/p/dart/issues/detail?id=12254]
did you mean: [issue
12254](https://code.google.com/p/dart/issues/detail?id=12254)

https://chromiumcodereview.appspot.com/23619013/diff/16001/src/site/polymer-d...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:47: `extends`
attribute, you are safe to use `<my-element>`.
replace "are safe to" with "should use"

https://chromiumcodereview.appspot.com/23619013/diff/16001/src/site/polymer-d...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:59: needs to be
in `<body>`, ideally at the end.
I'm not sure this is true anymore?

https://chromiumcodereview.appspot.com/23619013/diff/16001/src/site/polymer-d...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:60: This might
change, see https://code.google.com/p/dart/issues/detail?id=12388
[issue 12388](https://code.google.com/p/dart/issues/detail?id=12388)

https://chromiumcodereview.appspot.com/23619013/diff/16001/src/site/polymer-d...
src/site/polymer-dart/upgrading-to-polymer-from-web-ui.markdown:63: is now
retrieved as a getter property on the class for the custom element.
nit: "getter property" is a bit awkward, perhaps just "getter"

[sethladd, 2013-09-06 00:34:52]

Committed patchset #8 manually as r2e7be28 (presubmit successful).