Help: Revise compile options command docs, and provide example

For add_compile_options and target_compile_options:
- Insert sections.
- Provide cross-links between the two doc pages
- Alleviate and explain links to the commands
  ...compile_definitions and ...include_directories.
- Alleviate link to COMPILE_OPTIONS, and integrate it into
  the synopsis.

1 files changed, 18 insertions, 12 deletions

diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst
index c26c926..47e7d86 100644
--- a/Help/command/target_compile_options.rst
+++ b/Help/command/target_compile_options.rst
@@ -9,22 +9,18 @@ Add compile options to a target.
     <INTERFACE|PUBLIC|PRIVATE> [items1...]
     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
 
-Specifies compile options to use when compiling a given target.  The
-named ``<target>`` must have been created by a command such as
-:command:`add_executable` or :command:`add_library` and must not be an
-:ref:`ALIAS target <Alias Targets>`.
+Adds options to the :prop_tgt:`COMPILE_OPTIONS` or
+:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options
+are used when compiling the given ``<target>``, which must have been
+created by a command such as :command:`add_executable` or
+:command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`.
+
+Arguments
+^^^^^^^^^
 
 If ``BEFORE`` is specified, the content will be prepended to the property
 instead of being appended.
 
-This command can be used to add any options, but
-alternative commands exist to add preprocessor definitions
-(:command:`target_compile_definitions` and :command:`add_compile_definitions`)
-or include directories (:command:`target_include_directories` and
-:command:`include_directories`).  See documentation of the
-:prop_dir:`directory <COMPILE_OPTIONS>` and
-:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
-
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
 specify the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC``
 items will populate the :prop_tgt:`COMPILE_OPTIONS` property of
@@ -40,3 +36,13 @@ manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
 .. include:: OPTIONS_SHELL.txt
+
+See Also
+^^^^^^^^
+
+This command can be used to add any options. However, for adding
+preprocessor definitions and include directories it is recommended
+to use the more specific commands :command:`target_compile_definitions`
+and :command:`target_include_directories`.
+
+For directory-wide settings, there is the command :command:`add_compile_options`.