Document the new stuff:

- The "documentation" field in the pubspec.
- SDK constraints.
- pub lish --force
- pub lish --dry-run
- Path dependencies.

app/doc/glossary.markdown

@@ -84,6 +84,13 @@ The lockfile is generated automatically for you by pub when you run
 package is an application package, you will typically check this into source
 control. For library packages, you usually won't.
 
+### SDK Constraint
+
+The declared versions of the Dart SDK itself that a package declares that it
+supports. It is specified using normal [version constraint](#version-constraint)
+syntax, but in a special "environment" section
+[in the pubspec](pubspec.html#sdk-constraints).
+
 ### Source
 
 A kind of place that pub can download and install packages from. A source isn't

app/doc/pub-lish.markdown

@@ -69,3 +69,21 @@ issue][delete-request] and the Pub authors will take down your package. You'll
 need to use a different version when you re-upload it, though.
 
 [delete-request]: http://code.google.com/p/dart/issues/entry?summary=Request%20to%20delete%20package%20from%20pub&status=Triaged&labels=Type-Task,Priority-Medium,Area-Pub,Pub-DeleteRequest
+
+## Options
+
+### `--dry-run` or `-n`
+
+With this, pub goes through the validation process but does not actually upload
+the package. This is useful if you want to see if your package meets all of the
+publishing requirements before you're ready to actually go public.
+
+### `--force` or `-f`
+
+With this, pub does not ask for confirmation before publishing. Normally, it
+shows you the package contents and asks for you to confirm the upload.
+
+If there are any errors in your package, it is not uploaded and this exits with
+an error. If there are warnings, it *will* be uploaded. If you want to ensure
+your package has no warnings before uploading, either don't use `--force`, or
+use `--dry-run` first.

app/doc/pubspec.markdown

@@ -7,12 +7,15 @@ title: "Pubspec Format"
 1. [Description](#description)
 1. [Author/Authors](#authorauthors)
 1. [Homepage](#homepage)
+1. [Documentation](#documentation)
 1. [Dependencies](#dependencies)
 1. [Dependency sources](#dependency-sources)
     1. [Hosted packages](#hosted-packages)
-    1. [SDK packages](#sdk-packages)
     1. [Git packages](#git-packages)
+    1. [Path packages](#path-packages)
+    1. [SDK packages](#sdk-packages)
 1. [Version constraints](#version-constraints)
+1. [SDK constraints](#sdk-constraints)
 {:.toc}
 
 Every pub package needs some metadata so it can specify its
@@ -34,6 +37,8 @@ At the top level are a series of fields. The currently supported ones are:
   <dd>Optional.</dd>
   <dt>Homepage</dt>
   <dd>Optional.</dd>
+  <dt>Documentation</dt>
+  <dd>Optional.</dd>
   <dt>Dependencies</dt>
   <dd>Can be omitted if your package has no dependencies.</dd>
 </dl>
@@ -50,6 +55,7 @@ description: >
   functionality you've been looking for.
 author: Nathan Weizenbaum <nweiz@google.com>
 homepage: http://newtify.dartlang.org
+documentation: http://docs.newtify.com
 dependencies:
   efts: '>=2.0.4 <3.0.0'
   transmogrify: '>=0.4.0'
@@ -132,6 +138,13 @@ can always use the URL where you host the source code:
 [GitHub](http://github.com), [code.google.com](http://code.google.com/),
 whatever.
 
+## Documentation
+
+Some packages may have a separate site that hosts documentation separate from
+the main homepage. If your package has that, you can also add a documentation
+field with that URL. If provided, a link to it will be shown on your package's
+page.
+
 ## Dependencies
 
 Finally, the pubspec's *raison d'être*:
@@ -230,20 +243,6 @@ dependencies:
     version: '>=0.4.0 <1.0.0'
 {% endhighlight %}
 
-### SDK packages
-
-Some packages are a built-in part of the Dart SDK. These are the "batteries
-included" packages that you get for free when you install Dart.
-
-{% highlight yaml %}
-dependencies:
-  i18n:
-    sdk: i18n
-{% endhighlight %}
-
-The `sdk` here says this package should be found in the installed Dart SDK, and
-"i18n" is the name of the package to use.
-
 ### Git packages
 
 Sometimes you live on the bleeding edge and you need to use stuff that hasn't
@@ -279,6 +278,60 @@ The ref can be anything that Git allows to [identify a commit][commit].
 
 [commit]: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#naming-commits
 
+### Path packages
+
+Sometimes you find yourself working on multiple related packages at the same
+time. Maybe you are hacking on a framework while building an app that uses it.
+In those cases, during development you really want to depend on the "live" local
+version of that package. That way changes in one package are instantly picked up
+by the one that depends on it.
+
+To handle that, pub supports *path dependencies*. These let you depend on a
+package on your local file system.
+
+{% highlight yaml %}
+dependencies:
+  transmogrify:
+    path: /Users/me/transmogrify
+{% endhighlight %}
+
+This says the root directory for `transmogrify` is at `/Users/me/transmogrify`.
+When you use this, pub will generate a symlink directly to the referenced
+directory. This means any changes you make to the dependent package will be seen
+immediately. You don't need to run pub every time you change the dependent
+package.
+
+Path dependencies are very useful for local development, but do not play nice
+with sharing code with the outside world. It's not like everyone can get to
+your file system, after all. Because of this, you cannot upload a package to
+[pub.dartlang.org][pubsite] if it has any path dependencies in its pubspec.
+
+Instead, the typical workflow is:
+
+1. Edit your pubspec locally to use a path dependency.
+2. Hack on the main package and the package it depends on.
+3. Once they're both in a happy place, publish the dependent package.
+4. Then change your pubspec to point to the now hosted version of its dependent.
+5. Now you can publish your main package too if you want.
+
+<aside class="alert alert-warning">
+Currently only absolute paths can be used for path dependencies.
+</aside>
+
+### SDK packages
+
+Some packages are a built-in part of the Dart SDK. These are the "batteries
+included" packages that you get for free when you install Dart.
+
+{% highlight yaml %}
+dependencies:
+  i18n:
+    sdk: i18n
+{% endhighlight %}
+
+The `sdk` here says this package should be found in the installed Dart SDK, and
+"i18n" is the name of the package to use.
+
 ## Version constraints
 
 If your package is an application, you don't usually need to specify [version
@@ -353,5 +406,26 @@ constraint starts with that.
 
 </aside>
 
+## SDK constraints
+
+A package can indicate which versions of its dependencies it supports, but there
+is also another implicit dependency all packages have: the Dart SDK itself.
+Since the Dart platform evolves over time, a package may only work with certain
+versions of it.
+
+A package can specify that using an *SDK constraint*. This goes inside a
+separate top-level "environment" field in the pubspec. For example, this
+constraint says that this package works with any Dart SDK from 0.3.4 or later:
+
+{% highlight yaml %}
+environment:
+  sdk: ">=0.3.4"
+{% endhighlight %}
+
+When you install a package that doesn't work with your installed Dart SDK, pub
+will show you an error message and ask you to resolve it. You can usually fix
+this by upgrading to the latest Dart SDK, or locking to an older version of that
+dependency that does work with your SDK.
+
 [pubsite]: http://pub.dartlang.org
 [semantic versioning]: http://semver.org/

app/static/style.css

@@ -4984,6 +4984,14 @@ body {
   padding-top: 60px;
 }
 
+code {
+  white-space: nowrap;
+}
+
+pre code {
+  white-space: inherit;
+}
+
 a.permalink {
   margin-left: 0.5em;
   display: none;

app/views/doc/glossary.html

@@ -80,6 +80,13 @@ <h3 id="lockfile">Lockfile</h3>
 package is an application package, you will typically check this into source
 control. For library packages, you usually won&rsquo;t.</p>
 
+<h3 id="sdk-constraint">SDK Constraint</h3>
+
+<p>The declared versions of the Dart SDK itself that a package declares that it
+supports. It is specified using normal <a href="#version-constraint">version constraint</a>
+syntax, but in a special &ldquo;environment&rdquo; section
+<a href="pubspec.html#sdk-constraints">in the pubspec</a>.</p>
+
 <h3 id="source">Source</h3>
 
 <p>A kind of place that pub can download and install packages from. A source isn&rsquo;t

app/views/doc/package-layout.html

@@ -113,7 +113,7 @@ <h2 id="readme">README</h2>
 package. This is the perfect place to introduce people to your code.</p>
 
 <p>If your README ends in <code>.md</code>, <code>.markdown</code>, or <code>.mdown</code>, it will be parsed as
-<a href="http://daringfireball.net/projects/markdown/">Markdown</a> so you can make it as fancy nicely formatted as you like.</p>
+<a href="http://daringfireball.net/projects/markdown/">Markdown</a> so you can make it as fancy as you like.</p>
 
 <h2 id="public-libraries">Public libraries</h2>
 

app/views/doc/pub-lish.html

@@ -73,3 +73,20 @@ <h2 id="deleting-a-published-package">Deleting a published package</h2>
 issue</a> and the Pub authors will take down your package. You&rsquo;ll
 need to use a different version when you re-upload it, though.</p>
 
+<h2 id="options">Options</h2>
+
+<h3 id="dry-run-or--n"><code>--dry-run</code> or <code>-n</code></h3>
+
+<p>With this, pub goes through the validation process but does not actually upload
+the package. This is useful if you want to see if your package meets all of the
+publishing requirements before you&rsquo;re ready to actually go public.</p>
+
+<h3 id="force-or--f"><code>--force</code> or <code>-f</code></h3>
+
+<p>With this, pub does not ask for confirmation before publishing. Normally, it
+shows you the package contents and asks for you to confirm the upload.</p>
+
+<p>If there are any errors in your package, it is not uploaded and this exits with
+an error. If there are warnings, it <em>will</em> be uploaded. If you want to ensure
+your package has no warnings before uploading, either don&rsquo;t use <code>--force</code>, or
+use <code>--dry-run</code> first.</p>