documentation: Add documentation for auto-xz

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 <!-- markdownlint-disable MD024 -->
 
+## [Unreleased] (date goes here)
+
+### Added
+
+- Downloads now default to using tarballs compressed by xz, rather than tarballs compressed by gzip. Includes system/feature detection, which is used to guess if xz can be decompressed by the current user, and if xz compression is available for the desired version of Node. (Enabled only for Node 4.x and greater for KISS reaons). ([#606] [#607])
+  - Export any value of `N_USE_XZ` (other than `0`), including setting it to be null or empty, to enable xz-compressed tarballs, overriding whatever the default behavior may be.
+  - (Unset `N_USE_XZ` entirely in order to return `n` to its default behavior.)
+
+### Changed
+
+- Exporting the environment variable `N_USE_XZ` as `0` will now have the effect of _disabling_ the use of tarballs compressed with xz, rather than enabling it. (Previously, exporting `N_USE_XZ` as any non-zero-length value, including the number `0`, would enable the use of xz-compressed tarballs.)
+
 ## [6.1.3] (2019-11-23)
 
 ### Added
@@ -235,6 +247,8 @@ Only minor functional changes, but technically could break scripts relying on sp
 [#588]: https://github.com/tj/n/issues/588
 [#590]: https://github.com/tj/n/issues/590
 [#593]: https://github.com/tj/n/issues/593
+[#606]: https://github.com/tj/n/issues/606
+[#607]: https://github.com/tj/n/issues/607
 
 <!-- reference links for releases -->
 

README.md

@@ -194,9 +194,12 @@ To change the location to say `$HOME/.n`, add lines like the following to your s
     export N_PREFIX=$HOME/.n
     export PATH=$N_PREFIX/bin:$PATH
 
-By default `n` downloads archives from the mirror site which have been compressed with `gzip`. You can switch to using the `xz` compressed archives by defining `N_USE_XZ`.
+By default `n` opportunistically downloads archives from the mirror site which have been compressed with `xz`, when possible. (This requires that the archive is new enough to be available with xz compression (Node 4.x or greater), and requires that your system supports extracting xz-compressed archives with `tar`. Otherwise, `n` falls back to using `gzip`-compressed archives.) You can override the default behavior by defining `N_USE_XZ`, as follows:
 
-    export N_USE_XZ=true
+    export N_USE_XZ=0; // Disables the use of xz compressed archives
+    export N_USE_XZ=true; // Enables the use of xz compressed archives
+
+Any exported value of `N_USE_XZ` (including null or empty) other than `0` will tell `n` to prefer xz-compressed archives over gzip-compressed archives, and will explicitly override the default behavior. Note: Setting `N_USE_XZ` to `false` will (perhaps suprisingly) tell `n` to prefer the use of xz-compressed archives!
 
 In brief: