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, 61 insertions, 39 deletions

diff --git a/Modules/CMakeParseArguments.cmake b/Modules/CMakeParseArguments.cmake
index 016da0c..4248176 100644
--- a/Modules/CMakeParseArguments.cmake
+++ b/Modules/CMakeParseArguments.cmake
@@ -1,64 +1,86 @@
-# CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)
+#.rst:
+# CMakeParseArguments
+# -------------------
 #
-# CMAKE_PARSE_ARGUMENTS() is intended to be used in macros or functions for
-# parsing the arguments given to that macro or function.
-# It processes the arguments and defines a set of variables which hold the
+#
+#
+# CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords>
+# <multi_value_keywords> args...)
+#
+# CMAKE_PARSE_ARGUMENTS() is intended to be used in macros or functions
+# for parsing the arguments given to that macro or function.  It
+# processes the arguments and defines a set of variables which hold the
 # values of the respective options.
 #
 # The <options> argument contains all options for the respective macro,
-# i.e. keywords which can be used when calling the macro without any value
-# following, like e.g. the OPTIONAL keyword of the install() command.
+# i.e.  keywords which can be used when calling the macro without any
+# value following, like e.g.  the OPTIONAL keyword of the install()
+# command.
 #
 # The <one_value_keywords> argument contains all keywords for this macro
-# which are followed by one value, like e.g. DESTINATION keyword of the
+# which are followed by one value, like e.g.  DESTINATION keyword of the
 # install() command.
 #
-# The <multi_value_keywords> argument contains all keywords for this macro
-# which can be followed by more than one value, like e.g. the TARGETS or
-# FILES keywords of the install() command.
+# The <multi_value_keywords> argument contains all keywords for this
+# macro which can be followed by more than one value, like e.g.  the
+# TARGETS or FILES keywords of the install() command.
 #
 # When done, CMAKE_PARSE_ARGUMENTS() will have defined for each of the
 # keywords listed in <options>, <one_value_keywords> and
 # <multi_value_keywords> a variable composed of the given <prefix>
-# followed by "_" and the name of the respective keyword.
-# These variables will then hold the respective value from the argument list.
+# followed by "_" and the name of the respective keyword.  These
+# variables will then hold the respective value from the argument list.
 # For the <options> keywords this will be TRUE or FALSE.
 #
 # All remaining arguments are collected in a variable
-# <prefix>_UNPARSED_ARGUMENTS, this can be checked afterwards to see whether
-# your macro was called with unrecognized parameters.
+# <prefix>_UNPARSED_ARGUMENTS, this can be checked afterwards to see
+# whether your macro was called with unrecognized parameters.
+#
+# As an example here a my_install() macro, which takes similar arguments
+# as the real install() command:
+#
+# ::
+#
+#    function(MY_INSTALL)
+#      set(options OPTIONAL FAST)
+#      set(oneValueArgs DESTINATION RENAME)
+#      set(multiValueArgs TARGETS CONFIGURATIONS)
+#      cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
+#      ...
 #
-# As an example here a my_install() macro, which takes similar arguments as the
-# real install() command:
 #
-#   function(MY_INSTALL)
-#     set(options OPTIONAL FAST)
-#     set(oneValueArgs DESTINATION RENAME)
-#     set(multiValueArgs TARGETS CONFIGURATIONS)
-#     cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
-#     ...
 #
 # Assume my_install() has been called like this:
-#   my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
-#
-# After the cmake_parse_arguments() call the macro will have set the following
-# variables:
-#   MY_INSTALL_OPTIONAL = TRUE
-#   MY_INSTALL_FAST = FALSE (this option was not used when calling my_install()
-#   MY_INSTALL_DESTINATION = "bin"
-#   MY_INSTALL_RENAME = "" (was not used)
-#   MY_INSTALL_TARGETS = "foo;bar"
-#   MY_INSTALL_CONFIGURATIONS = "" (was not used)
-#   MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (no value expected after "OPTIONAL"
+#
+# ::
+#
+#    my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
+#
+#
+#
+# After the cmake_parse_arguments() call the macro will have set the
+# following variables:
+#
+# ::
+#
+#    MY_INSTALL_OPTIONAL = TRUE
+#    MY_INSTALL_FAST = FALSE (this option was not used when calling my_install()
+#    MY_INSTALL_DESTINATION = "bin"
+#    MY_INSTALL_RENAME = "" (was not used)
+#    MY_INSTALL_TARGETS = "foo;bar"
+#    MY_INSTALL_CONFIGURATIONS = "" (was not used)
+#    MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (no value expected after "OPTIONAL"
+#
+#
 #
 # You can then continue and process these variables.
 #
-# Keywords terminate lists of values, e.g. if directly after a one_value_keyword
-# another recognized keyword follows, this is interpreted as the beginning of
-# the new option.
-# E.g. my_install(TARGETS foo DESTINATION OPTIONAL) would result in
-# MY_INSTALL_DESTINATION set to "OPTIONAL", but MY_INSTALL_DESTINATION would
-# be empty and MY_INSTALL_OPTIONAL would be set to TRUE therefor.
+# Keywords terminate lists of values, e.g.  if directly after a
+# one_value_keyword another recognized keyword follows, this is
+# interpreted as the beginning of the new option.  E.g.
+# my_install(TARGETS foo DESTINATION OPTIONAL) would result in
+# MY_INSTALL_DESTINATION set to "OPTIONAL", but MY_INSTALL_DESTINATION
+# would be empty and MY_INSTALL_OPTIONAL would be set to TRUE therefor.
 
 #=============================================================================
 # Copyright 2010 Alexander Neundorf <neundorf@kde.org>