From 2732c5e8f77c32254778fa192fb247248ebfaa67 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Tue, 21 Apr 2020 15:34:59 -0700
Subject: [PATCH] Update docs and tweak error messages.

---
 book-example/src/for_developers/backends.md |  2 +-
 book-example/src/format/config.md           | 14 ++++++++++----
 src/renderer/mod.rs                         | 12 +++++++-----
 3 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/book-example/src/for_developers/backends.md b/book-example/src/for_developers/backends.md
index 1b289c5f..605c2191 100644
--- a/book-example/src/for_developers/backends.md
+++ b/book-example/src/for_developers/backends.md
@@ -331,7 +331,7 @@ the usual `RUST_LOG` to control logging verbosity.
 
 ## Handling missing backends
 
-If you should enable a backend that isn't installed, the default behavior is to throw an error:
+If you enable a backend that isn't installed, the default behavior is to throw an error:
 
 ```text
 The command wasn't found, is the "wordcount" backend installed?
diff --git a/book-example/src/format/config.md b/book-example/src/format/config.md
index 82c896c3..d8be13e8 100644
--- a/book-example/src/format/config.md
+++ b/book-example/src/format/config.md
@@ -306,11 +306,17 @@ specify which preprocessors should run before the Markdown renderer.
 A custom renderer can be enabled by adding a `[output.foo]` table to your
 `book.toml`. Similar to [preprocessors](#configuring-preprocessors) this will
 instruct `mdbook` to pass a representation of the book to `mdbook-foo` for
-rendering.
+rendering. See the [alternative backends] chapter for more detail.
 
-Custom renderers will have access to all configuration within their table
-(i.e. anything under `[output.foo]`), and the command to be invoked can be
-manually specified with the `command` field.
+The custom renderer has access to all the fields within its table (i.e.
+anything under `[output.foo]`). mdBook checks for two common fields:
+
+- **command:** The command to execute for this custom renderer. Defaults to
+  the name of the renderer with the `mdbook-` prefix (such as `mdbook-foo`).
+- **optional:** If `true`, then the command will be ignored if it is not
+  installed, otherwise mdBook will fail with an error. Defaults to `false`.
+
+[alternative backends]: ../for_developers/backends.md
 
 ## Environment Variables
 
diff --git a/src/renderer/mod.rs b/src/renderer/mod.rs
index 02244ae2..318e7da3 100644
--- a/src/renderer/mod.rs
+++ b/src/renderer/mod.rs
@@ -166,15 +166,17 @@ impl CmdRenderer {
                 };
 
                 if is_optional {
-                    warn!("The command was not found, but was marked as optional.");
-                    warn!("\tCommand: {}", self.cmd);
+                    warn!(
+                        "The command `{}` for backend `{}` was not found, \
+                        but was marked as optional.",
+                        self.cmd, self.name
+                    );
                     return Ok(());
                 } else {
                     error!(
-                        "The command wasn't found, is the \"{}\" backend installed?",
-                        self.name
+                        "The command `{}` wasn't found, is the `{}` backend installed?",
+                        self.cmd, self.name
                     );
-                    error!("\tCommand: {}", self.cmd);
                 }
             }
             _ => {}