Merge topic 'doc-formatting'

c3f40f4f Help: Improve formatting of command documentation

Help/command/add_subdirectory.rst

@@ -12,23 +12,23 @@ Add a subdirectory to the build.  The source_dir specifies the
 directory in which the source CMakeLists.txt and code files are
 located.  If it is a relative path it will be evaluated with respect
 to the current directory (the typical usage), but it may also be an
-absolute path.  The binary_dir specifies the directory in which to
+absolute path.  The ``binary_dir`` specifies the directory in which to
 place the output files.  If it is a relative path it will be evaluated
 with respect to the current output directory, but it may also be an
-absolute path.  If binary_dir is not specified, the value of
-source_dir, before expanding any relative path, will be used (the
+absolute path.  If ``binary_dir`` is not specified, the value of
+``source_dir``, before expanding any relative path, will be used (the
 typical usage).  The CMakeLists.txt file in the specified source
 directory will be processed immediately by CMake before processing in
 the current input file continues beyond this command.
 
-If the EXCLUDE_FROM_ALL argument is provided then targets in the
-subdirectory will not be included in the ALL target of the parent
+If the ``EXCLUDE_FROM_ALL`` argument is provided then targets in the
+subdirectory will not be included in the ``ALL`` target of the parent
 directory by default, and will be excluded from IDE project files.
 Users must explicitly build targets in the subdirectory.  This is
 meant for use when the subdirectory contains a separate part of the
 project that is useful but not necessary, such as a set of examples.
-Typically the subdirectory should contain its own project() command
-invocation so that a full build system will be generated in the
+Typically the subdirectory should contain its own :command:`project`
+command invocation so that a full build system will be generated in the
 subdirectory (such as a VS IDE solution file).  Note that inter-target
 dependencies supercede this exclusion.  If a target built by the
 parent project depends on a target in the subdirectory, the dependee

Help/command/aux_source_directory.rst

@@ -8,7 +8,7 @@ Find all source files in a directory.
   aux_source_directory(<dir> <variable>)
 
 Collects the names of all the source files in the specified directory
-and stores the list in the <variable> provided.  This command is
+and stores the list in the ``<variable>`` provided.  This command is
 intended to be used by projects that use explicit template
 instantiation.  Template instantiation files can be stored in a
 "Templates" subdirectory and collected automatically using this

Help/command/build_name.rst

@@ -3,7 +3,7 @@ build_name
 
 Disallowed.  See CMake Policy :policy:`CMP0036`.
 
-Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
+Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.
 
 ::
 
@@ -11,4 +11,5 @@ Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
 
 Sets the specified variable to a string representing the platform and
 compiler settings.  These values are now available through the
-CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
+:variable:`CMAKE_SYSTEM` and
+:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variables.

Help/command/cmake_host_system_information.rst

@@ -8,10 +8,10 @@ Query host system specific information.
   cmake_host_system_information(RESULT <variable> QUERY <key> ...)
 
 Queries system information of the host system on which cmake runs.
-One or more <key> can be provided to select the information to be
-queried.  The list of queried values is stored in <variable>.
+One or more ``<key>`` can be provided to select the information to be
+queried.  The list of queried values is stored in ``<variable>``.
 
-<key> can be one of the following values:
+``<key>`` can be one of the following values:
 
 ::
 

Help/command/cmake_minimum_required.rst

@@ -25,7 +25,7 @@ When version 2.4 or lower is given the command implicitly invokes
 
 which enables compatibility features for CMake 2.4 and lower.
 
-The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
+The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and
 higher.  It should be specified so CMake versions 2.4 and lower fail
 with an error instead of just a warning.
 

Help/command/create_test_sourcelist.rst

@@ -14,17 +14,17 @@ A test driver is a program that links together many small tests into a
 single executable.  This is useful when building static executables
 with large libraries to shrink the total required size.  The list of
 source files needed to build the test driver will be in
-sourceListName.  DriverName is the name of the test driver program.
+``sourceListName``.  ``driverName`` is the name of the test driver program.
 The rest of the arguments consist of a list of test source files, can
 be semicolon separated.  Each test source file should have a function
 in it that is the same name as the file with no extension (foo.cxx
-should have int foo(int, char*[]);) DriverName will be able to call
-each of the tests by name on the command line.  If EXTRA_INCLUDE is
+should have int foo(int, char*[]);) ``driverName`` will be able to call
+each of the tests by name on the command line.  If ``EXTRA_INCLUDE`` is
 specified, then the next argument is included into the generated file.
