improve CONTRIBUTING.md

CONTRIBUTING.md

@@ -13,22 +13,21 @@ To effectively work on the project the following tools are required:
 
 * `Git`
 * `Node.js` or another npm client
-* an IDE capable of working with JavaScript, TypeScript and CSS. `VS Code` is one option.
+* an IDE capable of working with JavaScript, TypeScript and CSS. [VS Code](https://code.visualstudio.com/) is one option.
 * Java Runtime Environment, minimum JRE8
 
 ### Setting everything up
 
 0. Clone the project from GitGud.io ([Detailed Git setup and work cycle](devNotes/gitSetup.md))
-1. Open a terminal (GNU/Linux) / cmd/Powershell window (Windows) and then navigate to the `fc-pregmod`
- root directory via `cd PATH`. e.g. 
- Windows: `cd C:\path\to\project\fc-pregmod`
- GNU/Linux: `cd /path/to/project/fc-pregmod/`
-
+1. Navigate to the `fc-pregmod` root directory.
+   * Windows: Open the cmd/Powershell and execute `cd C:\path\to\project\fc-pregmod`
+   * GNU/Linux: Open a terminal and execute `cd /path/to/project/fc-pregmod/`.
 2. Run `npm install`
 3. Open the directory in your preferred IDE
 4. Configure your IDE to use ESLint.
-5. It might also be worth installing the following extensions if using VS Code:
- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) and [GitLens — Git supercharged](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens).
+5. Recommended extensions for VSCode:
+   * [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) 
+   * [GitLens — Git supercharged](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens).
 
 ## Compiling
 
@@ -139,7 +138,7 @@ const foo = {
 .FOO-BAR {}
 ```
 
-New code should generally get organized into the `App` namespace. See `js/002-config/fc-init-js.js` for a rough outline.
+New code should generally get organized into the `App` namespace. See [fc-js-init.js](js/002-config/fc-js-init.js) for a rough outline.
 
 ## JavaScript Features
 
@@ -207,7 +206,7 @@ errors, it's not totally clean as is and there are a few false positives.
   * [Limbs](devNotes/limb functions.md)
   * [Standalone functions](devNotes/standaloneFunctions.md)
   * [Some potentially useful JS functions](devNotes/usefulJSFunctionDocumentation.txt)
-  * [Content embedding chart](devNotes/contentEmbeddingChart.png) (for more details refer to https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616)
+  * [Content embedding chart](devNotes/contentEmbeddingChart.png) (for more details refer to [this issue](https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616))
 
 ## Useful issues
 

devNotes/exceptions.md

-# Proper exception handling
+# JavaScript Exceptions
+
+## Who captures exceptions?
+If we don't catch the error manually, there are three different places where the error ends up being displayed to the
+user. The exact place depends on the context of the executed code. These error messages show roughly the same information.
+
+1. Captured and printed by us: `App.UI.DOM.formatException()`, hides path & shows version information.
+    * Usually code which displays a passage.
+2. Captured and printed by SugarCube: custom modification, hides path & shows version information.
+    * Usually old twine passages
+3. Captured and printed by Browser: Not hiding anything & does not show version information.
+    * Usually callbacks
+
+## Manual exception handling
 
 With the movement away from passages as .tw files error handling is getting more important, especially proper cleanup.
 
-Good example is [this issue](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2654), the end week animation did not stop because `App.EndWeek.slaveAssignmentReport()` failed, which
+A good example is [this issue](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2654), the end week animation did not stop because `App.EndWeek.slaveAssignmentReport()` failed, which
 meant that the endweek animation stop call wasn't executed.
 
-## Finally
+### Finally
 
 Example of the proper way to handle code that cleans up something and should therefore always be executed:
 
@@ -22,7 +35,7 @@ try {
 Do note that this will still propagate the error up, it will just execute `cleanup code` first. If you want to handle
 the error use `catch`
 
-## Catch
+### Catch
 
 If needed a catch clause can be used as well, but it is usually advisable to only catch specific errors and only if you
 know they can be thrown and there is no easy way to prevent them.
@@ -37,6 +50,6 @@ try {
 }
 ```
 
-## Reference
+### Reference
 
 See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch