1 files changed, 52 insertions, 0 deletions

diff --git a/htdocs/exceptions/index.chtml b/htdocs/exceptions/index.chtml
new file mode 100644
index 0000000..cc0ed8a
--- a/dev/null
+++ b/htdocs/exceptions/index.chtml
@@ -0,0 +1,52 @@
+% html(); return; /* vim:set ft=sitecing: */
+%%derive layout = "/ancestry/layout.chtml";
+<%codemethod string title() %>
+ return "exceptions handling";
+</%codemethod>
+<%method void content() %>
+ <h1>site-C-ing exception handling</h1>
+ <p>
+  The purpose of this section is to give an overview of the <em>site-C-ing</em>
+  exception handling mechanism. Before the web visitor can see the page each
+  site-C-ing component goes through a few stages, namely, preprocessing,
+  compiling and execution. Having three stages to go through also means the
+  stages one can fail to go through and three exciting opportunities to handle
+  different errors.
+ </p>
+ <p>
+  First each component is preprocessed so that you can feed the valid c++ code
+  to the compiler. Here is where the preprocessor can choke at your broken
+  source code. Once preprocessor failes to parse your code it will throw an
+  exception which <em>site-C-ing</em> will catch and pass to <a
+  href="/sources/htdocs/handlers/exception_dev" title="development mode
+  exception handler source">the exception handler component</a>. Want to <a
+  href="/exceptions/preprocess">read more</a> about preprocessor exception
+  handling?
+ </p>
+ <p>
+  After the preprocessing stage is over we have a great opportunity to catch
+  the compile-time errors. After <em>site-C-ing</em> fails to compile the
+  component it throws another exception and passes it to the same handler which
+  may show you some information on what's gone wrong with your source code from
+  the compiler's perspective. If you've gone this far you definitely want to <a
+  href="/exceptions/compile">read more</a> about the compiler error handling.
+ </p>
+ <p class="note">
+  Note, that it is likely that you will want to disable the steps above for the
+  production environment to save time on unnecessary checking whether the
+  component is up to date.
+ </p>
+ <p>
+  Finally, we need to execute the component and present its output to the web
+  site visitor. This is also where things may go wrong and here is where your
+  component may throw an exception for the engine to catch and pass to the
+  handler. Feel free to <a href="/exceptions/runtime">learn more</a> about it
+  as well.
+ </p>
+ <p class="note">
+  One more thing you will likely want to have differently in production
+  environment is <a href="/sources/htdocs/handlers/exception_prod"
+  title="production mode exception handler source">an exception handler</a>
+  which will not give out that much unnecessary information to the user.
+ </p>
+</%method>