Help: Revise and format 'add_custom_target' docs

Format the reStructuredText markup manually.  Organize the command
options into a definition list.  Use inline markup to cross-reference
related documents.

1 files changed, 64 insertions, 29 deletions

diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index 1bf70bf..4f8e190 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -13,33 +13,68 @@ Add a target with no output so it will always be built.
                     [SOURCES src1 [src2...]])
 
 Adds a target with the given name that executes the given commands.
-The target has no output file and is ALWAYS CONSIDERED OUT OF DATE
+The target has no output file and is *always considered out of date*
 even if the commands try to create a file with the name of the target.
-Use ADD_CUSTOM_COMMAND to generate a file with dependencies.  By
-default nothing depends on the custom target.  Use ADD_DEPENDENCIES to
-add dependencies to or from other targets.  If the ALL option is
-specified it indicates that this target should be added to the default
-build target so that it will be run every time (the command cannot be
-called ALL).  The command and arguments are optional and if not
-specified an empty target will be created.  If WORKING_DIRECTORY is
-set, then the command will be run in that directory.  If it is a
-relative path it will be interpreted relative to the build tree
-directory corresponding to the current source directory.  If COMMENT
-is set, the value will be displayed as a message before the commands
-are executed at build time.  Dependencies listed with the DEPENDS
-argument may reference files and outputs of custom commands created
-with add_custom_command() in the same directory (CMakeLists.txt file).
-
-If VERBATIM is given then all arguments to the commands will be
-escaped properly for the build tool so that the invoked command
-receives each argument unchanged.  Note that one level of escapes is
-still used by the CMake language processor before add_custom_target
-even sees the arguments.  Use of VERBATIM is recommended as it enables
-correct behavior.  When VERBATIM is not given the behavior is platform
-specific because there is no protection of tool-specific special
-characters.
-
-The SOURCES option specifies additional source files to be included in
-the custom target.  Specified source files will be added to IDE
-project files for convenience in editing even if they have not build
-rules.
+Use the :command:`add_custom_command` command to generate a file with
+dependencies.  By default nothing depends on the custom target.  Use
+the :command:`add_dependencies` command to add dependencies to or
+from other targets.
+
+The options are:
+
+``ALL``
+  Indicate that this target should be added to the default build
+  target so that it will be run every time (the command cannot be
+  called ``ALL``).
+
+``COMMAND``
+  Specify the command-line(s) to execute at build time.
+  If more than one ``COMMAND`` is specified they will be executed in order,
+  but *not* necessarily composed into a stateful shell or batch script.
+  (To run a full script, use the :command:`configure_file` command or the
+  :command:`file(GENERATE)` command to create it, and then specify
+  a ``COMMAND`` to launch it.)
+
+  If ``COMMAND`` specifies an executable target (created by the
+  :command:`add_executable` command) it will automatically be replaced
+  by the location of the executable created at build time.
+  Additionally a target-level dependency will be added so that the
+  executable target will be built before this custom target.
+
+  Arguments to ``COMMAND`` may use
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+  References to target names in generator expressions imply target-level
+  dependencies.
+
+  The command and arguments are optional and if not specified an empty
+  target will be created.
+
+``COMMENT``
+  Display the given message before the commands are executed at
+  build time.
+
+``DEPENDS``
+  Reference files and outputs of custom commands created with
+  :command:`add_custom_command` command calls in the same directory
+  (``CMakeLists.txt`` file).  They will be brought up to date when
+  the target is built.
+
+``SOURCES``
+  Specify additional source files to be included in the custom target.
+  Specified source files will be added to IDE project files for
+  convenience in editing even if they have no build rules.
+
+``VERBATIM``
+  All arguments to the commands will be escaped properly for the
+  build tool so that the invoked command receives each argument
+  unchanged.  Note that one level of escapes is still used by the
+  CMake language processor before ``add_custom_target`` even sees
+  the arguments.  Use of ``VERBATIM`` is recommended as it enables
+  correct behavior.  When ``VERBATIM`` is not given the behavior
+  is platform specific because there is no protection of
+  tool-specific special characters.
+
+``WORKING_DIRECTORY``
+  Execute the command with the given current working directory.
+  If it is a relative path it will be interpreted relative to the
+  build tree directory corresponding to the current source directory.