readme: update

Rewrite the README and the source comments in a plainer register.

The README had picked up the usual generated-prose tics: seventeen em
dashes, inline bold headers over every work item, signposting lines like
'the two scripts are called out because it matters', and a two-word
'Twenty of them.' dropped in for emphasis. Replaced with commas, real
section headings, and sentences that carry their own subject.

Also fixes the two rustdoc warnings cargo doc was emitting: <NAME> and
<N> in the subcommand doc comments were being parsed as unclosed HTML
tags. cargo doc is clean now.

src/config.rs

@@ -1,7 +1,7 @@
 //! Where the kernel tree and the patches live.
 //!
-//! Everything else asks this module for paths, so the day a config file or
-//! `spectral init` arrives, it is the only thing that changes.
+//! Everything else asks this module for paths, so adding a config file or a
+//! `spectral init` only touches this file.
 
 #![allow(dead_code)] // accessors are read once the patch verbs stop being stubs
 
@@ -29,9 +29,9 @@ impl Config {
     /// Resolve the tree from `$SPECTRAL_KERNEL`, falling back to
     /// `~/.spectral/linux`.
     ///
-    /// The tree is not checked for existence here — commands that need it call
-    /// [`Config::require_kernel_tree`], so `kernel quest` still works before
-    /// anything is cloned.
+    /// The tree is not checked for existence here. Commands that need it call
+    /// [`Config::require_kernel_tree`], which leaves `kernel quest` working
+    /// before anything is cloned.
     ///
     /// TODO: also read `~/.config/spectral/config.toml` once `spectral init`
     /// exists. The environment variable should keep winning over the file.
@@ -56,7 +56,7 @@ impl Config {
         &self.patch_dir
     }
 
-    /// The kernel tree, having confirmed it is one.
+    /// Resolve the tree and check that it really is a kernel source tree.
     pub fn require_kernel_tree(&self) -> Result<&Path> {
         if self.kernel_tree.join("scripts/checkpatch.pl").is_file() {
             Ok(&self.kernel_tree)