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, 31 insertions, 8 deletions

diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst
index fcdcfd4..43805c3 100644
--- a/Help/command/add_compile_options.rst
+++ b/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.