doc(README/ford): add doc-generation instructions

update submodules to work around FORD bug

Author: Damian Rouson

README.md

@@ -35,11 +35,14 @@ Utility functions
 
 * Array functions
 * Assertions
-* Emulated intrinsic functions
+* Emulated intrinsic functions: `findloc`
+* Emulated collective subroutines: `co_sum`, `co_broadcast`
+* User-defined collective subroutines: `co_all`
 * String functions
 
 Classes
 -------
+* Parallel data partitioning and gathering
 * (Co-)Object pattern abstract parent
 
 Prerequisites
@@ -65,13 +68,19 @@ fpm test \
   --flag "-Wall" \
   --flag "-std=f2018" \
   --flag "-DCOMPILER_LACKS_COLLECTIVE_SUBROUTINES" \
-  --flag "-DCOMPILER_LACKS_FINDLOC" 
+  --flag "-DCOMPILER_LACKS_FINDLOC"
 ```
-where the `COMPILER_LACKS_*` flags exercise the Sourcery Library's 
-emulated instrinsic procedures, which are intended for use with 
+where the `COMPILER_LACKS_*` flags exercise the Sourcery Library's
+emulated instrinsic procedures, which are intended for use with
 compiler versions that lack support for the named features.  Delete
 those flags with compilers that support these features.
 
+Build documentation
+-------------------
+```zsh
+ford doc/ford-documentation.md
+```
+
 [GNU Fortran]: https://gcc.gnu.org
 [OpenCoarrays]: https://github.com/sourceryinstitute/opencoarrays
 [fpm]: https://github.com/fortran-lang/fpm

src/data-partition-implementation.f90 renamed to src/data-partition-implementation.F90

@@ -26,15 +26,21 @@
       end block
     end associate
 
+#ifdef FORD
+  end procedure
+#else
   contains
+#endif
 
     pure function overflow(im, excess) result(extra_datum)
       integer, intent(in) :: im, excess
       integer extra_datum
       extra_datum= merge(1,0,im<=excess)
     end function
 
+#ifndef FORD
   end procedure
+#endif
 
   module procedure first
     if (assertions) call assert( allocated(first_datum), "allocated(first_datum)")

src/emulated_intrinsics_implementation.F90

@@ -12,13 +12,19 @@
 
   module procedure co_all
       call co_reduce(boolean, both)
+#ifdef FORD
+  end procedure
+#else
   contains
+#endif
     pure function both(lhs,rhs) result(lhs_and_rhs)
       logical, intent(in) :: lhs,rhs
       logical lhs_and_rhs
       lhs_and_rhs = lhs .and. rhs
     end function
+#ifndef FORD
   end procedure
+#endif
 
 #ifdef COMPILER_LACKS_COLLECTIVE_SUBROUTINES
   module procedure co_sum_integer