Some additions to documentation

git-svn-id: https://svn.kapsi.fi/jpa/nanopb@1003 e3a754e5-d11d-0410-8d38-ebb782a927b9

docs/Makefile

@@ -1,4 +1,8 @@
-all: index.html concepts.html reference.html
+all: index.html concepts.html reference.html \
+	generator_flow.png
+
+%.png: %.svg
+	rsvg $< $@
 
 %.html: %.rst
-	rst2html --stylesheet=lsr.css --link-stylesheet $< $@
+	rst2html --stylesheet=lsr.css --link-stylesheet $< $@

docs/index.rst

@@ -13,9 +13,11 @@ Overall structure
 =================
 
 For the runtime program, you always need *pb.h* for type declarations.
-Depending on whether you want to encode, decode or both, you also need *pb_encode.h/c* or *pb_decode.h/c*.
+Depending on whether you want to encode, decode, or both, you also need *pb_encode.h/c* or *pb_decode.h/c*.
 
-The high-level encoding and decoding functions take an array of *pb_field_t* structures, which describes the fields of a message structure. Usually you want these autogenerated from a *.proto* file. The tool string *nanopb_generator.py* accomplishes this.
+The high-level encoding and decoding functions take an array of *pb_field_t* structures, which describes the fields of a message structure. Usually you want these autogenerated from a *.proto* file. The tool script *nanopb_generator.py* accomplishes this.
+
+.. image:: generator_flow.png
 
 So a typical project might include these files:
 
@@ -25,8 +27,8 @@ So a typical project might include these files:
     - pb_encode.h and pb_encode.c (needed for encoding messages)
 2) Protocol description (you can have many):
     - person.proto (just an example)
-    - person.c (autogenerated, contains initializers for const arrays)
-    - person.h (autogenerated, contains type declarations)
+    - person.pb.c (autogenerated, contains initializers for const arrays)
+    - person.pb.h (autogenerated, contains type declarations)
 
 Features and limitations
 ========================
@@ -37,7 +39,7 @@ Features and limitations
 #) Small code size (2–10 kB depending on processor)
 #) Small ram usage (typically 200 bytes)
 #) Allows specifying maximum size for strings and arrays, so that they can be allocated statically.
-#) No malloc needed: everything is stored on the stack.
+#) No malloc needed: everything can be allocated statically or on the stack.
 #) You can use either encoder or decoder alone to cut the code size in half.
 
 **Limitations**
@@ -48,6 +50,7 @@ Features and limitations
 #) The deprecated Protocol Buffers feature called "groups" is not supported.
 #) Fields in the generated structs are ordered by the tag number, instead of the natural ordering in .proto file.
 #) Unknown fields are not preserved when decoding and re-encoding a message.
+#) Reflection (runtime introspection) is not supported. E.g. you can't request a field by giving its name in a string.
 #) Numeric arrays are always encoded as packed, even if not marked as packed in .proto. This causes incompatibility with decoders that do not support packed format.
 #) Cyclic references between messages are not supported. They could be supported in callback-mode if there was an option in the generator to set the mode.