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, 261 insertions, 141 deletions

diff --git a/Modules/UseJava.cmake b/Modules/UseJava.cmake
index c9635b5..f7f242b 100644
--- a/Modules/UseJava.cmake
+++ b/Modules/UseJava.cmake
@@ -1,120 +1,220 @@
-# - Use Module for Java
-# This file provides functions for Java. It is assumed that FindJava.cmake
-# has already been loaded.  See FindJava.cmake for information on how to
-# load Java into your CMake project.
+#.rst:
+# UseJava
+# -------
+#
+# Use Module for Java
+#
+# This file provides functions for Java.  It is assumed that
+# FindJava.cmake has already been loaded.  See FindJava.cmake for
+# information on how to load Java into your CMake project.
 #
 # add_jar(target_name
-#         [SOURCES] source1 [source2 ...] [resource1 ...]
-#         [INCLUDE_JARS jar1 [jar2 ...]]
-#         [ENTRY_POINT entry]
-#         [VERSION version]
-#         [OUTPUT_NAME name]
-#         [OUTPUT_DIR dir]
-#        )
-#
-# This command creates a <target_name>.jar. It compiles the given source files
-# (source) and adds the given resource files (resource) to the jar file. If
-# only resource files are given then just a jar file is created. The list of
-# include jars are added to the classpath when compiling the java sources and
-# also to the dependencies of the target. INCLUDE_JARS also accepts other
-# target names created by add_jar. For backwards compatibility, jar files
-# listed as sources are ignored (as they have been since the first version of
-# this module).
+#
+# ::
+#
+#          [SOURCES] source1 [source2 ...] [resource1 ...]
+#          [INCLUDE_JARS jar1 [jar2 ...]]
+#          [ENTRY_POINT entry]
+#          [VERSION version]
+#          [OUTPUT_NAME name]
+#          [OUTPUT_DIR dir]
+#         )
+#
+#
+#
+# This command creates a <target_name>.jar.  It compiles the given
+# source files (source) and adds the given resource files (resource) to
+# the jar file.  If only resource files are given then just a jar file
+# is created.  The list of include jars are added to the classpath when
+# compiling the java sources and also to the dependencies of the target.
+# INCLUDE_JARS also accepts other target names created by add_jar.  For
+# backwards compatibility, jar files listed as sources are ignored (as
+# they have been since the first version of this module).
 #
 # The default OUTPUT_DIR can also be changed by setting the variable
 # CMAKE_JAVA_TARGET_OUTPUT_DIR.
 #
 # Additional instructions:
-#   To add compile flags to the target you can set these flags with
-#   the following variable:
 #
-#       set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
+# ::
+#
+#    To add compile flags to the target you can set these flags with
+#    the following variable:
+#
+#
+#
+# ::
+#
+#        set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
+#
+#
+#
+# ::
+#
+#    To add a path or a jar file to the class path you can do this
+#    with the CMAKE_JAVA_INCLUDE_PATH variable.
+#
+#
+#
+# ::
+#
+#        set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
+#
+#
+#
+# ::
+#
+#    To use a different output name for the target you can set it with:
+#
+#
+#
+# ::
+#
+#        add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
+#
+#
+#
+# ::
+#
+#    To use a different output directory than CMAKE_CURRENT_BINARY_DIR
+#    you can set it with:
+#
+#
+#
+# ::
+#
+#        add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
+#
+#
+#
+# ::
+#
+#    To define an entry point in your jar you can set it with the ENTRY_POINT
+#    named argument:
+#
+#
+#
+# ::
+#
+#        add_jar(example ENTRY_POINT com/examples/MyProject/Main)
+#
+#
+#
+# ::
+#
+#    To define a custom manifest for the jar, you can set it with the manifest
+#    named argument:
+#
 #
-#   To add a path or a jar file to the class path you can do this
-#   with the CMAKE_JAVA_INCLUDE_PATH variable.
 #
-#       set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
+# ::
 #
-#   To use a different output name for the target you can set it with:
+#        add_jar(example MANIFEST /path/to/manifest)
 #
-#       add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
 #
-#   To use a different output directory than CMAKE_CURRENT_BINARY_DIR
-#   you can set it with:
 #
-#       add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
+# ::
 #
-#   To define an entry point in your jar you can set it with the ENTRY_POINT
-#   named argument:
+#    To add a VERSION to the target output name you can set it using
+#    the VERSION named argument to add_jar. This will create a jar file with the
+#    name shibboleet-1.0.0.jar and will create a symlink shibboleet.jar
+#    pointing to the jar with the version information.
 #
-#       add_jar(example ENTRY_POINT com/examples/MyProject/Main)
 #
-#   To define a custom manifest for the jar, you can set it with the manifest
-#   named argument:
 #
