Update messages in code transformers now that we have the article about imports.

pkg/code_transformers/lib/src/messages.dart

 // Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /// Contains all warning messages produced by the code_transformers package.
 library code_transformers.src.messages;
 
 import 'package:code_transformers/messages/messages.dart';
 
 const NO_ABSOLUTE_PATHS = const MessageTemplate(
     const MessageId('code_transformers', 1),
     'absolute paths not allowed: "%-url-%"',
     'Absolute paths not allowed',
     '''
 The transformers processing your code were trying to resolve a URL and identify
 a file that they correspond to. Currently only relative paths can be resolved.
 ''');
 
 const INVALID_URL_TO_OTHER_PACKAGE = const MessageTemplate(
     const MessageId('code_transformers', 2),
     'Invalid URL to reach to another package: %-url-%. Path '
     'reaching to other packages must first reach up all the '
     'way to the %-prefix-% directory. For example, try changing the URL '
     'to: %-fixedUrl-%',
     'Invalid URL to reach another package',
     '''
 To reach an asset that belongs to another package, use `package:` URLs in
-Dart code, but in any other language (like HTML or CSS) use relative URLs.
+Dart code, but in any other language (like HTML or CSS) use relative URLs that
+first go all the way to the `packages/` directory.
 
-These are the rules you must follow to write URLs that refer to files in other
-packages:
-
-  * If the file containing the relative URL is an entrypoint under `web`, use
-    `packages/package_name/path_to_file`
-
-  * If the file containing the URL is under `web`, but in a different directory
-    than your entrypoint, walk out to the same level as the entrypoint first,
-    then enter the `packages` directory.
-
-    **Note**: If two entrypoints include the file under `web` containing the
-    URL, either both entrypoints have to live in the same directory, or you need
-    to move the file to the `lib` directory.
-
-  * If the file containing the URL lives under `lib`, walk up as many levels as
-    directories you have + 1. This is because code in `lib/a/b` is loaded from
-    `packages/package_name/a/b`.
-
-The rules are easier to follow if you know how the code is laid out for
-Dartium before you build, and how it is laid out after you build it with `pub
-build`. Consider the following example:
-
-   package a
-      lib/
-        |- a1.html
-
-      web/
-        |- a2.html
-
-   package b
-      lib/
-        |- b1.html
-        |- b2/
-            |- b3.html
-
-   package c
-      lib/
-        |- c3.html
-
-      web/
-        |- index.html
-        |- index.dart
-        |- c1/
-            |- c2.html
-
-If your app is package `c`, then `pub get` generates a packages directory under
-the web directory, like this:
-
-      web/
-        |- index.html
-        |- index.dart
-        |- c1/
-        |   |- c2.html
-        |- packages/
-            |- a/
-            |   |- a1.html
-            |- b/
-            |   |- b1.html
-            |   |- b2/
-            |       |- b3.html
-            |- c/
-                |- c3.html
-
-Note that no `lib` directory is under the `packages` directory.
-When you launch `web/index.html` in Dartium, Dartium loads `package:` imports from
-`web/packages/`.
-
-If you need to refer to any file in other packages from `index.html`, you can
-simply do `packages/package_name/path_to_file`. For example
-`packages/b/b2/b3.html`. From `index.html` you can also refer to files under the
-web directory of the same package using a simple relative URL, like
-`c1/c2.html`.
-
-However, if you want to load `a1.html` from `c2.html`, you need to reach out to
-the packages directory that lives next to your entrypoint and then load the file
-from there, for example `../packages/a/a1.html`. Because pub generates symlinks
-to the packages directory also under c1, you may be tempted to write
-`packages/a/a1.html`, but that is incorrect - it would yield a canonicalization
-error (see more below).
-
-If you want to load a file from the lib directory of your own package, you
-should also use a package URL. For example, `packages/c/c3.html` and not
-`../lib/c3.html`. This will allow you to write code in `lib` in a way that it
-can be used within and outside your package without making any changes to it.
-
-Because any time you reach inside a `lib/` directory you do so using a
-`packages/` URL, the rules for reaching into other files in other packages are
-always consistent: go up to exit the `packages` directory and go back inside to
-the file you are looking for.  For example, to reach `a1.html` from `b3.html`
-you need to write `../../../packages/a/a1.html`.
-
-The motivation behind all these rules is that URLs need to work under many
-scenarios at once:
-
-  * They need to work in Dartium without any code transformation: resolving the
-    path in the context of a simple HTTP server, or using `file:///` URLs,
-    should yield a valid path to assets. The `packages` directory is safe to use
-    because pub already creates it next to entrypoints of your application.
-
-  * They need to be canonical. To take advantage of caching, multiple URLs
-    reaching the same asset should resolve to the same absolute URL.
-    
-    Also, in projects that use HTML imports (like polymer) tools support that
-    you reach a library with either Dart imports or HTML imports, and correctly
-    resolve them to be the same library. The rules are designed to allow tools
-    to support this.
-
-    For example, consider you have an import might like:
-
-        <link rel=import href=packages/a/a.html>
-
-    where a.html has `<script type="application/dart" src="a.dart">`. If your
-    Dart entrypoint also loads `"package:a/a.dart"`,  then a tool need to make
-    sure that both versions of `a.dart` are loaded from the same URL. Otherwise,
-    you may see errors at runtime like: `A is not a subtype of A`, which can be
-    extremely confusing.
-
-    When you follow the rules above, our tools can detect the pattern in the
-    HTML-import URL containing `packages/` and canonicalize the import
-    by converting `packages/a/a.dart` into `package:a/a.dart` under the hood.
-
-  * They need to continue to be valid after applications are built.
-    Technically this could be done automatically with pub transformers, but to
-    make sure that code works also in Dartium with a simple HTTP Server,
-    existing transformers do not fix URLs, they just detect inconsistencies and
-    produce an error message like this one, instead.
+The rules for correctly writing these imports are subtle and have a lot of
+special cases. Please review
+<https://www.dartlang.org/polymer/app-directories.html> to learn
+more.
 ''');
 
 const INVALID_PREFIX_PATH = const MessageTemplate(
     const MessageId('code_transformers', 3),
     'incomplete %-prefix-%/ path. It should have at least 3 '
     'segments %-prefix-%/name/path_from_name\'s_%-folder-%_dir',
     'Incomplete URL to asset in another package',
     '''
 URLs that refer to assets in other packages need to explicitly mention the
 `packages/` directory. In the future this requirement might be removed, but for
 now you must use a canonical URL form for it.
 
 For example, if `packages/a/a.html` needs to import `packages/b/b.html`,
 you might expect a.html to import `../b/b.html`. Instead, it must import
 `../../packages/b/b.html`.
-See [issue 15797](http://dartbug.com/15797).
+
+See [issue 15797](http://dartbug.com/15797) and
+<https://www.dartlang.org/polymer/app-directories.html> to learn more.
 ''');