[docs / examples] Update docs and examples

examples/tutorial/README.md

@@ -1,6 +1,12 @@
 masque Tutorial
 ===============
 
+These examples are meant to be read roughly in order.
+
+- Start with `basic_shapes.py` for the core `Pattern` / GDS concepts.
+- Then read `devices.py` and `library.py` for hierarchical composition and libraries.
+- Read the `pather*` tutorials separately when you want routing helpers.
+
 Contents
 --------
 
@@ -8,11 +14,13 @@ Contents
     * Draw basic geometry
     * Export to GDS
 - [devices](devices.py)
+    * Build hierarchical photonic-crystal example devices
     * Reference other patterns
     * Add ports to a pattern
-    * Snap ports together to build a circuit
+    * Use `Builder` to snap ports together into a circuit
     * Check for dangling references
 - [library](library.py)
+    * Continue from `devices.py` using a lazy library
     * Create a `LazyLibrary`, which loads / generates patterns only when they are first used
     * Explore alternate ways of specifying a pattern for `.plug()` and `.place()`
     * Design a pattern which is meant to plug into an existing pattern (via `.interface()`)
@@ -28,7 +36,8 @@ Contents
     * Advanced port manipulation and connections
 
 
-Additionaly, [pcgen](pcgen.py) is a utility module for generating photonic crystal lattices.
+Additionally, [pcgen](pcgen.py) is a utility module used by `devices.py` for generating
+photonic-crystal lattices; it is support code rather than a step-by-step tutorial.
 
 
 Running
@@ -40,3 +49,6 @@ cd examples/tutorial
 python3 basic_shapes.py
 klayout -e basic_shapes.gds
 ```
+
+Some tutorials depend on outputs from earlier ones. In particular, `library.py`
+expects `circuit.gds`, which is generated by `devices.py`.