Merge branch 'docs' into 'main'

docs: update README to better explain the tool, show example output

See merge request sequoia-pgp/missing-dependencies!4

2 files changed, 115 insertions, 10 deletions

diff --git a/README.md b/README.md
index 4a0bad3..cd29047 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,24 @@
 # List dependencies that haven't been packaged
 
+Summary: For a given Rust project (crate), list the Rust dependencies
+(crates) that it depends on, that aren't packaged for a target
+operating system.
+
+## Description
+
 The problem: a Rust project wants to be packaged in various operating
-systems, and want to control the Rust dependencies so that packaging
-is less work. Specifically, they want to know what dependencies are
-not already packaged for the target system.
+systems, and wants to manage its Rust dependencies to mainly be on
+versions of crates that are already packaged. This would make
+packaging is less work.
 
 This tool takes a list of packaged crates and versions and compares a
 Rust crate's dependencies accordingly.
 
 Operating systems such as Debian package dependencies separately, and
-frown upon embedded copies of them. Without going into why they do
-that, it's something projects using Rust have to live with, if they
-want their software packaged for such systems.
+frown upon embedded copies of them, or on downloading dependencies at
+build time. Without going into why they do that, it's something
+projects using Rust have to live with, if they want their software
+packaged for such systems.
 
 Other operating systems don't package dependencies separately. For
 those, a Rust program will just use dependencies from crates.io
@@ -48,11 +55,109 @@ To be run from the source tree of the `missing-dependencies` crate:
 ```sh
 $ ./debian-crate-packages > crates-in-debian
 $ cargo run -- crates-in-debian ~/my/rust/project
-missing-version aho-corasick 0.7.18
-missing-entirely ansi_term
+Table: Packaged version is not what is required
+
+┌───────────────────────┬──────────────────┬──────────────────┐
+│ Crate                 │ Required version │ Packaged version │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ blobby                │ ^0.1             │ 0.3.1            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ block-buffer          │ ^0.7             │ 0.10.2           │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ block-padding         │ ^0.1             │ 0.2.1            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ clap-derive           │ =3.2.17          │ 3.2.15           │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ deunicode             │ ^0.4.0           │ 1.3.1            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ digest                │ ^0.8             │ 0.10.3           │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ generic-array         │ ^0.12            │ 0.14.4           │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ hashbrown             │ ^0.8.1           │ 0.12.1           │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ hyphenation           │ ^0.8.4           │ 0.7.1            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ itertools             │ ^0.8             │ 0.10.3           │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ opaque-debug          │ ^0.2             │ 0.3.0            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ proc-macro-error-attr │ =1.0.4           │ 1.0.3            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ quick-error           │ ^1.0.0           │ 2.0.1            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ remove-dir-all        │ ^0.5             │ 0.7.0            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ serde-derive          │ =1.0.136         │ 1.0.142          │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ sha1-asm              │ ^0.4             │ 0.5.1            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ strsim                │ ^0.10            │ 0.9.3            │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ textwrap              │ ^0.14            │ 0.15.0           │
+├───────────────────────┼──────────────────┼──────────────────┤
+│ value-bag             │ =1.0.0-alpha.8   │ 1.0.0-alpha.9    │
+└───────────────────────┴──────────────────┴──────────────────┘
+
+Table: Required crate is not packaged at all
+
+┌───────────────────────────┬──────────────────┐
+│ Crate                     │ Required version │
+├───────────────────────────┼──────────────────┤
+│ atomic_polyfill           │ ^1               │
+├───────────────────────────┼──────────────────┤
+│ clippy                    │ 0.*              │
+├───────────────────────────┼──────────────────┤
+│ directories_next          │ ^2.0.0           │
+├───────────────────────────┼──────────────────┤
+│ fehler                    │ ^1               │
+├───────────────────────────┼──────────────────┤
+│ fehler_macros             │ ^1.0.0           │
+├───────────────────────────┼──────────────────┤
+│ git_testament             │ ^0.2             │
+├───────────────────────────┼──────────────────┤
+│ git_testament_derive      │ ^0.1.13          │
+├───────────────────────────┼──────────────────┤
+│ ndarray                   │ ^0.14            │
+├───────────────────────────┼──────────────────┤
+│ no_std_compat             │ ^0.4             │
+├───────────────────────────┼──────────────────┤
+│ packed_simd_2             │ ^0.3.7           │
+├───────────────────────────┼──────────────────┤
+│ pandoc                    │ ^0.8.0           │
+├───────────────────────────┼──────────────────┤
+│ pandoc_ast                │ ^0.8             │
+├───────────────────────────┼──────────────────┤
+│ pikchr                    │ ^0.1             │
+├───────────────────────────┼──────────────────┤
+│ roadmap                   │ ^0.4.4           │
+├───────────────────────────┼──────────────────┤
+│ rustc_rayon               │ ^0.3             │
+├───────────────────────────┼──────────────────┤
+│ rustc_std_workspace_alloc │ ^1.0.0           │
+├───────────────────────────┼──────────────────┤
+│ scale_info                │ ^1.0             │
+├───────────────────────────┼──────────────────┤
+│ serde_aux                 │ ^3.0             │
+├───────────────────────────┼──────────────────┤
+│ state                     │ ^0.5             │
+├───────────────────────────┼──────────────────┤
+│ subplot                   │ ^0.4.3           │
+├───────────────────────────┼──────────────────┤
+│ subplot_build             │ ^0.4.0           │
+├───────────────────────────┼──────────────────┤
+│ subplotlib                │ ^0.4.1           │
+├───────────────────────────┼──────────────────┤
+│ subplotlib_derive         │ ^0.4.0           │
+├───────────────────────────┼──────────────────┤
+│ sval                      │ =1.0.0-alpha.5   │
+├───────────────────────────┼──────────────────┤
+│ tempfile_fast             │ ^0.3.1           │
+└───────────────────────────┴──────────────────┘
+ ERROR missing_dependencies > ERROR: there were 44 missing dependencies
 ```
 
-Set `RUST_LOG` to `debug` or `info` to get log messages.
+Set `RUST_LOG` to `debug` or `info` to get more detailed log messages.
 
 
 ## FAQ
diff --git a/report.sh b/report.sh
index aa8ccee..1c3cf35 100755
--- a/report.sh
+++ b/report.sh
@@ -5,5 +5,5 @@ set -euo pipefail
 sq_dir="$1"
 
 ./debian-crate-packages >crates-in-debian
-cargo run -q -- --style=markdown crates-in-debian "$sq_dir" -f crypto-nettle |
+cargo run -q -- --style=markdown --features crypto-nettle crates-in-debian "$sq_dir" |
 	pandoc -H style.css -f markdown /dev/stdin -o problems.html --metadata title="Problems packaging sq for Debian"