docs: update README

Sponsored-by: pep.foundation

1 files changed, 31 insertions, 7 deletions

diff --git a/README.md b/README.md
index 3b768b6..4a0bad3 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,22 @@
 # List dependencies that haven't been packaged
 
-The problems: a Rust project wants to be packaged in various operating
+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. This tool takes a list of packaged crates and versions
-and compares a Rust crate's dependencies accordingly.
+is less work. Specifically, they want to know what dependencies are
+not already packaged for the target system.
+
+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.
 
+Other operating systems don't package dependencies separately. For
+those, a Rust program will just use dependencies from crates.io
+directly.
+
 This repository contains tooling to make it easier to see what Rust
 dependencies (crates) are missing from a target operating system.
 There are two parts:
@@ -17,8 +24,9 @@ There are two parts:
 * `debian-crate-packages` is a simple shell script that fetches the
   package list for the Debian "unstable" version, and produces a list
   of Rust crates and versions that have been packaged.
-* The Rust program in this crate reads the outputs of the two scripts
-  and produces a list of missing crates or versions.
+
+* The Rust program in this crate reads the outputs of the script and
+  produces a list of missing crates or versions of some Rust project.
 
 A crate may be entirely missing from the target system, or the target
 may have package of an older version. The Rust program looks for both
@@ -33,15 +41,20 @@ about dependencies:
   the target system to update their package to a newer version?
 
 
-## Example
+## Example use
+
+To be run from the source tree of the `missing-dependencies` crate:
 
 ```sh
 $ ./debian-crate-packages > crates-in-debian
-$ (cd /where/rust/program/is && cargo tree) | cargo run -q -- crates-in-debian
+$ cargo run -- crates-in-debian ~/my/rust/project
 missing-version aho-corasick 0.7.18
 missing-entirely ansi_term
 ```
 
+Set `RUST_LOG` to `debug` or `info` to get log messages.
+
+
 ## FAQ
 
 ### Why is only Debian supported?
@@ -56,3 +69,14 @@ The format of the output is one line per crate, with name, a space,
 and the version, and nothing else.
 
 The name of the crate should be the name as used by the crate itself.
+
+### Why is only Debian unstable supported?
+
+If Debian needs to package an entirely new crate, it'll be uploaded to
+unstable. Likewise new versions of existing crates, except in serious
+circumstances, mostly involving security problems. Thus, if a Rust
+project wants to consider getting packaged for Debian, it'll need to
+target unstable itself.
+
+However, if you have different use case, by all means get in touch and
+let's talk about it.