Help: Revise and format 'add_custom_command' docs

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

Help/command/add_custom_command.rst

@@ -3,10 +3,12 @@ add_custom_command
 
 Add a custom build rule to the generated build system.
 
-There are two main signatures for add_custom_command The first
-signature is for adding a custom command to produce an output.
+There are two main signatures for ``add_custom_command``.
 
-::
+Generating Files
+^^^^^^^^^^^^^^^^
+
+The first signature is for adding a custom command to produce an output::
 
   add_custom_command(OUTPUT output1 [output2 ...]
                      COMMAND command1 [ARGS] [args1...]
@@ -18,28 +20,117 @@ signature is for adding a custom command to produce an output.
                      [WORKING_DIRECTORY dir]
                      [COMMENT comment] [VERBATIM] [APPEND])
 
-This defines a command to generate specified OUTPUT file(s).  A target
-created in the same directory (CMakeLists.txt file) that specifies any
-output of the custom command as a source file is given a rule to
-generate the file using the command at build time.  Do not list the
-output in more than one independent target that may build in parallel
-or the two instances of the rule may conflict (instead use
-add_custom_target to drive the command and make the other targets
-depend on that one).  If an output name is a relative path it will be
-interpreted relative to the build tree directory corresponding to the
-current source directory.  Note that MAIN_DEPENDENCY is completely
-optional and is used as a suggestion to visual studio about where to
-hang the custom command.  In makefile terms this creates a new target
-in the following form:
-
-::
+This defines a command to generate specified ``OUTPUT`` file(s).
+A target created in the same directory (``CMakeLists.txt`` file)
+that specifies any output of the custom command as a source file
+is given a rule to generate the file using the command at build time.
+Do not list the output in more than one independent target that
+may build in parallel or the two instances of the rule may conflict
+(instead use the :command:`add_custom_target` command to drive the
+command and make the other targets depend on that one).
+In makefile terms this creates a new target in the following form::
 
   OUTPUT: MAIN_DEPENDENCY DEPENDS
           COMMAND
 
-If more than one command is specified they will be executed in order.
-The optional ARGS argument is for backward compatibility and will be
-ignored.
+The options are:
+
+``APPEND``
+  Append the ``COMMAND`` and ``DEPENDS`` option values to the custom
+  command for the first output specified.  There must have already
+  been a previous call to this command with the same output.
+  The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
+  options are currently ignored when APPEND is given, but may be
+  used in the future.
+
+``COMMAND``
+  Specify the command-line(s) to execute at build time.
+  If more than one command is specified they will be executed in order.
+  The optional ``ARGS`` argument is for backward compatibility and
+  will be ignored.
+
+  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 any target using this custom
+  command.  However this does NOT add a file-level dependency that
+  would cause the custom command to re-run whenever the executable is
+  recompiled.
+
+  Arguments to ``COMMAND`` may use
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+  References to target names in generator expressions imply target-level
+  dependencies, but NOT file-level dependencies.  List target names with
+  the ``DEPENDS`` option to add file-level dependencies.
+
+``COMMENT``
+  Display the given message before the commands are executed at
+  build time.
+
+``DEPENDS``
+  Specify files on which the command depends.  If any dependency is
+  an ``OUTPUT`` of another custom command in the same directory
+  (``CMakeLists.txt`` file) CMake automatically brings the other
+  custom command into the target in which this command is built.
+  If ``DEPENDS`` is not specified the command will run whenever
+  the ``OUTPUT`` is missing; if the command does not actually
+  create the ``OUTPUT`` then the rule will always run.
+  If ``DEPENDS`` specifies any target (created by the
+  :command:`add_custom_target`, :command:`add_executable`, or
+  :command:`add_library` command) a target-level dependency is
+  created to make sure the target is built before any target
+  using this custom command.  Additionally, if the target is an
+  executable or library a file-level dependency is created to
+  cause the custom command to re-run whenever the target is
+  recompiled.
+
+  Arguments to ``DEPENDS`` may use
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+``IMPLICIT_DEPENDS``
+  Request scanning of implicit dependencies of an input file.
+  The language given specifies the programming language whose
+  corresponding dependency scanner should be used.
+  Currently only ``C`` and ``CXX`` language scanners are supported.
+  The language has to be specified for every file in the
+  ``IMPLICIT_DEPENDS`` list.  Dependencies discovered from the
+  scanning are added to those of the custom command at build time.
+  Note that the ``IMPLICIT_DEPENDS`` option is currently supported
+  only for Makefile generators and will be ignored by other generators.
+
+``MAIN_DEPENDENCY``
+  Specify the primary input source file to the command.  This is
+  treated just like any value given to the ``DEPENDS`` option
+  but also suggests to Visual Studio generators where to hang
+  the custom command.
+
+``OUTPUT``
+  Specify the output files the command is expected to produce.
+  If an output name is a relative path it will be interpreted
+  relative to the build tree directory corresponding to the
+  current source directory.
+  If the output of the custom command is not actually created
+  as a file on disk it should be marked with the :prop_sf:`SYMBOLIC`
+  source file property.
+
+``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_command 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.
+
+Build Events
+^^^^^^^^^^^^
 
 The second signature adds a custom command to a target such as a
 library or executable.  This is useful for performing an operation
