treewide: write better docstrings for tor-browser things

4 files changed, 29 insertions, 9 deletions

diff --git a/pkgs/applications/networking/browsers/tor-browser-bundle-bin/default.nix b/pkgs/applications/networking/browsers/tor-browser-bundle-bin/default.nix
index de676670913..8d8c1bc979c 100644
--- a/pkgs/applications/networking/browsers/tor-browser-bundle-bin/default.nix
+++ b/pkgs/applications/networking/browsers/tor-browser-bundle-bin/default.nix
@@ -51,6 +51,9 @@
 
 # Extra preferences
 , extraPrefs ? ""
+
+# For meta
+, tor-browser-bundle
 }:
 
 with stdenv.lib;
@@ -397,7 +400,8 @@ stdenv.mkDerivation rec {
   '';
 
   meta = with stdenv.lib; {
-    description = "Tor Browser Bundle";
+    description = "Tor Browser Bundle built by torproject.org";
+    longDescription = tor-browser-bundle.meta.longDescription;
     homepage = https://www.torproject.org/;
     platforms = attrNames srcs;
     maintainers = with maintainers; [ offline matejc doublec thoughtpolice joachifm ];
diff --git a/pkgs/applications/networking/browsers/tor-browser-bundle/default.nix b/pkgs/applications/networking/browsers/tor-browser-bundle/default.nix
index 50b992253ce..6ce22e16415 100644
--- a/pkgs/applications/networking/browsers/tor-browser-bundle/default.nix
+++ b/pkgs/applications/networking/browsers/tor-browser-bundle/default.nix
@@ -339,7 +339,29 @@ stdenv.mkDerivation rec {
 
   passthru.execdir = "/bin";
   meta = with stdenv.lib; {
-    description = "An unofficial version of the tor browser bundle, built from source";
+    description = "An unofficial version of the Tor Browser Bundle, built from source";
+    longDescription = ''
+      Tor Browser Bundle is a bundle of the Tor daemon, Tor Browser (heavily patched version of
+      Firefox), several essential extensions for Tor Browser, and some tools that glue those
+      together with a convenient UI.
+
+      `tor-browser-bundle-bin` package is the official version built by torproject.org patched with
+      `patchelf` to work under nix and with bundled scripts adapted to the read-only nature of
+      the `/nix/store`.
+
+      `tor-browser-bundle` package is the version built completely from source. It reuses the `tor`
+      package for the tor daemon, `firefoxPackages.tor-browser` package for the tor-browser, and
+      builds all the extensions from source.
+
+      Note that `tor-browser-bundle` package is not only built from source, but also bundles Tor
+      Browser differently from the official `tor-browser-bundle-bin` implementation. The official
+      Tor Browser is not a normal UNIX program and is heavily patched for its use in the Tor Browser
+      Bundle (which `tor-browser-bundle-bin` package then has to work around for the read-only
+      /nix/store). Meanwhile, `firefoxPackages.tor-browser` reverts all those patches, allowing
+      `firefoxPackages.tor-browser` to be used independently of the bundle, and then implements what
+      `tor-browser-bundle` needs for the bundling using a much simpler patch. See the
+      longDescription and expression of the `firefoxPackages.tor-browser` package for more info.
+    '';
     homepage = https://torproject.org/;
     license = licenses.free;
     platforms = [ "x86_64-linux" ];
diff --git a/pkgs/top-level/aliases.nix b/pkgs/top-level/aliases.nix
index 634a3e4c17e..34260652649 100644
--- a/pkgs/top-level/aliases.nix
+++ b/pkgs/top-level/aliases.nix
@@ -278,6 +278,7 @@ mapAliases ({
   tex-gyre-schola-math = tex-gyre-math.schola; # added 2018-04-03
   tex-gyre-termes-math = tex-gyre-math.termes; # added 2018-04-03
   tftp_hpa = tftp-hpa; # added 2015-04-03
+  torbrowser = tor-browser-bundle-bin; # added 2017-04-05
   trang = jing-trang; # added 2018-04-25
   transmission_gtk = transmission-gtk; # added 2018-01-06
   transmission_remote_gtk = transmission-remote-gtk; # added 2018-01-06
diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix
index 60147e724ee..e2d4ba27b33 100644
--- a/pkgs/top-level/all-packages.nix
+++ b/pkgs/top-level/all-packages.nix
@@ -5562,13 +5562,6 @@ with pkgs;
 
   tor-arm = callPackage ../tools/security/tor/tor-arm.nix { };
 
-  # added 2017-04-05
-  torbrowser = /* builtins.trace ''
-    WARNING: torbrowser package was renamed to tor-browser-bundle-bin.
-
-    Also, consider using nix-built tor-browser-unwrapped package instead. Read its longDescription.
-  '' */ tor-browser-bundle-bin;
-
   tor-browser-bundle-bin = callPackage ../applications/networking/browsers/tor-browser-bundle-bin { };
 
   tor-browser-bundle = callPackage ../applications/networking/browsers/tor-browser-bundle {