Updated tech overview

src/site/docs/technical-overview/index.html

Index: src/site/docs/technical-overview/index.html
diff --git a/src/site/docs/technical-overview/index.html b/src/site/docs/technical-overview/index.html
index 325b454fdc4fe50a0ee31e7f6d7a8f0a649ec13e..251e872a9bea21dc1c141d149264ed3f3e14fbbe 100644
--- a/src/site/docs/technical-overview/index.html
+++ b/src/site/docs/technical-overview/index.html
@@ -6,7 +6,7 @@ title: "Technical Overview"
 
 <section>
   <p>
-  Dart is a new class-based programming language
+  Dart is a class-based programming language

[sethladd, 2012/11/01 05:23:52]

How about:

"Dart helps developers scale from small scripts to large apps as they build
high-performance apps for the modern web. Dart compiles to JavaScript and
targets modern desktop and mobile browsers."

And then continue with "Developed with..."

And then a statement like "Dart is more than a language, with the project
shipping a productive editor, a package manager, libraries, and more."  Or
something.

[Kathy Walrath, 2012/12/12 22:49:04]

Done. (But not exactly what you said. Please take a close look.)

   for creating structured web applications.
   Developed with the goals of simplicity, efficiency, and scalability,
   the Dart language combines powerful new language features
@@ -16,10 +16,12 @@ title: "Technical Overview"
 <aside>
   <div class="alert alert-info">
     <strong>Note:</strong>
-    This document is part of an early preview of
-    the Dart language and programming environment.
-    Some elements are missing from the current release,
-    and the details are subject to change based on the feedback we receive.
+    The M1 release (October 2012)
+    established a stable basis for the Dart language.
+    The language will continue to change,
+    but we expect the changes to be backward compatible.
+    The Dart libraries, on the other hand,
+    are not yet stable.
   </div>
 </aside>
 
@@ -28,21 +30,16 @@ title: "Technical Overview"
   <ol class="toc">
     <li> <a href="#key">Key features</a> </li>
     <li> <a href="#goals">Design goals</a> </li>
-    <li> <a href="#code">Show me the code </a>
+    <li> <a href="#code">Show me the code</a>
       <ol>
-      <li> <a href="#classes">Classes and interfaces </a> </li>
-      <li> <a href="#optional-types">Optional types </a> </li>
+      <li> <a href="#classes">Classes </a></li>
+      <li> <a href="#optional-types">Optional types</a> </li>
+      <li> <a href="#browser">Web apps</a> </li>
       </ol>
     </li>
-    <li> <a href="#howtouse">How can I use Dart? </a>
-      <ol>
-      <li> <a href="#editor">Dart Editor</a> </li>
-      <li> <a href="#mimetype">New MIME type </a> </li>
-      </ol>
-    </li>
-    <li> <a href="#tools">Tools </a> </li>
-    <li> <a href="#libraries">Libraries </a> </li>
-    <li> <a href="#involved">Get involved </a> </li>
+    <li> <a href="#tools">Tools</a>
+    <li> <a href="#libraries">Libraries</a> </li>
+    <li> <a href="#involved">Get involved</a> </li>
   </ol>
 </section>
 
@@ -51,26 +48,29 @@ title: "Technical Overview"
   <h2> Key features </h2>

[sethladd, 2012/11/01 05:23:52]

Maybe "Key features of the language" which then leaves room for "Key features of
the editor"

[Kathy Walrath, 2012/12/12 22:49:04]

Done.

 
   <p>
-  Key features of the Dart language include:
+  Key features of the Dart language include
+  classes, optional types, libraries, and tooling.

[sethladd, 2012/11/01 05:23:52]

I'd also include isolates as being key.

[Kathy Walrath, 2012/12/12 22:49:04]

Done.

   </p>
 

[sethladd, 2012/11/01 05:23:52]

Maybe a note about "even though Dart is familiar, we took this opportunity to
clean up some problematic areas of other commons languages and introduce
features we like from other languages"

Examples:

- lexical scope
- method cascades
- optional params
- top level functions
- one-line functions
- multi-line strings
- string interpolation

[Kathy Walrath, 2012/12/12 22:49:04]

Done.

 
   <h3>Classes</h3>
   <p>
-  Classes and interfaces provide a well understood mechanism
+  Classes provide a well understood mechanism
   for efficiently defining APIs.
-  These constructs enable encapsulation and reuse of methods and data.
+  Each class implicitly defines an interface.
+  Together, classes and interfaces
+  enable encapsulation and reuse of methods and data.
   </p>
 
   <h3>Optional types</h3>
   <p>
-  Dart programmers can optionally add static types to their code.
+  Code can have static types.

[sethladd, 2012/11/01 05:23:52]

Almost too "matter of fact". Can you talk about scalability here?

[Kathy Walrath, 2012/12/12 22:49:04]

Done.

   Depending on programmer preference and stage of application development,
   the code can migrate from a simple, untyped experimental prototype
   to a complex, modular application with typing.
   Because types state programmer intent,
   less documentation is required to explain what is happening in the code,
-  and type-checking tools can be used for debugging.
+  and tools can give more help for writing and debugging code.
   </p>
 
   <h3>Libraries</h3>
@@ -83,10 +83,10 @@ title: "Technical Overview"
 
   <h3>Tooling</h3>
   <p>
-  Dart will include a rich set of
+  Dart includes a rich set of
   execution environments, libraries, and development tools
   built to support the language.
-  These tools will enable productive and dynamic development,
+  These tools enable productive and dynamic development,
   including edit-and-continue debugging and beyond&mdash;up
   to a style where you program an application outline, run it,
   and fill in the blanks as you run.
@@ -98,8 +98,7 @@ title: "Technical Overview"
   <h2> Design goals </h2>
 
   <p>
-  The Dart programming language is presented here in its early stages.
-  The following design goals will guide
+  The following design goals guide
   the continued evolution and refinement of this open source project:
   </p>
 
@@ -131,14 +130,13 @@ title: "Technical Overview"
       so that different teams can work on them independently.
       It&rsquo;s difficult to be productive
       when a web application gets large.</li>
-    <li>Scripting languages are popular
-      because their lightweight nature makes it easy to write code quickly.
-      Generally, the contracts with other parts of an application
-      are conveyed in comments rather than in the language structure itself.
-      As a result, it&rsquo;s difficult for someone other than the author
+    <li>
+      In scripting languages, the contracts with other parts of an application
+      are usually conveyed in comments rather than in the language structure itself.
+      As a result, it can be difficult for someone other than the author
       to read and maintain a particular piece of code.</li>
-    <li>With existing languages,
-      the developer is forced to make a choice between
+    <li>Before Dart,
+      the developer was forced to make a choice between
       static and dynamic languages.
       Traditional static languages require heavyweight toolchains
       and a coding style that can feel inflexible and overly constrained.</li>
@@ -156,36 +154,44 @@ title: "Technical Overview"
 <h2>Show me the code</h2>
 
 <p>
-Here are several code snippets
+Here are some code snippets
 to give you a feel for what Dart code looks like.
 </p>
 
 <section id="classes">
-<h3>Classes and interfaces</h3>
+<h3>Classes</h3>
 
 <p>
-Dart&rsquo;s interfaces and classes provide you with
+Dart&rsquo;s classes provide
 a set of reusable and extensible building blocks.
-An <em>interface</em> defines a basic set of methods and constants,
-sometimes by inheriting from other interfaces.
-A <em>class</em> can implement multiple interfaces,
-but it only inherits from a single superclass.
+A <em>class</em> defines methods and data
+and can provide method implementations.
+Every <em>object</em> is an instance of a class.
+An <em>abstract class</em> can't be instantiated,
+and it might not implement the methods it defines.
+</p>
+
+<p>
+Each class implicitly defines an interface.
+A class can implement multiple interfaces,
+but it only <em>extends</em>—inherits implementation from—a
+single superclass.
 </p>
 
 <p>
-The following example defines an interface,
-along with a class and subclass that implement it:
+The following example defines an abstract class,
+along with a class and subclass that implement its interface:
 </p>
 
 {% highlight dart %}
-interface Shape {
+abstract class Shape {
   num perimeter();
 }
 
 class Rectangle implements Shape {
   final num height, width; 
-  Rectangle(num this.height, num this.width);  // Compact constructor syntax.
-  num perimeter() => 2*height + 2*width;       // Short function syntax.
+  Rectangle(this.height, this.width);    // Compact constructor syntax.
+  num perimeter() => 2*height + 2*width; // Short function syntax.
 }
 
 class Square extends Rectangle {
@@ -205,19 +211,19 @@ a mixture of static and dynamic checking.
 When experimenting,
 the programmer can write untyped code for simple prototyping.
 As the application becomes larger and more stable,
-types can be added to aid debugging and impose structure where desired.
+types can be added to aid debugging and impose structure.
 </p>
 
 <p>
 For example, here is a sample of untyped code in Dart
-that creates a new Point class that has parameters
-<code>x</code> and <code>y</code>
-and two methods:
-<code>scale()</code> and <code>distance()</code>.
+that creates a new Point class that has two instance variables
+(<code>x</code> and <code>y</code>)
+and two methods
+(<code>scale()</code> and <code>distance()</code>).
 </p>
 
 {% highlight dart %}
-#import('dart:math');
+import 'dart:math';
 
 class Point {
   var x, y;
@@ -233,134 +239,99 @@ main() {
 {% endhighlight %}
 
 <p>
-Here is what this code looks like with types added
-that ensure that
-<code>x</code>, <code>y</code>, and <code>factor</code>
-are of type <code>num</code>,
-and that a <code>Point</code> contains two values
-of type <code>num</code>:
+Here is what this code looks like with a few types added

[sethladd, 2012/11/01 05:23:52]

A more powerful example:

(before)

recalculate(origin, offset, estimate) { .. }

(after)

num recalculate(Point origin, num offset,
                {bool estimate:false}) {

[Kathy Walrath, 2012/12/12 22:49:04]

Since we're showing complete code here... What would this be recalculating?

+to make the API of Point clearer.
+For example, this code specifies that
+<code>x</code> and <code>y</code>
+are of type <code>num</code>.
 </p>
 
 {% highlight dart %}
-#import('dart:math');
+import 'dart:math';
 
 class Point {
   num x, y;
-  Point(num this.x, num this.y);
+  Point(this.x, this.y);
   Point scale(num factor) => new Point(x*factor, y*factor);
   num distance() => sqrt(x*x + y*y);
 }
 
-void main() {
-  Point a = new Point(2,3).scale(10);
+main() {
+  var a = new Point(2,3).scale(10);
   print(a.distance());
 }
 {% endhighlight %}
 
 </section> <!-- optional types -->
-</section> <!-- code -->
-
-<section id="howtouse">
-<h2>How can I use Dart?</h2>
-
-<p>
-You can run Dart code in several ways:
-</p>
-
-<ul>
-  <li>
-    <p>
-    Compile Dart code to JavaScript that can run in any modern browser:<br />
-    Chrome, Safari 5+, and Firefox 4+ (more browser support coming shortly)
-    </p>
-  </li>
-  <li>
-    <p>
-    Execute Dart code directly in a VM on your computer
-    </p>
-  </li>
-  <li>
-    <p>
-    With a <a href="#mimetype">new MIME type</a>,
-    use Dart in a browser
-    without first compiling to JavaScript
-    </p>
-  </li>
-</ul>
-
-<section id="editor">
-<h3>Dart Editor</h3>
-
-<p>
-Dart Editor is a tool for
-creating, modifying, and launching Dart web apps.
-With one click, you can compile a Dart web app to JavaScript
-and launch the app in a browser.
-Taking advantage of Dart&rsquo;s structured nature,
-Dart Editor supports method name completion and refactoring.
-</p>
 
-<p>
-For information about downloading and using Dart Editor, see the
-<a href="/docs/editor/getting-started/">Dart Editor tutorial</a>.
-</p>
-</section>
-
-<section id="mimetype">
-<h3>New MIME type</h3>
+<section id="browser">
+<h3>Web apps</h3>
 
 <p>
-You will be able to link to a Dart program directly from an HTML page.
-Here is the proposed new MIME type,
-&ldquo;application/dart&rdquo;:
+With the new <code>application/dart</code> MIME type,
+Dart code can run directly in browsers that have a Dart VM,
+including Dartium and eventually Chrome.
+For other modern browsers,

[sethladd, 2012/11/01 05:23:52]

Please lead with this point (JavaScript compilation is critical factor)

[Kathy Walrath, 2012/12/12 22:49:04]

Done.

+Dart can be compiled to JavaScript.
+Here's an example of an HTML file that loads Dart code:
 </p>
 
 {% highlight html %}
 <!DOCTYPE html>
-
 <html>
   <head>
     <title>Simple Dart Web App</title>
   </head>
   <body>
-    <h1>Simple Dart Web App</h1>
-    <h2 id="status">dart is starting up...</h2>
-    <script type="application/dart" src="SimpleDartWebApp.dart"></script>
-    <script src="http://dart.googlecode.com/svn/branches/bleeding_edge/dart/client/dart.js"></script>
+    <h1>Simple Dart Web App</h1> 
+    <p id="changeme"></p>
+    <script type="application/dart" src="app.dart"></script>
+    <script src="https://dart.googlecode.com/svn/branches/bleeding_edge/dart/client/dart.js"></script>
   </body>
 </html>
 {% endhighlight %}
 
 <p>
-The dart.js file above will swap out the <code>application/dart</code>
-tag with a <code>text/javascript</code> tag if the browser does not
-have an embedded Dart virtual machine.
+  The first &lt;script> tag in this example
+  loads the code from app.dart.
+  If the browser has an embedded Dart VM,
+  then the browser loads Dart code.
+  Otherwise, the browser loads the code's JavaScript equivalent,
+  thanks to the dart.js script
+  in the second &lt;script> tag.
 </p>
 
 <p>
-The following is the Dart code for the page above:
+Here is the code in app.dart:
 </p>
 
 {% highlight dart %}
-#import('dart:html');
-
-class SimpleDartWebApp {
-  void run() {
-    write("Hello World!");
-  }
+import 'dart:html';
 
-  void write(String message) {
-    // the HTML library defines a global "document" variable
-    document.query('#status').innerHTML = message;
-  }
+main() {
+  query('#changeme')
+    ..text = "Click me!"
+    ..on.click.add(respond);
 }
 
-void main() {
-  new SimpleDartWebApp().run();
+respond(event) {
+  window.alert('Clicked!');

[sethladd, 2012/11/01 05:23:52]

Instead of window.alert, let's use:

query("#msg").text = "You clicked the button!"

and add an <output id="msg"></output> to the HTML

My main concern is not to show window.alert

[Kathy Walrath, 2012/12/12 22:49:04]

Done.

 }
 {% endhighlight %}
-</section> <!-- howtouse -->
-</section> <!-- mimetype -->
+
+<p>
+  The main() function's call to query()
+  returns the HTML element that has the ID "changeme".
+  The code then uses the cascade operator (<code>..</code>)
+  to perform multiple operations on that element.
+  The first operation initializes
+  the element's <code>text</code> property,
+  and the second adds an event handler to the element.
+</p>
+
+</section> <!-- browser -->
+
+</section> <!-- code -->
 
 
 <section id="tools">
@@ -374,10 +345,11 @@ Offerings include:
 </p>
 
 <ul>
-  <li>The Dart Editor</li>
-  <li>The dart2js compiler</li>
-  <li>The Dart VM</li>
-  <li>Dartium: Chromium with an embedded Dart VM</li>
+  <li><b>Dart Editor:</b> A Dart-savvy editor that supports creating, modifying, running, and debugging Dart apps</li>
+  <li><b>pub:</b> A package manager that features libraries published on <a href="http://pub.dartlang.org/">pub.dartlang.org</a></li>
+  <li><b>dart2js:</b> The Dart-to-JavaScript compiler</li>
+  <li><b>dart:</b> The Dart VM</li>
+  <li><b>Dartium:</b> Chromium with an embedded Dart VM</li>
 </ul>
 
 <p>
@@ -385,10 +357,11 @@ On the client side, you can deploy Dart apps in two ways.
 For browsers without an embedded Dart VM,
 you can compile the Dart code to JavaScript,
 using the dart2js compiler. This compiler generates ECMAScript5-compatible
-JavaScript from the Dart code. Dart code can run
-directly in browsers that have a Dart VM,
-including Dartium (a special build of Chromium)
-and eventually Chrome.
+JavaScript from the Dart code.
+This JavaScript code works in Chrome, Safari 5+, and Firefox 4+
+(with more to come).
+<b>{PENDING: is the browser list accurate?
+Do we want it here?}</b>
 </p>
 
 <p>
@@ -396,9 +369,28 @@ On the server side, the Dart code runs directly on the command line,
 for fast iteration and for cloud-based tasks.
 </p>
 
+<p>
 <img src="images/source-flow.png"
      alt="Dart source -> Dart Editor; Dart Editor -> either [Dart VM] or [JavaScript source -> Browser (JavaScript Engine)]"
      width="266" height="417" >
+</p>
+
+
+<section id="editor">
+
+<p>
+Running an app is easy—a single click—when you use Dart Editor.
+For example, clicking the Run button while you're editing a web app
+either runs it in Dartium
+or compiles it to JavaScript
+and launches it in the browser you've chosen.
+</p>
+
+<p>
+To get the tools and find more information, go to the
+<a href="/downloads.html">downloads page</a>.</p>
+</section>
+
 </section>
 
 
@@ -406,58 +398,59 @@ for fast iteration and for cloud-based tasks.
 <h2>Libraries</h2>
 
 <p>
-Dart provides the following libraries
-to support web and web server development:
+Dart provides several libraries

[sethladd, 2012/11/01 05:23:52]

we should also talk about unit tests, JSON, math, and more.

[Kathy Walrath, 2012/12/12 22:49:04]

Done.

+to support web and web server development,
+including:
 </p>
 
 <dl>
   <dt> <a href="http://api.dartlang.org/dart_core.html">Core Library</a> </dt>
-  <dd> Contains interfaces to support
-    common data structures and operations.
+  <dd> Common data structures and operations.
     </dd>
-  <dt> <a href="http://api.dartlang.org/html.html">HTML Library</a> </dt>
-  <dd> Contains interfaces to the HTML5 DOM,
+  <dt> <a href="http://api.dartlang.org/dart_html.html">HTML Library</a> </dt>
+  <dd> The interface to the HTML5 DOM,
     loosely based on the proposed HTML5 standard
     as specified by the W3C/WHATWG.
-    These interfaces will evolve in parallel with
+    This library is evolving in parallel with
     the HTML5 standards.</dd>
 
-  <dt> <a href="http://api.dartlang.org/io.html">I/O Library</a> </dt>
-  <dd> Contains interfaces to read and write files, open directories,
-    open network sockets, and run HTTP servers. This library is for
-    command-line Dart programs.
+  <dt> <a href="http://api.dartlang.org/dart_io.html">I/O Library</a> </dt>
+  <dd> Server-side support for I/O:
+    read and write files, open directories,
+    open network sockets, and run HTTP servers.
   </dd>
 
   <dt> <a href="http://api.dartlang.org/dart_isolate.html">Isolate Library</a> </dt>
   <dd>
-    Contains interfaces for spawning and communicating with isolates,
+    Support for spawning and communicating with isolates,
     the mechanism for concurrency and security in a Dart program.
   </dd>
 
-  <dt> <a href="http://api.dartlang.org/crypto.html">Crypto Library</a> </dt>
+  <dt> <a href="http://api.dartlang.org/dart_json.html">JSON Library</a> </dt>
   <dd>
-    Contains interfaces for creating one-way hashes (SHA1, MD5, SHA256)
-    and HMAC support.
+    Support for parsing and producing JSON-encoded text.
   </dd>
 
-  <dt> <a href="http://api.dartlang.org/json.html">JSON Library</a> </dt>
+  <dt> <a href="http://api.dartlang.org/dart_math.html">Math Library</a> </dt>
   <dd>
-    Contains the ability to parse and produce JSON-encoded text.
-  </dd>
-
-  <dt> <a href="http://api.dartlang.org/unittest.html">Unit Test Library</a> </dt>
-  <dd>
-    Contains functions and classes for writing unit tests in Dart.
+    Common functionality such as sine and cosine,
+    maximum and minimum,
+    and constants such as <em>pi</em> and <em>e</em>.
   </dd>
 </dl>
 
 <p>
   See the
-  <a href="/docs/library-tour/">library tour</a>
+  <a href="/docs/dart-up-and-running/ch03.html">library tour</a>
   and the
-  <a href="http://api.dartlang.org">API reference</a> docs for
+  <a href="http://api.dartlang.org">API reference</a> for
   details on all the bundled
   Dart libraries.
+  Also see <a href="http://pub.dartlang.org">pub.dartlang.org</a>
+  for additional libraries and tools such as
+  <a href="http://pub.dartlang.org/packages/js">JavaScript Interop</a>
+  and
+  <a href="http://pub.dartlang.org/packages/web_components">Dart Web Components</a>.
 </p>
 
 </section> <!-- libraries -->
@@ -469,9 +462,6 @@ to support web and web server development:
 <p>
 This project is open source
 and will evolve with feedback and participation from the community.
-We have released the draft language specification at an early stage
-to gather responses from the developers
-who will be using this new language and infrastructure for web programming.
 Here are some additional links for learning more about Dart
 and providing your feedback:
 </p>
@@ -479,9 +469,10 @@ and providing your feedback:
 <ul>
   <li>
     Other pages in the Dart website,
-    such as the <a href="/docs/language-tour/">language tour</a>,
-    <a href="/docs/library-tour/">library tour</a>,
-    tutorials, and <a href="/docs/spec/">language specification</a>.
+    such as the <a href="/docs/dart-up-and-running/ch02.html">language tour</a>,
+    <a href="/docs/dart-up-and-running/ch03.html">library tour</a>,
+    <a href="/docs/tutorials/">tutorials</a>,
+    and <a href="/docs/dart-up-and-running/ch05.html">Dart Chat walkthrough</a>
   </li>
   <li>
     <a href="https://code.google.com/p/dart/">Dart project</a>
@@ -493,6 +484,4 @@ and providing your feedback:
     <a href="https://plus.google.com/109866369054280216564/">+Dart</a> on Google+ </li>
 </ul>
 
-</section> <!-- involved -->
-
-
+</section> <!-- involved -->