doc(example/README): describe invoke-via-macro

Author: rouson

example/README.md

@@ -1,7 +1,24 @@
 Examples
 ========
 
-This directory contains two example programs.
+This directory contains several example programs.
+
+Example of recommended use
+--------------------------
+The [invoke-via-macro.F90] example demonstrates the recommended ways
+to write assertions in code.  These leverage the function-like macros
+`call_assert` and `call_assert_describe`.  The primary advantage of
+using these macros is that they are completely eliminated when a file
+is compiled with the `ASSERTIONS` macro undefined or defined as `0`.
+To run this example with assertions off, use the command
+```
+fpm run --example invoke-via-macro
+```
+To run the example with assertions on, use either of the following
+commands:
+```
+fpm run --example invoke-via-macro --flag "-DASSERTIONS"
+```
 
 Simple examples
 ---------------
@@ -39,6 +56,7 @@ or more images providing stop codes analogous to those quoted in the [Single-ima
 [Enforcing programming contracts]: #enforcing-programming-contracts
 [Single-image execution]: #single-image-execution
 [simple_assertions.f90]: ./simple_assertions.f90
+[invoke-via-macro.F90]: ./invoke-via-macro.F90
 [UML]: https://en.wikipedia.org/wiki/Unified_Modeling_Language
 [OCL]: https://en.wikipedia.org/wiki/Object_Constraint_Language
 [Atom]: https://atom.io