README updates

2 files changed, 58 insertions, 9 deletions

diff --git a/README.txt b/README.txt
index 2a12b4f5..c6085d28 100644
--- a/README.txt
+++ b/README.txt
@@ -1,11 +1,61 @@
-Nanopb is a small code-size Protocol Buffers implementation.
+Nanopb is a small code-size Protocol Buffers implementation in ansi C. It is
+especially suitable for use in microcontrollers, but fits any memory
+restricted system.
 
 Homepage: http://kapsi.fi/~jpa/nanopb/
 
-To compile the library, you'll need these libraries:
-protobuf-compiler python-protobuf libprotobuf-dev
 
-The only runtime dependencies are memset() and memcpy().
 
-To run the tests, run make under the tests folder.
-If it completes without error, everything is fine.
+
+Using the nanopb library
+========================
+To use the nanopb library, you need to do two things:
+
+1) Compile your .proto files for nanopb, using protoc.
+2) Include pb_encode.c and pb_decode.c in your project.
+
+The easiest way to get started is to study the project in "examples/simple".
+It contains a Makefile, which should work directly under most Linux systems.
+However, for any other kind of build system, see the manual steps in
+README.txt in that folder.
+
+
+
+Using the Protocol Buffers compiler (protoc)
+============================================
+The nanopb generator is implemented as a plugin for the Google's own protoc
+compiler. This has the advantage that there is no need to reimplement the
+basic parsing of .proto files. However, it does mean that you need the
+Google's protobuf library in order to run the generator.
+
+If you have downloaded a binary package for nanopb (either Windows or Linux
+version), the 'protoc' binary is included in the 'generator-bin' folder. In
+this case, you are ready to go. Simply run this command:
+
+    generator-bin/protoc --nanopb_out=. myprotocol.proto
+
+However, if you are using a git checkout or a plain source distribution, you
+need to provide your own version of protoc and the Google's protobuf library.
+On Linux, the necessary packages are protobuf-compiler and python-protobuf.
+On Windows, you can either build Google's protobuf library from source or use
+one of the binary distributions of it. In either case, if you use a separate
+protoc, you need to manually give the path to nanopb generator:
+
+    protoc --plugin=protoc-gen-nanopb=nanopb/generator/protoc-gen-nanopb ...
+
+
+
+Running the tests
+=================
+If you want to perform further development of the nanopb core, or to verify
+its functionality using your compiler and platform, you'll want to run the
+test suite. The build rules for the test suite are implemented using Scons,
+so you need to have that installed. To run the tests:
+
+    cd tests
+    scons
+
+This will show the progress of various test cases. If the output does not
+end in an error, the test cases were successful.
+
+
diff --git a/examples/simple/README.txt b/examples/simple/README.txt
index d18c4183..ee77bfc7 100644
--- a/examples/simple/README.txt
+++ b/examples/simple/README.txt
@@ -18,10 +18,9 @@ On Linux, simply type "make" to build the example. After that, you can
 run it with the command: ./simple
 
 On other platforms, you first have to compile the protocol definition using
-the following two commands::
+the following command::
 
-  protoc -osimple.pb simple.proto
-  python nanopb_generator.py simple.pb
+  ../../generator-bin/protoc --nanopb_out=. simple.proto
 
 After that, add the following four files to your project and compile: