Convert builtin help to reStructuredText source files

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.

1 files changed, 103 insertions, 59 deletions

diff --git a/Modules/FortranCInterface.cmake b/Modules/FortranCInterface.cmake
index c59e1f8..dccb26f 100644
--- a/Modules/FortranCInterface.cmake
+++ b/Modules/FortranCInterface.cmake
@@ -1,85 +1,129 @@
-# - Fortran/C Interface Detection
+#.rst:
+# 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:
-#   FortranCInterface_GLOBAL_FOUND = Global subroutines and functions
-#   FortranCInterface_MODULE_FOUND = Module subroutines and functions
-#                                    (declared by "MODULE PROCEDURE")
+#
+# ::
+#
+#    FortranCInterface_GLOBAL_FOUND = Global subroutines and functions
+#    FortranCInterface_MODULE_FOUND = Module subroutines and functions
+#                                     (declared by "MODULE PROCEDURE")
+#
 # A 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> ...])
+#
+# ::
+#
+#    FortranCInterface_HEADER(<file>
+#                             [MACRO_NAMESPACE <macro-ns>]
+#                             [SYMBOL_NAMESPACE <ns>]
+#                             [SYMBOLS [<module>:]<function> ...])
+#
 # It generates in <file> definitions of the following macros:
-#   #define FortranCInterface_GLOBAL (name,NAME) ...
-#   #define FortranCInterface_GLOBAL_(name,NAME) ...
-#   #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
-#   #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
-# These macros mangle four categories of Fortran symbols,
-# respectively:
-#   - Global symbols without '_': call mysub()
-#   - Global symbols with '_'   : call my_sub()
-#   - Module symbols without '_': use mymod; call mysub()
-#   - Module symbols with '_'   : use mymod; call my_sub()
+#
+# ::
+#
+#    #define FortranCInterface_GLOBAL (name,NAME) ...
+#    #define FortranCInterface_GLOBAL_(name,NAME) ...
+#    #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
+#    #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
+#
+# These macros mangle four categories of Fortran symbols, respectively:
+#
+# ::
+#
+#    - Global symbols without '_': call mysub()
+#    - Global symbols with '_'   : 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 MACRO_NAMESPACE option replaces the default "FortranCInterface_"
+# All macros require raw names in both lower case and upper case.  The
+# MACRO_NAMESPACE option replaces the default "FortranCInterface_"
 # prefix with a given namespace "<macro-ns>".
 #
 # The SYMBOLS option lists symbols to mangle automatically with C
 # preprocessor definitions:
-#   <function>          ==> #define <ns><function> ...
-#   <module>:<function> ==> #define <ns><module>_<function> ...
+#
+# ::
+#
+#    <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 SYMBOL_NAMESPACE option prefixes all preprocessor definitions
+# definition is created, and a warning is displayed.  The
+# SYMBOL_NAMESPACE option prefixes all preprocessor definitions
 # generated by the SYMBOLS option with a given namespace "<ns>".
 #
 # Example usage:
-#   include(FortranCInterface)
-#   FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
-# This creates a "FC.h" header that defines mangling macros
-# FC_GLOBAL(), FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
+#
+# ::
+#
+#    include(FortranCInterface)
+#    FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
+#
+# This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
+# FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
 #
 # Example usage:
-#   include(FortranCInterface)
-#   FortranCInterface_HEADER(FCMangle.h
-#                            MACRO_NAMESPACE "FC_"
-#                            SYMBOL_NAMESPACE "FC_"
-#                            SYMBOLS mysub mymod:my_sub)
+#
+# ::
+#
+#    include(FortranCInterface)
+#    FortranCInterface_HEADER(FCMangle.h
+#                             MACRO_NAMESPACE "FC_"
+#                             SYMBOL_NAMESPACE "FC_"
+#                             SYMBOLS mysub mymod:my_sub)
+#
 # 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.
 #
 # Another 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.
-#
-# 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 example, the code:
-#   set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
-#     #                                  ^^^^^  ^^^^^^   ^^^^^
-#   set(FortranCInterface_MODULE_SYMBOLS
-#       __mymodule_MOD_mysub __my_module_MOD_my_sub)
-#     #   ^^^^^^^^     ^^^^^   ^^^^^^^^^     ^^^^^^
-#   include(FortranCInterface)
+#
+# ::
+#
+#    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.
+#
+# 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
+# example, the code:
+#
+# ::
+#
+#    set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
+#      #                                  ^^^^^  ^^^^^^   ^^^^^
+#    set(FortranCInterface_MODULE_SYMBOLS
+#        __mymodule_MOD_mysub __my_module_MOD_my_sub)
+#      #   ^^^^^^^^     ^^^^^   ^^^^^^^^^     ^^^^^^
+#    include(FortranCInterface)
+#
 # 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.)
+# (The carets point at raw symbol names for clarity in this example but
+# are not needed.)
 
 #=============================================================================
 # Copyright 2008-2009 Kitware, Inc.