From a595896c5686881a73c6819fbc9b0d1967cfea60 Mon Sep 17 00:00:00 2001
From: Tuomas Tynkkynen <tuomas@tuxera.com>
Date: Thu, 19 Jul 2018 02:31:23 +0300
Subject: [PATCH] diffoscope: Document the script to locate missing optional
 dependencies

And give it it a bit more descriptive name of list-missing-tools.sh.
---
 pkgs/tools/misc/diffoscope/default.nix                        | 4 ++++
 .../misc/diffoscope/{list-tools.sh => list-missing-tools.sh}  | 3 +++
 2 files changed, 7 insertions(+)
 rename pkgs/tools/misc/diffoscope/{list-tools.sh => list-missing-tools.sh} (76%)

diff --git a/pkgs/tools/misc/diffoscope/default.nix b/pkgs/tools/misc/diffoscope/default.nix
index 73b7f2272cd..e55d5c89b5b 100644
--- a/pkgs/tools/misc/diffoscope/default.nix
+++ b/pkgs/tools/misc/diffoscope/default.nix
@@ -6,6 +6,7 @@
 , enableBloat ? false
 }:
 
+# Note: when upgrading this package, please run the list-missing-tools.sh script as described below!
 python3Packages.buildPythonApplication rec {
   name = "diffoscope-${version}";
   version = "99";
@@ -30,6 +31,9 @@ python3Packages.buildPythonApplication rec {
 
   nativeBuildInputs = [ docutils help2man ];
 
+  # Most of the non-Python dependencies here are optional command-line tools for various file-format parsers.
+  # To help figuring out what's missing from the list, run: ./pkgs/tools/misc/diffoscope/list-missing-tools.sh
+  #
   # Still missing these tools: abootimg docx2txt dumpxsb enjarify js-beautify lipo oggDump otool procyon-decompiler Rscript
   # Also these libraries: python3-guestfs
   pythonPath = with python3Packages; [ debian libarchive-c python_magic tlsh rpm ] ++ [
diff --git a/pkgs/tools/misc/diffoscope/list-tools.sh b/pkgs/tools/misc/diffoscope/list-missing-tools.sh
similarity index 76%
rename from pkgs/tools/misc/diffoscope/list-tools.sh
rename to pkgs/tools/misc/diffoscope/list-missing-tools.sh
index 9af7f0e3889..5f4d118cfed 100755
--- a/pkgs/tools/misc/diffoscope/list-tools.sh
+++ b/pkgs/tools/misc/diffoscope/list-missing-tools.sh
@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# This script lists all the optional command-line tools that diffoscope can use
+# (i.e. `diffoscope --list-tools`) but are missing from the Nix expression.
+
 diffoscope=$(nix-build --no-out-link -E 'with import ./. {}; diffoscope.override { enableBloat = true; }')/bin/diffoscope
 
 required=$($diffoscope --list-tools | \