Link to stable-errors site from pub-build messages on the command line.

pkg/polymer/tool/create_message_details_page.dart

Index: pkg/polymer/tool/create_message_details_page.dart
diff --git a/pkg/polymer/tool/create_message_details_page.dart b/pkg/polymer/tool/create_message_details_page.dart
index 1724f725fbe38fb0d16a947ca77ba1ab3fe7dc23..c24c06b22b261c5d821d5d904587386787be33ce 100644
--- a/pkg/polymer/tool/create_message_details_page.dart
+++ b/pkg/polymer/tool/create_message_details_page.dart
@@ -23,8 +23,10 @@ import 'package:observe/src/messages.dart' as m2; // used via mirrors
 import 'package:polymer/src/build/messages.dart' as m3; // used via mirrors
 import 'package:markdown/markdown.dart';
 import 'package:path/path.dart' as path;
+import 'package:args/args.dart';
 
-main() {
+main(args) {
+  var options = _parseOptions(args);
   var seen = {};
   var templates = [];
   _getMessagesFrom(#polymer.src.build.messages, seen, templates);
@@ -33,20 +35,28 @@ main() {
 
   templates.sort((a, b) => a.id.compareTo(b.id));
   var sb = new StringBuffer();
-  sb.write(_HEADER);
+  bool forSite = options['site'];
+  var out = path.join(path.current, options['out']);
+  var ext = forSite ? '.markdown' : '.html';
+  if (!out.endsWith(ext)) {
+    print('error: expected to have a $ext extension.');
+    exit(1);
+  }
+
+  sb.write(forSite ? _SITE_HEADER : _LOCAL_HEADER);
 
   var lastPackage = '';
   for (var t in templates) {
     if (lastPackage != t.id.package) {
       lastPackage = t.id.package;
       sb.write(markdownToHtml(
-            '#Messages from package `$lastPackage`\n\n----\n'));
+            '## Messages from package `$lastPackage`\n\n----\n'));
     }
-    sb.write(_htmlFor(t));
+    sb.write(_htmlFor(t, forSite));
   }
-  sb.write(_FOOTER);
-  new File('lib/src/build/generated/messages.html')
-      .writeAsStringSync(sb.toString());
+  sb.write(forSite ? '' : _LOCAL_FOOTER);
+  new File(out).writeAsStringSync(sb.toString());
+  print('updated: ${options["out"]}');
 }
 
 final _mirrors = currentMirrorSystem();
@@ -68,19 +78,73 @@ _getMessagesFrom(Symbol libName, Map seen, List templates) {
   });
 }
 
-_htmlFor(MessageTemplate template) {
+_htmlFor(MessageTemplate template, bool forSite) {
   var details = template.details == null
       ? 'No details available' : template.details;
   var id = template.id;
-  var hashTag = 'msg_${id.package}_${id.id}';
+  var hashTag = '${id.package}_${id.id}';
   var markdown = 
-      '## ${template.description} [#${id.id}](#$hashTag)\n\n$details\n\n----\n';
-  var html = markdownToHtml(markdown);
-  // We add the anchor inside the <h2> title, otherwise the link doesn't work.
-  return '\n\n${html.replaceFirst("<h2>", "<h2 id=\"$hashTag\">")}';
+      '### ${template.description} [#${id.id}](#$hashTag)\n\n$details\n\n----\n';
+  // We add the anchor inside the <h3> title, otherwise the link doesn't work.
+  var clazz = forSite ? 'class="has-permalink"' : '';
+  var html = markdownToHtml(markdown)
+      .replaceFirst('<h3>', '<h3 id="$hashTag" $clazz>');
+  return '\n\n$html';
+}
+
+_parseOptions(args) {
+  var parser = new ArgParser(allowTrailingOptions: true)
+      ..addOption('out', abbr: 'o',
+          defaultsTo: 'lib/src/build/generated/messages.html',
+          help: 'the output file path')
+      ..addFlag('site', abbr: 's', negatable: false,
+          help: 'generate contents for the dartlang.org site')
+      ..addFlag('help', abbr: 'h', negatable: false);
+
+  var options = parser.parse(args);
+  if (options['help']) {
+    var command = Platform.script.path;
+    var relPath = path.relative(command, from: path.current);
+    if (!relPath.startsWith('../')) command = relPath;
+    print('usage: dart $command [-o path_to_output_file] [-s]');
+    print(parser.getUsage());
+    exit(0);
+  }
+  return options;
+}
+
+const _SITE_HEADER = '''
+---
+# WARNING - DO NOT EDIT

[Kathy Walrath, 2014/09/05 14:59:01]

Let's make this a little more formal and closer to the
header used by the book's generated files (e.g.
https://github.com/dart-lang/www.dartlang.org/blob/master/src/site/docs/dart-...).

How about:

# WARNING: GENERATED FILE. DO NOT EDIT.
#
#   This file was generated automatically from the polymer package.
#   To regenerate this file, from the top directory of the polymer package run:
#
#     dart tool/create_message_details_page.dart -s -o path_to_this_file

[Siggi Cherem (dart-lang), 2014/09/05 16:13:15]

Done.

+#   this file was generated automatically from the polymer package
+#   to regenerate go to the polymer package, then run:
+#      dart tool/create_message_details_page.dart -s -o path-to-this-file
+layout: default
+title: "Error messages"
+subsite: "Polymer.dart"
+description: "Details about error messages from polymer and related packages."
+---
+
+# {{ page.title }}
+
+<style>
+h3 > a {
+  display: none;
 }
 
-const _HEADER = '''
+h3:hover > a {
+  display: inline;
+}
+
+</style>
+
+
+This page contains a list of error messages produced during `pub build` and `pub
+serve` by transformers in polymer and its related packages. You can find here
+additional details that can often help understand or debug error messages.

[Kathy Walrath, 2014/09/05 14:59:01]

understand -> you understand

[debugging error messages sounds strange. what do you really mean?]

[Siggi Cherem (dart-lang), 2014/09/05 16:13:15]

how about `figure out how to fix the underlying problem`

+''';
+
+const _LOCAL_HEADER = '''
 <!doctype html>
 <!--
   This file is autogenerated with polymer/tool/create_message_details_page.dart
@@ -118,7 +182,7 @@ body {
   font-family: Roboto, sans-serif;
 }
 
-h1 {
+h2 {
   font-family: Montserrat, sans-serif;
   box-sizing: border-box;
   color: rgb(72, 72, 72);
@@ -128,7 +192,7 @@ h1 {
   font-weight: normal;
 }
 
-h2 {
+h3 {
   font-family: Montserrat, sans-serif;
   box-sizing: border-box;
   color: rgb(72, 72, 72);
@@ -142,7 +206,6 @@ pre {
   display: block;
   padding: 9.5px;
   margin: 0 0 10px;
-  line-height: 1.42857143;
   color: #333;
   word-break: break-all;
   word-wrap: break-word;
@@ -162,27 +225,29 @@ code {
    background-color: #f9f2f4;
 }
 
-pre > code {
+pre code {
    white-space: inherit;
+   color: inherit;
+   background-color: inherit;
 }
 
 a {
   color: rgb(42, 100, 150);
 }
 
-h2 > a {
+h3 > a {
   display: none;
   font-size: 0.8em;
 }
 
-h2:hover > a {
+h3:hover > a {
   display: inline;
 }
 </style>
 <body>
 ''';
 
-const _FOOTER = '''
+const _LOCAL_FOOTER = '''
 </body>
 </html>
 ''';