-#       add_jar(example MANIFEST /path/to/manifest)
+# ::
 #
-#   To add a VERSION to the target output name you can set it using
-#   the VERSION named argument to add_jar. This will create a jar file with the
-#   name shibboleet-1.0.0.jar and will create a symlink shibboleet.jar
-#   pointing to the jar with the version information.
+#        add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
 #
-#       add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
 #
-#    If the target is a JNI library, utilize the following commands to
-#    create a JNI symbolic link:
 #
-#       set(CMAKE_JNI_TARGET TRUE)
-#       add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
-#       install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
-#       install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
+# ::
 #
-#    If a single target needs to produce more than one jar from its
-#    java source code, to prevent the accumulation of duplicate class
-#    files in subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior
-#    to calling the add_jar() function:
+#     If the target is a JNI library, utilize the following commands to
+#     create a JNI symbolic link:
+#
+#
+#
+# ::
+#
+#        set(CMAKE_JNI_TARGET TRUE)
+#        add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
+#        install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
+#        install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
+#
+#
+#
+# ::
+#
+#     If a single target needs to produce more than one jar from its
+#     java source code, to prevent the accumulation of duplicate class
+#     files in subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior
+#     to calling the add_jar() function:
+#
+#
+#
+# ::
+#
+#        set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
+#        add_jar(foo foo.java)
+#
+#
+#
+# ::
+#
+#        set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
+#        add_jar(bar bar.java)
 #
-#       set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
-#       add_jar(foo foo.java)
 #
-#       set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
-#       add_jar(bar bar.java)
 #
 # Target Properties:
-#   The add_jar() functions sets some target properties. You can get these
-#   properties with the
-#      get_property(TARGET <target_name> PROPERTY <propery_name>)
-#   command.
-#
-#   INSTALL_FILES      The files which should be installed. This is used by
-#                      install_jar().
-#   JNI_SYMLINK        The JNI symlink which should be installed.
-#                      This is used by install_jni_symlink().
-#   JAR_FILE           The location of the jar file so that you can include
-#                      it.
-#   CLASS_DIR          The directory where the class files can be found. For
-#                      example to use them with javah.
+#
+# ::
+#
+#    The add_jar() functions sets some target properties. You can get these
+#    properties with the
+#       get_property(TARGET <target_name> PROPERTY <propery_name>)
+#    command.
+#
+#
+#
+# ::
+#
+#    INSTALL_FILES      The files which should be installed. This is used by
+#                       install_jar().
+#    JNI_SYMLINK        The JNI symlink which should be installed.
+#                       This is used by install_jni_symlink().
+#    JAR_FILE           The location of the jar file so that you can include
+#                       it.
+#    CLASS_DIR          The directory where the class files can be found. For
+#                       example to use them with javah.
+#
+#
 #
 # find_jar(<VAR>
-#          name | NAMES name1 [name2 ...]
-#          [PATHS path1 [path2 ... ENV var]]
-#          [VERSIONS version1 [version2]]
-#          [DOC "cache documentation string"]
-#         )
 #
-# This command is used to find a full path to the named jar. A cache
-# entry named by <VAR> is created to stor the result of this command. If
-# the full path to a jar is found the result is stored in the variable
-# and the search will not repeated unless the variable is cleared. If
-# nothing is found, the result will be <VAR>-NOTFOUND, and the search
-# will be attempted again next time find_jar is invoked with the same
-# variable.
-# The name of the full path to a file that is searched for is specified
-# by the names listed after NAMES argument. Additional search locations
-# can be specified after the PATHS argument. If you require special a
-# version of a jar file you can specify it with the VERSIONS argument.
-# The argument after DOC will be used for the documentation string in
-# the cache.
+# ::
+#
+#           name | NAMES name1 [name2 ...]
+#           [PATHS path1 [path2 ... ENV var]]
+#           [VERSIONS version1 [version2]]
+#           [DOC "cache documentation string"]
+#          )
+#
+#
+#
+# This command is used to find a full path to the named jar.  A cache
+# entry named by <VAR> is created to stor the result of this command.
+# If the full path to a jar is found the result is stored in the
+# variable and the search will not repeated unless the variable is
+# cleared.  If nothing is found, the result will be <VAR>-NOTFOUND, and
+# the search will be attempted again next time find_jar is invoked with
+# the same variable.  The name of the full path to a file that is
+# searched for is specified by the names listed after NAMES argument.
+# Additional search locations can be specified after the PATHS argument.
+# If you require special a version of a jar file you can specify it with
+# the VERSIONS argument.  The argument after DOC will be used for the
+# documentation string in the cache.
 #
 # install_jar(TARGET_NAME DESTINATION)
 #
