Created 2.1 User.js (markdown)

2.1-User.js.md

@@ -0,0 +1,68 @@
+🟩 Previous: [To Arkenfox or Not](https://github.com/arkenfox/user.js/wiki/1.1-to-arkenfox-or-not)
+
+🟥 Summary: **How a user.js works**. To know how to apply arkenfox, read the rest of the wiki
+
+---
+
+Prefs are settings that control Firefox's behavior. Some can be set from the Options interface and all can be found in `about:config`, except for what are called `hidden preferences` which will only show when they are set by the user.
+
+🟪 SYNTAX
+
+A `user.js` file is a javascript file and is text based. It resides in the root directory of a profile, and is used to set preferences for that profile when Firefox starts. You can update the user.js while Firefox is open, it is only ever read when Firefox starts.
+
+Prefs must follow Mozilla's syntax which is `user_pref("prefname", value);`
+ - the pref name must be wrapped in quotation marks
+ - string values must be wrapped in quotation marks
+ - prefs are case sensitive
+ - a semi-colon is required at the end
+
+```js
+user_pref("pref.name.string", "i am a string"); // strings require quote marks
+user_pref("pref.name.boolean", true);
+user_pref("pref.name.integer", 0);
+
+user_pref("pref.name", "value") // this will NOT be applied, it is missing a closing ;
+user_pref("pref.name.integer", "0"); // this will be applied but NOT do anything (type mismatch)
+
+user_pref("browser.startup.page", 0); // this will be applied and actually work
+user_pref("browser.Startup.page", 0); // this will be applied but NOT do anything (incorrect case)
+
+/* this is a
+   multi-line comment
+   user_pref("preference.name", "value")
+   and nothing in it is applied ***/
+
+// two forward slashes indicate a comment
+   // and do not need to be closed at the end
+      // and only apply to the one line from when they are added
+user_pref("preference.name", "value"); // comment starts at //
+
+user_pref("preference.name", "not commented out"); // this is an ACTIVE pref and will be applied
+// user_pref("preference.name", "commented out"); // this is an INACTIVE pref and will NOT be applied
+```
+
+🟪 USAGE
+
+- 🔷 Firefox starts
+   - It reads the ACTIVE prefs in `user.js`, in order, and writes them to `prefs.js`
+      - It ignores INACTIVE prefs, i.e it does not reset them
+      - If a pref already exists in `prefs.js`, it overwrites it
+      - If a pref is listed twice, the last one will be applied last
+      - It may abort parsing the file if it encounters a syntax error, but will still apply any content up to that error
+         - [Not all syntax errors cause parsing to abort](https://blog.mozilla.org/nnethercote/2018/03/09/a-new-preferences-parser-for-firefox/), check the browser console (Ctrl-Shift-J) for errors
+      - It will not abort if you apply a type mismatch, it will actually write that type mismatch into prefs.js (and Firefox will ignore it)
+   -  The user.js is now ignored until the next time Firefox starts
+
+- 🔷 Firefox opens
+   - The contents of prefs.js are used and shown as modified in about:config
+      - If a pref in prefs.js has a type mismatch, then it is ignored and the previous value is retained
+
+- 🔷 about:config
+   - All values stored in prefs.js, even if they are the default value, will be denoted as modified
+   - If you set a value to a modified value, it is stored in prefs.js
+   - If you reset a value to default, it is removed from prefs.js
+   - If you reset a hidden pref to default, the value will be blank, and assuming it is not applied again from a user.js, it will then vanish on the next about:config reload
+
+---
+
+🟩 Next: [Backup](https://github.com/arkenfox/user.js/wiki/2.2-Backup)