Updated 3.2 Additonal JS Files (markdown)

3.2-Additonal-JS-Files.md

@@ -1,18 +1,22 @@
-:exclamation:  Firefox 58+ no longer supports using `profile/preferences/xxx.js` - [1413413](https://bugzilla.mozilla.org/show_bug.cgi?id=1413413)
-  * It is suggested you keep your `override.js` in `profile/` (rename it `user-override` or something) and keep it up to date as your master copy, and just copy and paste it's contents to the end of the ghacks `user.js` when required
+### :small_orange_diamond: The Issue
 
----
-We make a lot of changes - not just adding and deprecating preferences, or flipping them from active to inactive, or changing their values, but also making descriptions better, syntax tweaks, adding/removing references, and even whole section revamps and re-ordering. Doing a file comparison and re-applying your own changes is time consuming, prone to human error, and not really feasible for most people.
+Keeping track of all **your** changes/additions and keeping up to date with all our changes is hard and problematic. We make a lot of changes - not just adding and deprecating preferences, or flipping them from active to inactive, or changing their values, but also making descriptions better, syntax tweaks, adding/removing references, and even whole section revamps and re-ordering. Doing a file comparison and re-applying your own changes is time consuming, prone to human error, and not really feasible for most people.
 
-:small_orange_diamond: The BEST Way To Update (and not lose your changes)
+### :small_orange_diamond: The Solution
 
-- **You use the ghacks user.js exactly as it is, no changes.**
-  * No need to compare files
-  * Just download and update your `profile/user.js` by replacing it with the new one
-- In a `/profile/preferences/` directory, you can store any preference overrides in a separate `override.js` file (you can use any name except user.js)
-- Follow our easy, succinct [changelogs](https://github.com/ghacksuserjs/ghacks-user.js/search?q=label%3Achangelog&type=Issues&utf8=✓) to discover new items and changes
+Keep your changes in a SEPARATE file (see the example below), and append them to the end of the `user.js` when you update. This simplifies updating the `user.js` (for which we have created some [updater scripts](https://github.com/ghacksuserjs/ghacks-user.js/wiki/3.3-Updater-Scripts) for you). Then all you have to do is follow our easy, succinct [changelogs](https://github.com/ghacksuserjs/ghacks-user.js/search?q=label%3Achangelog&type=Issues&utf8=✓) to discover new items and changes
 
-:small_orange_diamond: Example
+> :small_blue_diamond: `user-override.js` [recommended]
+> 
+> Create a `user-override.js` file in your profile directory. This acts as the master copy of all your tweaks, and our updater scripts will auto append its contents for you to the end of the `user.js`
+
+> :small_blue_diamond: `profile/preferences/*.js` [old method]
+> 
+> Firefox 58+ no longer supports using `profile/preferences/xxx.js` - [1413413](https://bugzilla.mozilla.org/show_bug.cgi?id=1413413). In FF versions where this is supported, there is no need to append the contents to the `user.js` as they are applied last (after `user.js`) on a Firefox startup.
+> 
+> However, you can still use this directory for storing a single, or multiple, *.js files full of your overrides, and our **windows** updater script will still append them to the end of your `user.js`
+
+### :small_orange_diamond: Example
 
 Lets say you don't want to limit fonts and need mathml
 
@@ -28,7 +32,7 @@ user_pref("gfx.downloadable_fonts.woff2.enabled", false);
 user_pref("mathml.disabled", true);
 ```
 
-- In a `profile/preferences/override.js` you override them
+- In a `profile/user-override.js` you override them
 ```js
 /*** MY OVERRIDES ***/
 user_pref("browser.display.use_document_fonts", 1); // 1401
@@ -36,9 +40,9 @@ user_pref("gfx.downloadable_fonts.woff2.enabled", true); //1405
 user_pref("mathml.disabled", false); // 2663
 ```
 
-Firefox will apply the `profile/preferences/*.js` file preferences last. The next time you update the `profile/user.js` and replace it, there is no need for you to edit it, and your existing tweaks are already applied and not lost - from the `profile/preferences/override.js`. Now all you need to do is follow the changelog/deprecated-sticky-issue/commits to see what's new, changed, or deprecated/removed
+The next time you update the `profile/user.js` and replace it, all your have to do is append the contents of your existing tweaks from `profile/user-override.js`. Or if you use our updater scripts, it will do this manual step for you as well.
 
-:small_orange_diamond: Caveats
+### :small_orange_diamond: Caveats
 
 You will need to monitor your small set of overrides due to Firefox changes. Just keep an eye on things is all I'm saying