-If FUNCTION is specified, then the next argument is taken as a
+If ``FUNCTION`` is specified, then the next argument is taken as a
 function name that is passed a pointer to ac and av.  This can be used
-to add extra command line processing to each test.  The cmake variable
-CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set to have code that will be
-placed directly before calling the test main function.
-CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have code that will be
-placed directly after the call to the test main function.
+to add extra command line processing to each test.  The
+``CMAKE_TESTDRIVER_BEFORE_TESTMAIN`` cmake variable can be set to
+have code that will be placed directly before calling the test main function.
+``CMAKE_TESTDRIVER_AFTER_TESTMAIN`` can be set to have code that
+will be placed directly after the call to the test main function.

Help/command/ctest_run_script.rst

@@ -10,6 +10,6 @@ runs a ctest -S script
 
 Runs a script or scripts much like if it was run from ctest -S.  If no
 argument is provided then the current script is run using the current
-settings of the variables.  If NEW_PROCESS is specified then each
-script will be run in a separate process.If RETURN_VALUE is specified
-the return value of the last script run will be put into var.
+settings of the variables.  If ``NEW_PROCESS`` is specified then each
+script will be run in a separate process.If ``RETURN_VALUE`` is specified
+the return value of the last script run will be put into ``var``.

Help/command/ctest_start.rst

@@ -14,7 +14,7 @@ after the binary directory is initialized.  If the 'source' and
 If the track is
 specified, the submissions will go to the specified track.  If APPEND
 is used, the existing TAG is used rather than creating a new one based
-on the current time stamp.  If QUIET is used, CTest will suppress any
+on the current time stamp.  If ``QUIET`` is used, CTest will suppress any
 non-error messages that it otherwise would have printed to the console.
 
 If the :variable:`CTEST_CHECKOUT_COMMAND` variable

Help/command/define_property.rst

@@ -11,11 +11,11 @@ Define and document custom properties.
                    BRIEF_DOCS <brief-doc> [docs...]
                    FULL_DOCS <full-doc> [docs...])
 
-Define one property in a scope for use with the set_property and
-get_property commands.  This is primarily useful to associate
+Define one property in a scope for use with the :command:`set_property` and
+:command:`get_property` commands.  This is primarily useful to associate
 documentation with property names that may be retrieved with the
-get_property command.  The first argument determines the kind of scope
-in which the property should be used.  It must be one of the
+:command:`get_property` command. The first argument determines the kind of
+scope in which the property should be used.  It must be one of the
 following:
 
 ::
@@ -28,18 +28,18 @@ following:
   VARIABLE  = documents a CMake language variable
   CACHED_VARIABLE = documents a CMake cache variable
 
-Note that unlike set_property and get_property no actual scope needs
-to be given; only the kind of scope is important.
+Note that unlike :command:`set_property` and :command:`get_property` no
+actual scope needs to be given; only the kind of scope is important.
 
-The required PROPERTY option is immediately followed by the name of
+The required ``PROPERTY`` option is immediately followed by the name of
 the property being defined.
 
-If the INHERITED option then the get_property command will chain up to
-the next higher scope when the requested property is not set in the
-scope given to the command.  DIRECTORY scope chains to GLOBAL.
-TARGET, SOURCE, and TEST chain to DIRECTORY.
+If the ``INHERITED`` option then the :command:`get_property` command will
+chain up to the next higher scope when the requested property is not set
+in the scope given to the command. ``DIRECTORY`` scope chains to
+``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``.
 
-The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
+The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
 associated with the property as its brief and full documentation.
-Corresponding options to the get_property command will retrieve the
-documentation.
+Corresponding options to the :command:`get_property` command will retrieve
+the documentation.

Help/command/else.rst

@@ -7,4 +7,4 @@ Starts the else portion of an if block.
 
   else(expression)
 
-See the if command.
+See the :command:`if` command.

Help/command/elseif.rst

@@ -7,4 +7,4 @@ Starts the elseif portion of an if block.
 
   elseif(expression)
 
-See the if command.
+See the :command:`if` command.

Help/command/enable_language.rst

@@ -18,5 +18,5 @@ targets using the named language directly for compiling sources or
 indirectly through link dependencies.  It is simplest to enable all
 needed languages in the top-level directory of a project.
 