@@ -124,75 +224,95 @@
 # install_jni_symlink(TARGET_NAME DESTINATION)
 #
 # This command installs the TARGET_NAME JNI symlinks to the given
-# DESTINATION. It should be called in the same scope as add_jar()
-# or it will fail.
+# DESTINATION.  It should be called in the same scope as add_jar() or it
+# will fail.
 #
 # create_javadoc(<VAR>
-#                PACKAGES pkg1 [pkg2 ...]
-#                [SOURCEPATH <sourcepath>]
-#                [CLASSPATH <classpath>]
-#                [INSTALLPATH <install path>]
-#                [DOCTITLE "the documentation title"]
-#                [WINDOWTITLE "the title of the document"]
-#                [AUTHOR TRUE|FALSE]
-#                [USE TRUE|FALSE]
-#                [VERSION TRUE|FALSE]
-#               )
-#
-# Create java documentation based on files or packages. For more
+#
+# ::
+#
+#                 PACKAGES pkg1 [pkg2 ...]
+#                 [SOURCEPATH <sourcepath>]
+#                 [CLASSPATH <classpath>]
+#                 [INSTALLPATH <install path>]
+#                 [DOCTITLE "the documentation title"]
+#                 [WINDOWTITLE "the title of the document"]
+#                 [AUTHOR TRUE|FALSE]
+#                 [USE TRUE|FALSE]
+#                 [VERSION TRUE|FALSE]
+#                )
+#
+#
+#
+# Create java documentation based on files or packages.  For more
 # details please read the javadoc manpage.
 #
-# There are two main signatures for create_javadoc. The first
-# signature works with package names on a path with source files:
-#
-#   Example:
-#   create_javadoc(my_example_doc
-#     PACKAGES com.exmaple.foo com.example.bar
-#     SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
-#     CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
-#     WINDOWTITLE "My example"
-#     DOCTITLE "<h1>My example</h1>"
-#     AUTHOR TRUE
-#     USE TRUE
-#     VERSION TRUE
-#   )
+# There are two main signatures for create_javadoc.  The first signature
+# works with package names on a path with source files:
+#
+# ::
+#
+#    Example:
+#    create_javadoc(my_example_doc
+#      PACKAGES com.exmaple.foo com.example.bar
+#      SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
+#      CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
+#      WINDOWTITLE "My example"
+#      DOCTITLE "<h1>My example</h1>"
+#      AUTHOR TRUE
+#      USE TRUE
+#      VERSION TRUE
+#    )
+#
+#
 #
 # The second signature for create_javadoc works on a given list of
 # files.
 #
-#   create_javadoc(<VAR>
-#                  FILES file1 [file2 ...]
-#                  [CLASSPATH <classpath>]
-#                  [INSTALLPATH <install path>]
-#                  [DOCTITLE "the documentation title"]
-#                  [WINDOWTITLE "the title of the document"]
-#                  [AUTHOR TRUE|FALSE]
-#                  [USE TRUE|FALSE]
-#                  [VERSION TRUE|FALSE]
-#                 )
+# ::
+#
+#    create_javadoc(<VAR>
+#                   FILES file1 [file2 ...]
+#                   [CLASSPATH <classpath>]
+#                   [INSTALLPATH <install path>]
+#                   [DOCTITLE "the documentation title"]
+#                   [WINDOWTITLE "the title of the document"]
+#                   [AUTHOR TRUE|FALSE]
+#                   [USE TRUE|FALSE]
+#                   [VERSION TRUE|FALSE]
+#                  )
+#
+#
 #
 # Example:
-#   create_javadoc(my_example_doc
-#     FILES ${example_SRCS}
-#     CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
-#     WINDOWTITLE "My example"
-#     DOCTITLE "<h1>My example</h1>"
-#     AUTHOR TRUE
-#     USE TRUE
-#     VERSION TRUE
-#   )
-#
-# Both signatures share most of the options. These options are the
-# same as what you can find in the javadoc manpage. Please look at
-# the manpage for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and
-# VERSION.
+#
+# ::
+#
+#    create_javadoc(my_example_doc
+#      FILES ${example_SRCS}
+#      CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
+#      WINDOWTITLE "My example"
+#      DOCTITLE "<h1>My example</h1>"
+#      AUTHOR TRUE
+#      USE TRUE
+#      VERSION TRUE
+#    )
+#
+#
+#
+# Both signatures share most of the options.  These options are the same
+# as what you can find in the javadoc manpage.  Please look at the
+# manpage for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE and VERSION.
 #
 # The documentation will be by default installed to
 #
-#   ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
+# ::
 #
-# if you don't set the INSTALLPATH.
+#    ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
 #
+#
+#
+# if you don't set the INSTALLPATH.
 
 #=============================================================================
 # Copyright 2013 OpenGamma Ltd. <graham@opengamma.com>