Merge pull request #56 from sourceryinstitute/update-readme

Update README.md with usage patterns and benefits

Author: Damian Rouson

README.md

@@ -11,37 +11,60 @@ Overview
 DAG is a Fortran 2018 library for creating and manipulating directed acyclic graphs (DAGs).  
 DAG is based on a fork of [daglib by Jacob Williams], refactored to 
 
-* Adopt a functional programming pattern based on (mostly) pure function constructors
-  and component getters but no setters.  When compilers cooperate, we recommend using 
-  `associate`  to assign names to constructor results to avoid unnecessary copies.
+* Adopt a functional programming pattern based on (mostly) pure functions. 
 * Add build system and test harness automated by [fpm],
 * Add unit testing written with [Vegetables], 
 * Add continuous-integration testing and documentation deployment via [GitHub Actions], 
 * Add [documentation] generated by [FORD], 
 * Add runtime assertion-checking using [Assert], and
-* Add [JSON] file input/output using [jsonff].  
-
-Constructor results contain an private index array that describes a topologically sorting
-of the vertices in a DAG.
+* Add [JSON] file input/output using [jsonff].
+* Ensure that dag objects always have a valid state that includes a topological
+  ordering stored without mutating vertices or vertex arrays. 
+
+Usage
+-----
+When compilers cooperate, we recommend using `associate` to assign names to
+dag's user-defined structure constructor results.  See the [example]
+subdirectory for demonstrations of how we use `associate` instead of the
+declare-and-define style that is much more common in Fortran
+and other imperative programming languages.  Associating a name instead of
+declaring an object and then later defining it offers several potential
+advantages:
+
+* It prevents the accidental use of declared-but-undefined data.
+* It provides immutable state, which in turn
+  - prevents the mistaken overwriting of data and
+  - enables some possible compiler optimizations.
+  
+_Caveat emptor_: your mileage may vary.  Compiler support for `associate` is
+evolving and compiler might or might not exploit optimizatio opportunities.
+When weird things happen, resort to declaring and subsequently defining
+objects by assigning a constructor function result to the declared object.
 
 Prerequisites
 -------------
-The [fpm] package manager automatically downloads and builds all dependencies.
-See [fpm.toml] for a complete list, including version numbers.
+The [fpm] package manager automatically downloads and builds all
+dependencies.  See [fpm.toml] for a complete list, including version numbers.
+
+Downloading
+-----------
+Obtain dag by downloading the [latest release] or cloning the repository as
+follows:
 
-Downloading, building and testing
---------------------
-With [fpm]  installed, clone
 ```
 git clone [email protected]:sourceryinstitute/dag
 ```
-### Serial build and testing
-Build and test the `dag` library  with in a `bash`-like shell as follows:
+
+Building and testing
+--------------------
+### Building and testing for serial execution
+Build and test `dag` in a `bash`-like shell as follows:
 ```
 fpm test
 ```
-### Parallel building and testing with the gfortran/OpenCoarrays
-Build and test the `dag` library  with in a `bash`-like shell as follows:
+### Building and testing for parallel execution
+With [gfortran] and [OpenCoarrays] installed, build and test `dag` in a
+`bash`-like shell as follows:
 ```
 fpm test --compiler caf --runner "cafrun -n 2"
 ```
@@ -52,7 +75,6 @@ Please report any test failures by submitting an [issue] on the DAG repository.
 
 Examples
 --------
-
 The [example] subdirectory provides the following examples:
 
 * [print-to-json.f90] - constructs and prints it a JSON representation the DAG. 
@@ -73,16 +95,30 @@ fpm run --example read-from-json > dag.json
 fpm run --example dag-to-dot > feats-dag.dot
 dot -Tpdf -o feats.pdf feats.dot
 ```
-which should produce the graph below.
+which should produce the following graph below:
 
 ![feats-dependencies](https://user-images.githubusercontent.com/13108868/133311851-721b7cda-1d10-4ee1-a51d-6169ca624839.png)
 
-
 License
 -------
 
 This library is released under a [BSD-3 license].
 
+Acknowledgments
+----------------
+
+| | |
+|-|-|
+| We gratefully acknowledge support from [NASA Langley Research Center] under contract number 80NSSC20P2246.  | <img src="https://user-images.githubusercontent.com/13108868/112893191-304ce180-908f-11eb-8bea-e0cab5322aa8.png" alt="NASA logo" width="100">|
+
+Donate
+------
+If you find this software useful, please consider donating code or
+[currency](http://bit.ly/donate-to-sourcery-institute) to aid in development efforts.
+
+[NASA Langley Research Center]: https://www.nasa.gov/langley
+[latest release]: https://github.com/sourceryinstitute/dag/releases/latest
+
 [daglib by Jacob Williams]: https://github.com/jacobwilliams/daglib
 [GraphViz]: https://www.graphviz.org
 [OpenCoarrays]: https://github.com/sourceryinstitute/opencoarrays