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.

Help/command/add_compile_options.rst

@@ -7,15 +7,12 @@ Add options to the compilation of source files.
 
   add_compile_options(<option> ...)
 
-Adds options to the compiler command line for targets in the current
-directory and below that are added after this command is invoked.
-See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and
-:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
+Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property.
+These options are used when compiling targets from the current
+directory and below.
 
-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`).
+Arguments
+^^^^^^^^^
 
 Arguments to ``add_compile_options`` may use "generator expressions" with
 the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
@@ -23,3 +20,29 @@ manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
 .. include:: OPTIONS_SHELL.txt
+
+Example
+^^^^^^^
+
+Since different compilers support different options, a typical use of
+this command is in a compiler-specific conditional clause:
+
+.. code-block:: cmake
+
+  if (MSVC)
+      # warning level 4 and all warnings as errors
+      add_compile_options(/W4 /WX)
+  else()
+      # lots of warnings and all warnings as errors
+      add_compile_options(-Wall -Wextra -pedantic -Werror)
+  endif()
+
+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:`add_compile_definitions`
+and :command:`include_directories`.
+
+The command :command:`target_compile_options` adds target-specific options.

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`.