Merge pull request #50 from fortran-lang/reorg-doc

Reorganize & clarify documentation structure

API-doc-FORD-file.md

@@ -26,7 +26,7 @@ license: by-sa
 author: Paul N. Swarztrauber &
         fortran-lang/fftpack contributors
 author_pic: https://fortran-lang.org/assets/img/fortran_logo_512x512.png
-author_email: [email protected]
+email: [email protected]
 github: https://github.com/fortran-lang
 twitter: https://twitter.com/fortranlang
 website: https://fortran-lang.org

README.md

@@ -69,9 +69,9 @@ See the our [GitHub Pages site] for documentation generated by [FORD] from the f
 
 ## References 
 Although fortran-lang is _not_ interface-compatible with any of the following libraries, each contains documentation that might be useful for different reasons:
-- **Recommended reference:** The [scipy.fftpack] documentation contains succinct description of the storage sequences for function results that match those in fortran-lang/fftpack, e.g., the location of the real and imaginary parts of the `rfft` function result.
-- **Theory reference:** The [documentation for the GNU/gsl FFT routines], which are also based on netlib/fftpack, provides some useful definitions of FFT terminology and represenations of the analytical forms of the Discrete Fourier Transform nicely formatted by [LaTeX].
-- **Historical reference:** The [netlib/fftpack] library on which fortran-lang/fftpack is useful for understanding several fortran-lang/fftpack design choices, e.g., the procedure dependencies.
+* **Recommended reference:** The [scipy.fftpack] documentation contains succinct description of the storage sequences for function results that match those in fortran-lang/fftpack, e.g., the location of the real and imaginary parts of the `rfft` function result.
+* **Theory reference:** The [documentation for the GNU/gsl FFT routines], which are also based on netlib/fftpack, provides some useful definitions of FFT terminology and represenations of the analytical forms of the Discrete Fourier Transform nicely formatted by [LaTeX].
+* **Historical reference:** The [netlib/fftpack] library on which fortran-lang/fftpack is useful for understanding several fortran-lang/fftpack design choices, e.g., the procedure dependencies.
 
 [FORD]: https://github.com/Fortran-FOSS-Programmers/ford
 [project file]: ./API-doc-FORD-file.md

doc/README.md

@@ -0,0 +1,17 @@
+Fortran-lang/fftpack Documentation
+==================================
+
+Please see the [GitHub Pages site] for the Fortran-lang/fftpack documentation.
+To generate a local copy of the corresponding HTML files, 
+
+1. Set your present working directory to the Fortran-lang/fftpack project root directory,
+2. Execute `ford API-doc-FORD-file.md`, and 
+3. View the result by opening the newly generated `API-doc/` subdirectory in a web browser.
+
+This subdirectory contains 
+1. Documentation files for previous incarnations of fftpack in the [legacy](./legacy) sudirectory and
+2. Files supporting the [API-doc-.md](../API-doc-FORD-file.md) project file that [FORD] uses to generate the GitHub Pages site.
+
+
+[FORD]: https://github.com/Fortran-FOSS-Programmers/ford
+[GitHub Pages site]: https://fortran-lang.github.io/fftpack/