Touch docs (#67)

* Suggest use of native type names

* Update intro paragraphs

This excellent contribution is from @gregtucker.

docs/source/bmi.spec.rst

@@ -1,19 +1,34 @@
-The *Basic Model Interface* (BMI) is a library specification
-created by the `Community Surface Dynamics Modeling System`_ (CSDMS)
-to facilitate the conversion of a model or dataset
-into a reusable, plug-and-play component.
-Recall that, in this context, an interface is a named set of functions
-with prescribed arguments and return values.
-The BMI functions make a model self-describing and fully controllable
-by a modeling framework or application.
-By design, the BMI functions are straightforward to implement in
-any language, using only simple data types from standard language libraries.
-Also by design, the BMI functions are noninvasive.
-This means that a model's BMI does not make calls to other
-components or tools and is not modified to use any
-framework-specific data structures. A BMI, therefore, introduces no
-dependencies into a model, so the model can still be used
-in a stand-alone manner.
+When you climb in the driver's seat of an unfamiliar car,
+you are nonetheless presented with a familiar sight.
+Whatever the make or model may be,
+we take it for granted that the vehicle will provide
+a steering wheel, brake pedal, and speedometer,
+alongside the various other controls and readouts
+that are common to essentially all cars and trucks on the planet.
+Although we don't usually think of it this way,
+drivers across the globe benefit from a standard interface:
+a set of control mechanisms and information displays
+that have essentially the same design regardless of whether the vehicle
+is a tiny electric two-seater or a giant stretch limousine.
+This standard interface makes the job of operating a vehicle much easier
+than it would be if each one presented a radically different interface.
+Imagine a world where switching from a sports car to a pickup truck
+required months of study and practice!
+Similarly, railroads benefit from a standard for coupling rail cars together.
+The result: trains can be assembled from combinations of all sorts
+of different rail cars, built by different companies,
+in different places, and with different purposes.
+
+We believe that numerical models,
+and the sub-components that make up those models,
+should offer a similar kind of standardization.
+To this end,
+the `Community Surface Dynamics Modeling System`_ (CSDMS)
+has developed the *Basic Model Interface* (BMI):
+a set of standard control and query functions that,
+when added to a model code,
+make that model both easier to learn
+and easier to couple with other software elements.
 
 While a BMI can be written for any language,
 CSDMS currently supports four languages:

docs/source/bmi.var_funcs.rst

@@ -52,8 +52,10 @@ A model can have one or more grids.
 
 The `get_var_type` function provides the data type of the
 variable as it's stored in memory by the model.
-The data type is returned as a string following the :term:`numpy` convention
-used by the `dtype`_ attribute; e.g., `int32`, `float`, etc.
+The data type is returned as a string.
+Use of native language type names is encouraged;
+e.g., in C, use `int`, `float`, and `double`,
+while in Fortran, use `integer`, `real`, and `double precision`.
 
 **Implementation notes**