README: rearrangement; revise Gawk @include discussion.

1 files changed, 30 insertions, 17 deletions

diff --git a/README.md b/README.md
index 453c4bf..336fb10 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,11 @@ Then this sort of code is possible:
 We have implemented a facsimile of an Awk input scanning loop inside a function
 with a bit of syntactic sugar.
 
+`cppawk` has low dependencies. It's written in shell, and makes use of the
+`sed` and `printf` utilities.  Preprocessed programs can be captured and
+transferred for execution to systems that have Awk but do not have a
+preprocessor.
+
 ## Roadmap
 
 `cppawk` is been carefully developed, and has a regression test suite.
@@ -57,9 +62,11 @@ itself. For instance if `cppawk` is `/usr/bin/cppawk`, it looks in
 *   You know Awk. You know C preprocessing inside out. Now use two things
     that you know, together, in obvious ways.
 
-*   Awks other than GNU Awk have poor support for making a program out of
-    multiple files.  No compile meta-programming, or conditional selection
-    of code.
+*   You can organize an Awk program into a tree of files that
+    the preprocessor "compiles" into a single "executable".
+
+*   You can use macros for C-style meta-programming, and for conditional
+    selection of code.
 
 *   Other minor benefits: Awk has no comments other than from a `#`
     character to the end of the line. You get `/* ... */` comments
@@ -75,20 +82,26 @@ itself. For instance if `cppawk` is `/usr/bin/cppawk`, it looks in
 
 *   It provides no way to capture all the included output.
 
-*   The way `@include` searches for files is inferior to `cpp`. GNU Awk's
-    include search is driven by the `AWKPATH` variable which brings in all the
-    disadvantages shared by shared by `PATH`-like variables.  In contrast `cpp`
-    implements the familiar behavior that an `#include "..."` directive is
-    resolved relative to the directory of the file which contains that
-    `#include` directive. No configuration is required for a program to find
-    all of its included pieces.
+*   The way `@include` searches for files is inferior to `cpp`;
+    it doesn't look in the same directory as the parent file which contains the
+    `@include` syntax. It reacts to an `AWKPATH` environment variable which has
+    no provision for referencing relative to the location of the parent file.
+
+*   `@include` requires, syntactically, a string-literal-like specification
+    of the path name to be included. An expression is not allowed. For
+    instance, if a GNU Awk program cannot do this:
+
+        ::awk
+        self = calculate_own_path_somehow();
+        @include self "lib/util"  # error
+
+    By contrast `cppawk` program just does this:
+
+        ::c
+        #include "lib/util"  // no problem
 
-## I use `awk` on embedded systems with no `cpp`!
+    The C preprocessor allows macro-replacement to take place in `#include`:
 
-Though packaged that way, `cppawk` doesn't have to be used as an interpreter
-which preprocesses and runs the code. Preprocessed code can be captured with
-the `--prepro-only` option, and then transferred to a target system for
-execution with its Awk.
+        ::c
+        #include FOO_LIB   // conditionally-defined macro to select lib
 
-**Tip**: it may be a good idea to tweak `cppawk` so that it doesn't define the
-`__gawk__` symbol, if your target system's Awk isn't GNU Awk.