@@ -60,79 +151,13 @@ This defines a new command that will be associated with building the
 specified target.  When the command will happen is determined by which
 of the following is specified:
 
-::
-
-  PRE_BUILD - run before all other dependencies
-  PRE_LINK - run after other dependencies
-  POST_BUILD - run after the target has been built
-
-Note that the PRE_BUILD option is only supported on Visual Studio 7 or
-later.  For all other generators PRE_BUILD will be treated as
-PRE_LINK.
-
-If WORKING_DIRECTORY is specified the command will be executed in the
-directory given.  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.  If APPEND is
-specified the COMMAND and DEPENDS option values are appended to the
-custom command for the first output specified.  There must have
-already been a previous call to this command with the same output.
-The COMMENT, WORKING_DIRECTORY, and MAIN_DEPENDENCY options are
-currently ignored when APPEND is given, but may be used in the future.
-
-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_command
-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.
-
-If the output of the custom command is not actually created as a file
-on disk it should be marked as SYMBOLIC with
-SET_SOURCE_FILES_PROPERTIES.
-
-The IMPLICIT_DEPENDS option requests scanning of implicit dependencies
-of an input file.  The language given specifies the programming
-language whose corresponding dependency scanner should be used.
-Currently only C and CXX language scanners are supported.  The
-language has to be specified for every file in the IMPLICIT_DEPENDS
-list.  Dependencies discovered from the scanning are added to those of
-the custom command at build time.  Note that the IMPLICIT_DEPENDS
-option is currently supported only for Makefile generators and will be
-ignored by other generators.
-
-If COMMAND specifies an executable target (created by ADD_EXECUTABLE)
-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 any target
-using this custom command.  However this does NOT add a file-level
-dependency that would cause the custom command to re-run whenever the
-executable is recompiled.
-
-Arguments to COMMAND may use "generator expressions" with the syntax
-``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual for
-available expressions.
-
-References to target names in generator expressions imply target-level
-dependencies, but NOT file-level dependencies.  List target names with
-the DEPENDS option to add file dependencies.
-
-The DEPENDS option specifies files on which the command depends.  If
-any dependency is an OUTPUT of another custom command in the same
-directory (CMakeLists.txt file) CMake automatically brings the other
-custom command into the target in which this command is built.  If
-DEPENDS is not specified the command will run whenever the OUTPUT is
-missing; if the command does not actually create the OUTPUT then the
-rule will always run.  If DEPENDS specifies any target (created by an
-ADD_* command) a target-level dependency is created to make sure the
-target is built before any target using this custom command.
-Additionally, if the target is an executable or library a file-level
-dependency is created to cause the custom command to re-run whenever
-the target is recompiled.
-
-Arguments to ``DEPENDS`` may use "generator expressions" with the syntax
-``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual for
-available expressions.
+``PRE_BUILD``
+  Run before any other rules are executed within the target.
+  This is supported only on Visual Studio 7 or later.
+  For all other generators ``PRE_BUILD`` will be treated as
+  ``PRE_LINK``.
+``PRE_LINK``
+  Run after sources have been compiled but before linking the binary
+  or running the librarian or archiver tool of a static library.
+``POST_BUILD``
+  Run after all other rules within the target have been executed.