FortranCInterface: Improve documentation formatting and organization

Organize content into sections.  Define functions via explicit markup
blocks so we can cross-reference them.

Modules/FortranCInterface.cmake

@@ -5,27 +5,33 @@ FortranCInterface
 Fortran/C Interface Detection
 
 This module automatically detects the API by which C and Fortran
-languages interact.  Variables indicate if the mangling is found:
+languages interact.
 
-::
+Module Variables
+^^^^^^^^^^^^^^^^
 
-   FortranCInterface_GLOBAL_FOUND = Global subroutines and functions
+Variables that indicate if the mangling is found:
-   FortranCInterface_MODULE_FOUND = Module subroutines and functions
-                                    (declared by "MODULE PROCEDURE")
 
-A function is provided to generate a C header file containing macros
+``FortranCInterface_GLOBAL_FOUND``
-to mangle symbol names:
+  Global subroutines and functions.
 
-::
+``FortranCInterface_MODULE_FOUND``
+  Module subroutines and functions (declared by "MODULE PROCEDURE").
+
+Module Functions
+^^^^^^^^^^^^^^^^
+
+.. command:: FortranCInterface_HEADER
+
+  The ``FortranCInterface_HEADER`` function is provided to generate a
+  C header file containing macros to mangle symbol names::
 
     FortranCInterface_HEADER(<file>
                              [MACRO_NAMESPACE <macro-ns>]
                              [SYMBOL_NAMESPACE <ns>]
                              [SYMBOLS [<module>:]<function> ...])
 
-It generates in <file> definitions of the following macros:
+  It generates in ``<file>`` definitions of the following macros::
-
-::
 
      #define FortranCInterface_GLOBAL (name,NAME) ...
      #define FortranCInterface_GLOBAL_(name,NAME) ...
@@ -34,44 +40,61 @@ It generates in <file> definitions of the following macros:
 
   These macros mangle four categories of Fortran symbols, respectively:
 
-::
+  * Global symbols without '_': ``call mysub()``
-
+  * Global symbols with '_'   : ``call my_sub()``
-   - Global symbols without '_': call mysub()
+  * Module symbols without '_': ``use mymod; call mysub()``
-   - Global symbols with '_'   : call my_sub()
+  * Module symbols with '_'   : ``use mymod; call my_sub()``
-   - Module symbols without '_': use mymod; call mysub()
-   - Module symbols with '_'   : use mymod; call my_sub()
 
   If mangling for a category is not known, its macro is left undefined.
-All macros require raw names in both lower case and upper case.  The
+  All macros require raw names in both lower case and upper case.
-MACRO_NAMESPACE option replaces the default "FortranCInterface_"
-prefix with a given namespace "<macro-ns>".
 
-The SYMBOLS option lists symbols to mangle automatically with C
+  The options are:
-preprocessor definitions:
 
-::
+  ``MACRO_NAMESPACE``
+    Replace the default ``FortranCInterface_`` prefix with a given
+    namespace ``<macro-ns>``.
+
+  ``SYMBOLS``
+    List symbols to mangle automatically with C preprocessor definitions::
 
       <function>          ==> #define <ns><function> ...
       <module>:<function> ==> #define <ns><module>_<function> ...
 
     If the mangling for some symbol is not known then no preprocessor
-definition is created, and a warning is displayed.  The
+    definition is created, and a warning is displayed.
-SYMBOL_NAMESPACE option prefixes all preprocessor definitions
-generated by the SYMBOLS option with a given namespace "<ns>".
 
-Example usage:
+  ``SYMBOL_NAMESPACE``
+    Prefix all preprocessor definitions generated by the ``SYMBOLS``
+    option with a given namespace ``<ns>``.
 
-::
+.. command:: FortranCInterface_VERIFY
+
+  The ``FortranCInterface_VERIFY`` function is provided to verify
+  that the Fortran and C/C++ compilers work together::
+
+    FortranCInterface_VERIFY([CXX] [QUIET])
+
+  It tests whether a simple test executable using Fortran and C (and C++
+  when the CXX option is given) compiles and links successfully.  The
+  result is stored in the cache entry ``FortranCInterface_VERIFIED_C``
+  (or ``FortranCInterface_VERIFIED_CXX`` if ``CXX`` is given) as a boolean.
+  If the check fails and ``QUIET`` is not given the function terminates with a
+  fatal error message describing the problem.  The purpose of this check
+  is to stop a build early for incompatible compiler combinations.  The
+  test is built in the ``Release`` configuration.
+
+Example Usage
+^^^^^^^^^^^^^
+
+.. code-block:: cmake
 
    include(FortranCInterface)
    FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
 
-This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
+This creates a "FC.h" header that defines mangling macros ``FC_GLOBAL()``,
-FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
+``FC_GLOBAL_()``, ``FC_MODULE()``, and ``FC_MODULE_()``.
 
-Example usage:
+.. code-block:: cmake
-
-::
 
    include(FortranCInterface)
    FortranCInterface_HEADER(FCMangle.h
@@ -79,40 +102,25 @@ Example usage:
                             SYMBOL_NAMESPACE "FC_"
                             SYMBOLS mysub mymod:my_sub)
 
-This creates a "FCMangle.h" header that defines the same FC_*()
+This creates a "FCMangle.h" header that defines the same ``FC_*()``
 mangling macros as the previous example plus preprocessor symbols
-FC_mysub and FC_mymod_my_sub.
+``FC_mysub`` and ``FC_mymod_my_sub``.
 
-Another function is provided to verify that the Fortran and C/C++
+Additional Manglings
-compilers work together:
+^^^^^^^^^^^^^^^^^^^^
 
-::
+FortranCInterface is aware of possible ``GLOBAL`` and ``MODULE`` manglings
-
+for many Fortran compilers, but it also provides an interface to specify
-   FortranCInterface_VERIFY([CXX] [QUIET])
+new possible manglings.  Set the variables::
-
-It tests whether a simple test executable using Fortran and C (and C++
-when the CXX option is given) compiles and links successfully.  The
-result is stored in the cache entry FortranCInterface_VERIFIED_C (or
-FortranCInterface_VERIFIED_CXX if CXX is given) as a boolean.  If the
-check fails and QUIET is not given the function terminates with a
-FATAL_ERROR message describing the problem.  The purpose of this check
-is to stop a build early for incompatible compiler combinations.  The
-test is built in the Release configuration.
-
-FortranCInterface is aware of possible GLOBAL and MODULE manglings for
-many Fortran compilers, but it also provides an interface to specify
-new possible manglings.  Set the variables
-
-::
 
    FortranCInterface_GLOBAL_SYMBOLS
    FortranCInterface_MODULE_SYMBOLS
 
 before including FortranCInterface to specify manglings of the symbols
-"MySub", "My_Sub", "MyModule:MySub", and "My_Module:My_Sub".  For
+``MySub``, ``My_Sub``, ``MyModule:MySub``, and ``My_Module:My_Sub``.
-example, the code:
+For example, the code:
 
-::
+.. code-block:: cmake
 
    set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
      #                                  ^^^^^  ^^^^^^   ^^^^^
@@ -121,7 +129,7 @@ example, the code:
      #   ^^^^^^^^     ^^^^^   ^^^^^^^^^     ^^^^^^
    include(FortranCInterface)
 
-tells FortranCInterface to try given GLOBAL and MODULE manglings.
+tells FortranCInterface to try given ``GLOBAL`` and ``MODULE`` manglings.
 (The carets point at raw symbol names for clarity in this example but
 are not needed.)
 #]=======================================================================]