rework the docs

1 files changed, 27 insertions, 14 deletions

diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml
index efec64f37..ec09d35f1 100644
--- a/SCons/Script/Main.xml
+++ b/SCons/Script/Main.xml
@@ -959,18 +959,6 @@ SetOption('max_drift', 0)
                 or defined by calls to &f-link-AddOption;.
             </para>
             <para>
-                If there are any command line options not defined.
-                Calling this function will cause SCons to issue an error message and then exit with an error exit
-                status.
-            </para>
-            <para>
-                If optional <parameter>throw_exception</parameter> is True, &f-ValidateOptions; will raise a
-                <exceptionname>SConsBadOptionError</exceptionname>
-                exception instead of printing an error message and exiting with an error status.  Then the calling
-                &SConscript; logic can catch that exception and handle invalid options itself.
-            </para>
-
-            <para>
                 This function should only be called after the last &f-link-AddOption; call in your &SConscript;
                 logic.
             </para>
@@ -978,19 +966,44 @@ SetOption('max_drift', 0)
                 Be aware that some tools call &f-link-AddOption;, if you are getting error messages for arguments
                 that they add, you will need to ensure that you load those tools before you call &f-ValidateOptions;.
             </para>
+            <para>
+                If there are any command line options not defined, calling this function will cause SCons to issue an
+                error message and then exit with an error exit
+                status.</para>
+            <para>If the optional <parameter>throw_exception</parameter> is <literal>True</literal>, &f-ValidateOptions; will raise a
+                <exceptionname>SConsBadOptionError</exceptionname>
+                exception. This would allow the calling
+                &SConscript; logic can catch that exception and handle invalid options itself.
+            </para>
 
             <para>
                 Example:
             </para>
 
-<example_commands>
+            <example_commands>
 try:
     ValidateOptions(throw_exception=True)
 except SConsBadOptionError as e:
     print("Parser is SConsOptionParser:%s" % (isinstance(e.parser, SConsOptionParser)))
     print("Message is :%s" % e.opt_str)
     Exit(3)
-</example_commands>
+            </example_commands>
+            
+            <para>
+                This function is useful to force SCons to fail fast before you execute any expensive logic later in your
+                build logic.
+                For example if you specify build options via any flags, a simple typo could yield the incorrect build
+                option throughout your entire build.
+            </para>
+            <example_commands>
+scons --compilers=mingw (the correct flag is --compiler)
+            </example_commands>
+            <para>
+                Could cause SCons to run configure steps with the incorrect compiler. Costing developer time trying to
+                track down why the configure logic failed with a compiler which should work.
+            </para>
+
+
 
         </summary>
     </scons_function>