Merge pull request #24 from sourceryinstitute/update-docs

Update documentation & eliminate preprocessing

Author: Damian Rouson

.gitignore

@@ -1,3 +1,6 @@
+# Documentation
+html
+
 # Build directories
 build
 

README.md

@@ -32,35 +32,38 @@ A grab bag of useful tricks in Fortran 2018.
 
 This library gathers software that developers at [Archaeologic Inc.] and
 [Sourcery Institute] find useful across many of our projects, including in
-courses that we teach.  Most code starts here because it feels too small to
-release as a standalone package but too distinct in purpose to fold into other
-existing packages.  Over time, when code that starts here grows in capability, a
-new repository is born and the corresponding code is removed from the Sourcery
-repository.  Following the practice of [semantic versioning], code removal 
-results in a major version number increment.
+courses that we teach.  Most code starts here because it is too limited in 
+capability to release as a standalone package but too distinct in purpose to 
+fold into other existing packages.  Over time, when code that starts here grows
+in capability, a new repository is born and the corresponding code is removed
+from the Sourcery repository.  Examples include the [Assert] and [Emulators]
+libraries.  Following the practice of [semantic versioning], code removal
+causes an increment in the major version number.
 
-versioning to Examples
-include the [Assert] and [Emulators] libraries.
-
-Utility functions
------------------
+Procedures
+---------
 
 * Array functions
 * String functions
 * User-defined collective subroutines: `co_all`
 
 Classes
 -------
-* Parallel data partitioning and gathering
-* (Co-)[Object pattern] abstract parent
-* Runtime units tracking
+* Parallel data partitioning and gathering,
+* (Co-)[Object pattern] abstract parent,
+* Runtime units tracking, and
+* A test oracle using the [Template Method pattern].
+* A command-line abstraction that searches for program arguments.
 
 Prerequisites
 -------------
-See the [fpm manifest](./fpm.toml) for the dependencies and developer
-dependencies, the latter of which are needed only for contributing to Sourcery
-by adding new tests.  Additionally, [FORD] 6.1.0 or later is required for
-producing HTML documentation.
+[FORD] 6.1.0 or later is required for producing HTML documentation (see
+"[Building the documentation]" below for instructions).  The Fortran Package
+Manager ([fpm]) is required to build Sourcery from source.  See the
+[fpm manifest](./fpm.toml) for the dependencies and developer dependencies,
+all of which [fpm] automatically downloads and builds via the `fpm` command
+provided in the "[Downloding, Building, and Testing]" section below.
+
 
 Downloding, Building, and Testing
 ---------------------------------
@@ -95,3 +98,6 @@ documentation.
 [Emulators]: https://github.com/sourceryinstitute/emulators
 [Object pattern]: https://www.cambridge.org/rouson
 [semantic versioning]: https://semver.org
+[Template Method pattern]: https://en.wikipedia.org/wiki/Template_method_pattern
+[Downloding, Building, and Testing]: #downloding-building-and-testing
+[Building the documentation]: #building-the-documentation

doc/ford-documentation.md

@@ -1,7 +1,6 @@
 project:
 summary: A Fortran 2018 utility library.
 src_dir: ../src
-src_dir: ../tests
 output_dir: html
 preprocess: true
 macro: FORD

src/units_implementation.F90 renamed to src/units_implementation.f90

@@ -61,14 +61,12 @@ module units_interface
     procedure :: integer_power
     procedure :: real_power
     procedure :: assign_units
-#ifndef FORD
     generic :: operator(+)=>add
     generic :: operator(*)=>multiply
     generic :: operator(/)=>divide
     generic :: operator(-)=>subtract,negate
     generic :: operator(**)=>integer_power,real_power
     generic :: assignment(=)=>assign_units
-#endif
   end type
 
   interface
@@ -88,10 +86,7 @@ pure module subroutine assign_units(lhs,rhs)
         class(units), intent(in) :: rhs
     end subroutine
 
-#ifndef HAVE_ERROR_STOP_IN_PURE
-    impure &
-#endif
-    elemental module function integer_power(this,exponent_) result(this_raised)
+    impure elemental module function integer_power(this,exponent_) result(this_raised)
       !! result has units of the opearand raised to the power "exponent_"
         implicit none
         class(units), intent(in) :: this
@@ -106,42 +101,29 @@ module function get_units(this) result(exponents)
         integer :: exponents(num_fundamental)
     end function
 
-#ifndef HAVE_ERROR_STOP_IN_PURE
-        impure &
-#endif
-    elemental module function get_system(this) result(system_of_units)
+    impure elemental module function get_system(this) result(system_of_units)
       !! result is enumerated value designating units system
         implicit none
         class(units), intent(in) :: this
         integer :: system_of_units
     end function
 
-
-#ifndef HAVE_ERROR_STOP_IN_PURE
-    impure &
-#endif
-    elemental module function real_power(this,exponent_) result(this_raised)
+    impure elemental module function real_power(this,exponent_) result(this_raised)
       !! result is the units of the operand raised to the power "exponent_"; includes check that operand is dimensionless
         implicit none
         class(units), intent(in) :: this
         real, intent(in) :: exponent_
         type(units) :: this_raised
     end function
 
-#ifndef HAVE_ERROR_STOP_IN_PURE
-    impure &
-#endif
-    elemental module function add(lhs,rhs) result(total)
+    impure elemental module function add(lhs,rhs) result(total)
       !! result is the units of the sum of two dimensional quantities; includes operand consistency check
         implicit none
         class(units), intent(in) :: lhs,rhs
         type(units) :: total
     end function
 
-#ifndef HAVE_ERROR_STOP_IN_PURE
-    impure &
-#endif
-    elemental module function subtract(lhs,rhs) result(difference)
+    impure elemental module function subtract(lhs,rhs) result(difference)
       !! result is the units of the difference of two dimensional quantities; includes operand consistency check
         implicit none
         class(units), intent(in) :: lhs,rhs