update protoc README

README.md

 Protoc compiler Dart plugin
 ===========================
 
-This application provides a plugin for protoc compiler which
-generates pure Dart library to deal with protobufs.
+This repository provides a plugin for the [protoc compiler](
+https://developers.google.com/protocol-buffers/docs/cpptutorial#compiling-your-protocol-buffers).
+It generates Dart files for working with data in protocol buffers format. At
+this time we only support [proto2](
+https://developers.google.com/protocol-buffers/docs/proto), but proto3 may work
+in simple cases due to backwards compatibility.
 
-Please, do not forget that generated libraries depend on runtime
-support library which can be found [here](https://github.com/dart-lang/dart-protobuf).
+Requirements
+------------
+
+To compile a .proto file, you must use the 'protoc' command which is
+[installed separately](
+https://developers.google.com/protocol-buffers/docs/downloads).
+Protobuf 2.6.1 or above is recommended. Many features may still work as far back
+as Protobuf 2.5.0 but we are no longer testing this.
+
+The generated files are pure Dart code that run in either in the Dart VM or in a
+browser (using dart2js). They depend the [protobuf Dart package](
+https://pub.dartlang.org/packages/protobuf). A Dart project that includes
+generated files should add "protobuf" to its pubspec.yaml file.
 
 How to build and use
 --------------------
 
 *Note:* currently the workflow is POSIX-oriented.
 
 To build standalone `protoc` plugin:
 - run `pub install` to install all dependecies
 - run `make build-plugin`. That will create a file `out/protoc-gen-dart` which
   is a plugin
@@ skipping 14 matching lines @@
 Dart plugin, these options are passed together with the `--dart_out`
 option. The individial options are separated using comma, and the
 final output directive is separated from the options using colon. Pass
 options `<option 1>` and `<option 2>` like this:
 
     --dart_out="<option 1>,<option 2>:."
 
 Using protocol buffer libraries to build new libraries
 ------------------------------------------------------
 
-The protocol buffer compiler produces one library for each `.proto` file
+The protocol buffer compiler produces several files for each `.proto` file
 it compiles. In some cases this is not exactly what is needed, e.g one
 would like to create new libraries which exposes the objects in these
 libraries or create new librares combining object definitions from
 several `.proto` libraries into one.
 
 The best way to aproach this is to create the new libraries needed and
 re-export the relevant protocol buffer classes.
 
 Say we have the file `m1.proto` with the following content
 
@@ skipping 19 matching lines @@
 
     export "m1.pb.dart" show M1;
     export "m2.pb.dart" show M2;
 
     M1 createM1() => new M1();
     M2 createM2() => new M2();
 
 Hacking
 -------
 
-You need to have `protoc` installed.
+Here are some ways to get protoc:
 
-* Linux Aptitude: `apt-get install protobuf-compiler`
+* Linux: `apt-get install protobuf-compiler`
 * Mac [homebrew](http://brew.sh/): `brew install protobuf`
 
+If the version installed this way doesn't work, an alternative is to
+[compile protoc from source](
+https://developers.google.com/protocol-buffers/docs/downloads).
+
 Remember to run the tests. That is as easy as `make run-tests`.
 
 The default way of running the Dart protoc plugin is through the
 generated `out/protoc-gen-dart` script. However when run this way the
 Dart code is assembled into one large Dart file using dart2dart. To
 run with the actual source in the repository create an executable
 script called `protoc-gen-dart` with the following content:
 
     #! /bin/bash
     dart bin/protoc_plugin.dart
@@ skipping 11 matching lines @@
     $ protoc --plugin=protoc-gen-dart=./plugin --dart_out=. test.proto
 
 Useful references
 -----------------
 
 * [Main Dart site](http://www.dartlang.org)
 * [Main protobuf site](https://code.google.com/p/protobuf)
 * [Protobuf runtime support project](https://github.com/dart-lang/dart-protobuf)
 * [DartEditor download](http://www.dartlang.org)
 * [Pub documentation](http://pub.dartlang.org/doc)