[guide] add sections for system properties and exception handler. Fixes

#204. Relates to #202

docs/griffon-guide/src/docs/asciidoc/_links.adoc

@@ -6,6 +6,7 @@
 :link_griffon_artifact: link:api/griffon/core/artifact/GriffonArtifact.html[GriffonArtifact, window="_blank"]
 :link_griffon_mvcartifact: link:api/griffon/core/artifact/GriffonMvcArtifact.html[GriffonMvcArtifact, window="_blank"]
 :link_shutdown_handler: link:api/griffon/core/ShutdownHandler.html[ShutdownHandler, window="_blank"]
+:link_exception_handler: link:api/griffon/core/ExceptionHandler.html[ExceptionHandler, window="_blank"]
 :link_mvc_group: link:api/griffon/core/mvc/MVCGroup.html[MVCGroup, window="_blank"]
 :link_mvc_group_configuration: link:api/griffon/core/mvc/MVCGroupConfiguration.html[MVCGroupConfiguration, window="_blank"]
 :link_mvc_group_manager: link:api/griffon/core/mvc/MVCGroupManager.html[MVCGroupManager, window="_blank"]

docs/griffon-guide/src/docs/asciidoc/appendix/appendix-system-properties.adoc

@@ -0,0 +1,15 @@
+
+[[_appendix_system_properties]]
+= System Properties
+
+The following list summarizes all System properties that the Griffon runtime may use
+
+[options="header"]
+|===
+| Property                        | Chapter
+| `griffon.env`                   | <<_overview_metadata_environment,Overview - Metadata - Application Environment>>
+| `griffon.exception.output`      | <<_overview_exception_handler,Overview - Exception Handler>>
+| `griffon.full.stacktrace`       | <<_overview_exception_handler,Overview - Exception Handler>>
+| `griffon.sanitized.stacktraces` | <<_overview_exception_handler,Overview - Exception Handler>>
+|===
+

docs/griffon-guide/src/docs/asciidoc/index.adoc

@@ -39,6 +39,10 @@ include::appendix/appendix-module-bindings.adoc[]
 [appendix]
 include::appendix/appendix-ast-transformations.adoc[]
 
+:numbered!:
+[appendix]
+include::appendix/appendix-system-properties.adoc[]
+
 :numbered!:
 [appendix]
 include::appendix/appendix-sample-applications.adoc[]

docs/griffon-guide/src/docs/asciidoc/overview/overview-configuration.adoc

@@ -47,6 +47,18 @@ The application's runtime configuration is available through the `configuration`
 of the application instance. This configuration instance is *read-only*; you can't modify
 its contents in any way.
 
+There are 3 configuration keys that control the application's behavior:
+
+[horizontal]
+application.title:: Defines the default title for the application.
+application.startupGroups:: Defines a list of MVC groups to be initialized during the <<_overview_lifecycle_startup,Startup>>
+phase. Refer to the <<_mvc,MVC chapter>> to know more about MVC groups.
+application.autoShutdown:: Controls if the application should shutdown when no windows are visible. Set to `true`by
+default.
+
+Additional configuration keys may be added as you deem fit. Take note that the `mvcGroups` prefix has special meaning.
+Refer to the <<_mvc,MVC chapter>> to know more about the different options available to you.
+
 == Internationalization Support
 
 Configuration files are i18n aware, which means you can append

docs/griffon-guide/src/docs/asciidoc/overview/overview-exception-handler.adoc

@@ -0,0 +1,40 @@
+
+[[_overview_exception_handler]]
+= Exception Handler
+
+Griffon provides a centralized exception management facility: `{link_exception_handler}`. An instance of this type
+ is automatically registered with the application's runtime to react to exceptions that are not caught by the
+application's code. In a sense it works like an uncuaght exception handler that's attached to all threads, including
+the UI thread.
+
+An `ExceptionHandler` has three responsibilities:
+
+ . Filter out stacktraces to reduce the amount of noise.
+ . Output the exception to a log file and/or the console.
+ . Pump events to the application's `{link_event_router}`.
+
+Filtering out stacktraces can be configured by setting a System property named `griffon.full.stacktrace` whose value
+defaults to `false`. This means stacktraces will be filtered by default if no configuration changes are made. Uncaught
+exceptions are automatically logged with an `ERROR` level. You cat set the System property `griffon.exception.output` to
+`true` if you'd like to see the stacktraces forwarded to the console's output. Finally, the System property `griffon.sanitized.stacktraces`
+defines the package patterns used to filter out stractrace lines. The default package patterns used are:
+
+ * `org.codehaus.groovy.`
+ * `org.codehaus.griffon.`
+ * `groovy.`
+ * `java.`
+ * `javax.`
+ * `sun.`
+ * `com.sun.`
+
+The `ExceptionHandler` will trigger the followoing events when an exception occurs.
+[horizontal]
+Uncaught<ShortName>(Throwable t):: Triggered after the `Throwable` has had its stacktraces filtered.
+UncaughtExceptionThrown(Throwable t):: Triggered after the previous event.
+
+For the first event, `<ShortName>` refers to the Throwable's short class name. If an exception of type
+`java.lang.IllegalArgumentException` was caught by the `ExceptionHandler` then the event name would become
+`UncaughtIllegalArgumentException`.
+
+Please refer to the <<_events,Events>> chapter in order to find out how these events may be handled.
+

docs/griffon-guide/src/docs/asciidoc/overview/overview-metadata.adoc

@@ -65,8 +65,8 @@ Values surrounded by `@` are treated as placeholder tokens; their values are det
 for the `griffon` section in the Gradle build file to change these values, which looks like this by default
 
 .build.gradle
-[source, groovy,options="nowrap"]
-[subs="attributes"]
+[source,groovy,options="nowrap"]
+[subs="verbatim,attributes"]
 ----
 griffon {
     disableDependencyResolution = false
@@ -185,6 +185,8 @@ You have the following options to change the environment value if using <<_build
  * specify the value as a project property named `griffonEnv`.
  * specify the value in the `jvmArgs` property of the `run` task.
 
+The value for this type is determined by the `griffon.env` System property.
+
 [[_overview_metadata_griffon_environment]]
 == Griffon Environment
 

docs/griffon-guide/src/docs/asciidoc/overview/overview.adoc

@@ -11,4 +11,5 @@ include::overview-modules.adoc[]
 include::overview-shutdown-handlers.adoc[]
 include::overview-startupargs.adoc[]
 include::overview-context.adoc[]
+include::overview-exception-handler.adoc[]
 :leveloffset: 1

docs/griffon-guide/src/docs/asciidoc/views/views-javafx.adoc

@@ -53,7 +53,7 @@ Where `node` is the root of the hierarchy. Here's an example of 3 actions being
 controls each:
 
 [source, xml]
-[subs="attributes,verbatim"]
+[subs="verbatim,attributes"]
 ----
 <?import griffon.javafx.support.JavaFXUtils?>
 ...
@@ -76,7 +76,7 @@ controls each:
 In contrast this is how the FXML would look if node ids would be set instead
 
 [source, xml]
-[subs="attributes,verbatim"]
+[subs="verbatim,attributes"]
 ----
 ...
 <VBox>