Updated 3.3 Updater Scripts (markdown)

3.3-Updater-Scripts.md

@@ -24,21 +24,29 @@ uses any and all .js files in a `user.js-overrides` sub-folder as overrides inst
 runs the script without user-input
 - `-updatebatch`
 the updater will auto-update itself on execution
-- `-log`
+- `-log` writes the console output to the logfile `user.js-update-log.txt`
-writes the console output to the logfile `user.js-update-log.txt`
+- `-LogP` works just like `-Log` but also opens the logfile after updating
-- `-LogP`
-works just like `-Log` but also opens the logfile after updating
 
-- `-Merge`
+- `-Merge` merges overrides instead of appending them
-merges overrides instead of appending them. Comments are appended normally. `_user.js.parrot` lines are not merged. Overrides for inactive (commented out) user.js prefs will be appended. When `-Merge` and `-MultiOverrides` are used together, a `user-overrides-merged.js` file is also generated in the root directory for quick reference. It contains only the merged data from override files and can be safely discarded after updating, or used as the new user-overrides.js. When there are conflicting records for the same pref, the value of the last one declared will be used.
+  - `_user.js.parrot` lines are not merged
+  - Comments are appended normally
+  - Overrides for inactive (commented out) user.js prefs will be appended
+  - When `-Merge` and `-MultiOverrides` are used together, a `user-overrides-merged.js` file is also generated in the root directory for quick reference. It contains only the merged data from override files and can be safely discarded after updating, or used as the new user-overrides.js.
+  - When there are conflicting records for the same pref, the value of the last one declared will be used.
+  - **v4.5+ supports commenting-out active user_pref lines** (see example below)
 
 The following example illustrates how `-merge` works:<br><br>
 ghacks user.js file contains this:
 ```js
 /* 0103: set your "home" page (see 0102) ***/
    // user_pref("browser.startup.homepage", "https://www.example.com/");
+
+/* 0510: disable Pocket (FF39+) ***/
+user_pref("extensions.pocket.enabled", false);
+
 /* 1202: control TLS versions with min and max ***/
 user_pref("security.tls.version.max", 4); // 4 = allow up to and including TLS 1.3
+
 /* 2503: disable giving away network info (FF31+) */
 user_pref("dom.netinfo.enabled", false);
 ```
@@ -46,15 +54,22 @@ user-overrides.js:
 ```js
 /*** my user.js overrides ***/
 user_pref("browser.startup.homepage", "https://www.foo.bar/"); // 01xx
-user_pref("security.tls.version.max", 3); // ghacks has 4 (=TLS1.3) but I prefer 3 for now
+user_pref("extensions.pocket.enabled", true); // 0510 - I like Pocket
 user_pref("dom.netinfo.enabled", false); // 25xx - enforcing false
+
+//// --- comment-out --- 'security.tls.version.max' -1202- wait until FF enables TLS1.3 for everyone
 ```
 final user.js after update + merging:
 ```js
 /* 0103: set your "home" page (see 0102) ***/
    // user_pref("browser.startup.homepage", "https://www.example.com/");
+
+/* 0510: disable Pocket (FF39+) ***/
+user_pref("extensions.pocket.enabled", true); // 0510 - I like Pocket
+
 /* 1202: control TLS versions with min and max ***/
-user_pref("security.tls.version.max", 3); // ghacks has 4 (=TLS1.3) but I prefer 3 for now
+//user_pref("security.tls.version.max", 4); // 4 = allow up to and including TLS 1.3
+
 /*** 4600: RFP (4500) ALTERNATIVES [SETUP] ***/
 /* [NOTE] ESR52.x and non-RFP users replace the * with a slash on this line to enable these
 // 4607: [2503] disable giving away network info (FF31+)
@@ -63,11 +78,27 @@ user_pref("dom.netinfo.enabled", false); // 25xx - enforcing false
 
 /*** my user.js overrides ***/
 user_pref("browser.startup.homepage", "https://www.foo.bar/"); // 01xx
-```
 
-With `-merge` it's best to always add a comment behind your overrides to make them easily noticeable when you compare your new user.js with one of your backups. A good way is to use the number of the pref's section. That will also make it easier to spot when a pref you want to override gets moved to a commented-out section like `9999: DEPRECATED` or `4600: RFP ALTERNATIVES`, resulting in your override becoming inactive, which may or may not be what you want. (see `dom.netinfo.enabled` in the example) If that's not what you want, you can prepend the `dom.netinfo.enabled` line with a TAB or JS multi-line-comment (or in v4.0 one or more spaces also works), like this:
+//// --- comment-out --- 'security.tls.version.max' -1202- wait until FF enables TLS1.3 for everyone
+```
+a couple things to note here:
+* 0103 was not merged because it's inactive in the user.js. Instead the override was appended at the bottom.
+* 0510 was merged with the override, including the comment from the overrides file.
+* 1202 was commented out and the original value and comment are kept intact
+* the netinfo line was merged but the pref has been moved to 4600 in the updated user.js (see info below)
+* the special comment-out command was also appended at the bottom as a reminder that you gave that command
+
+With `-merge` it's best to always add a comment behind your overrides to make them easily noticeable when you compare your new user.js with one of your backups. A good way is to use the number of the pref's section. That will also make it easier to spot when a pref you want to override gets moved to a commented-out section like `9999: DEPRECATED` or `4600: RFP ALTERNATIVES`, resulting in your override becoming inactive, which may or may not be what you want. (see `dom.netinfo.enabled` in the example) If that's not what you want, you can prepend the `dom.netinfo.enabled` line with a TAB or JS multi-line-comment (or in v4.0+ one or more spaces also works), like this:
 ```js
     user_pref("dom.netinfo.enabled", false); // 25xx - enforcing false -- prepended with a TAB
 /* !!! */ user_pref("dom.netinfo.enabled", false); // 25xx - enforcing false -- or a JS-multi-line comment
  user_pref("dom.netinfo.enabled", false); // 25xx - enforcing false -- for v4.0 space(s) also works
 ```
+
+If you want the `-merge` function to comment out an active user_pref line you have to use this **exact** format:
+```js
+//// --- comment-out --- 'prefname.goes.here'
+```
+Anything after the closing single-quote is optional and can be used for comments/reminders. (see example above)
+
+