-The OPTIONAL keyword is a placeholder for future implementation and
+The ``OPTIONAL`` keyword is a placeholder for future implementation and
 does not currently work.

Help/command/enable_testing.rst

@@ -7,7 +7,7 @@ Enable testing for current directory and below.
 
   enable_testing()
 
-Enables testing for this directory and below.  See also the add_test
-command.  Note that ctest expects to find a test file in the build
-directory root.  Therefore, this command should be in the source
-directory root.
+Enables testing for this directory and below.  See also the
+:command:`add_test` command.  Note that ctest expects to find a test file
+in the build directory root.  Therefore, this command should be in the
+source directory root.

Help/command/endforeach.rst

 endforeach
 ----------
 
-Ends a list of commands in a FOREACH block.
+Ends a list of commands in a foreach block.
 
 ::
 
   endforeach(expression)
 
-See the FOREACH command.
+See the :command:`foreach` command.

Help/command/endfunction.rst

@@ -7,4 +7,4 @@ Ends a list of commands in a function block.
 
   endfunction(expression)
 
-See the function command.
+See the :command:`function` command.

Help/command/endif.rst

@@ -7,4 +7,4 @@ Ends a list of commands in an if block.
 
   endif(expression)
 
-See the if command.
+See the :command:`if` command.

Help/command/endmacro.rst

@@ -7,4 +7,4 @@ Ends a list of commands in a macro block.
 
   endmacro(expression)
 
-See the macro command.
+See the :command:`macro` command.

Help/command/endwhile.rst

@@ -7,4 +7,4 @@ Ends a list of commands in a while block.
 
   endwhile(expression)
 
-See the while command.
+See the :command:`while` command.

Help/command/exec_program.rst

 exec_program
 ------------
 
-Deprecated.  Use the execute_process() command instead.
+Deprecated.  Use the :command:`execute_process` command instead.
 
 Run an executable program during the processing of the CMakeList.txt
 file.
@@ -15,10 +15,10 @@ file.
 
 The executable is run in the optionally specified directory.  The
 executable can include arguments if it is double quoted, but it is
-better to use the optional ARGS argument to specify arguments to the
+better to use the optional ``ARGS`` argument to specify arguments to the
 program.  This is because cmake will then be able to escape spaces in
-the executable path.  An optional argument OUTPUT_VARIABLE specifies a
+the executable path.  An optional argument ``OUTPUT_VARIABLE`` specifies a
 variable in which to store the output.  To capture the return value of
-the execution, provide a RETURN_VALUE.  If OUTPUT_VARIABLE is
+the execution, provide a ``RETURN_VALUE``.  If ``OUTPUT_VARIABLE`` is
 specified, then no output will go to the stdout/stderr of the console
 running cmake.

Help/command/execute_process.rst

@@ -26,7 +26,7 @@ A single standard error pipe is used for all processes.
 
 Options:
 
-COMMAND
+``COMMAND``
  A child process command line.
 
  CMake executes the child process using operating system APIs directly.
@@ -36,31 +36,31 @@ COMMAND
  (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
  redirect stdin, stdout, and stderr.)
 
-WORKING_DIRECTORY
+``WORKING_DIRECTORY``
  The named directory will be set as the current working directory of
  the child processes.
 
-TIMEOUT
+``TIMEOUT``
  The child processes will be terminated if they do not finish in the
  specified number of seconds (fractions are allowed).
 
-RESULT_VARIABLE
+``RESULT_VARIABLE``
  The variable will be set to contain the result of running the processes.
  This will be an integer return code from the last child or a string
  describing an error condition.
 
-OUTPUT_VARIABLE, ERROR_VARIABLE
+``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
  The variable named will be set with the contents of the standard output
  and standard error pipes, respectively.  If the same variable is named
  for both pipes their output will be merged in the order produced.
 
-INPUT_FILE, OUTPUT_FILE, ERROR_FILE
+``INPUT_FILE, OUTPUT_FILE``, ``ERROR_FILE``
  The file named will be attached to the standard input of the first
  process, standard output of the last process, or standard error of
  all processes, respectively.  If the same file is named for both
  output and error then it will be used for both.
 
-OUTPUT_QUIET, ERROR_QUIET
+``OUTPUT_QUIET``, ``ERROR_QUIET``
  The standard output or standard error results will be quietly ignored.
 
 If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the