Update documentation and arduino debug options (#8837)

* Update documentation

Describe how to improve Exception Decoder results.

Updated build option details.

* Added d-a-v's code. And updated description and debug macro.

* Update doc

Updated platform.txt - positioned -Os such that it can be overridden by `build.opt`.

Add suggestion of using `-Og` which may improve the Decoder's line number correlation
with the problem in the source code.

Untested adjustments to platformio-build.py

* Fixed code formatting

* Fixed example

Previously `-O3` in the example had no effect. It was overridden by later flags.
Reording the `-Os` allowed changing optimization to  work. Somehow this triggered
a new warning "Stream.h:50:7: warning: 'f.Stream::_startMillis' may be used
uninitialized in this function". Replaced `-O3` with `-Og`.

* Proposed "Debug port" menu change
Preserves a pathway for `build.opt` override.

* Update boards.txt.py and docs - WIP

* Improve organization of optimization content.
Use "Debug Optimization" for menu name.
The menu item defines the initial optimization.
platform.txt - optimization parameter can be overridden by build.opt.

* Add fallback value for build.debug_optim to platform.txt

* update text and undo changes to platformio-build.py

* tweak text

* Added ':orphan:' mark to a06-global-build-options.rst

* Update doc. Added link in page index to 'Improving Exception Decoder Results'

* Update text to reference PR#8868 improvements for leaf function.

tools/boards.txt.py

@@ -1045,6 +1045,7 @@ macros = {
         ( '.build.core', 'esp8266' ),
         ( '.build.variant', 'generic' ),
         ( '.build.spiffs_pagesize', '256' ),
+        ( '.build.debug_optim', '' ),
         ( '.build.debug_port', '' ),
         ( '.build.debug_level', '' ),
         ]),
@@ -1360,6 +1361,12 @@ def all_debug ():
             ( '.menu.dbg.Serial1.build.debug_port', '-DDEBUG_ESP_PORT=Serial1' ),
             ( '.menu.lvl.None____', 'None' ),
             ( '.menu.lvl.None____.build.debug_level', '' ),
+            ( '.menu.optim.Smallest', 'None' ),
+            ( '.menu.optim.Smallest.build.debug_optim', '-Os' ),
+            ( '.menu.optim.Lite', 'Lite' ),
+            ( '.menu.optim.Lite.build.debug_optim', '-Os -fno-optimize-sibling-calls' ),
+            ( '.menu.optim.Full', 'Optimum' ),
+            ( '.menu.optim.Full.build.debug_optim', '-Og' ),
         ])
 
     for optlist in options:
@@ -1740,6 +1747,7 @@ def all_boards ():
     print('menu.ResetMethod=Reset Method')
     print('menu.dbg=Debug port')
     print('menu.lvl=Debug Level')
+    print('menu.optim=Debug Optimization')
     print('menu.ip=lwIP Variant')
     print('menu.vt=VTables')
     print('menu.exception=C++ Exceptions')