Updated the documentation for new preprocessor format (#787)

* Updated the documentation for new preprocessor format

* adjusted the descriptions for preprocessors

Author: rbuckland

book-example/src/for_developers/preprocessors.md

@@ -18,7 +18,10 @@ A preprocessor is represented by the `Preprocessor` trait.
 ```rust
 pub trait Preprocessor {
     fn name(&self) -> &str;
-    fn run(&self, ctx: &PreprocessorContext, book: &mut Book) -> Result<()>;
+    fn run(&self, ctx: &PreprocessorContext, book: Book) -> Result<Book>;
+    fn supports_renderer(&self, _renderer: &str) -> bool {
+        true
+    }
 }
 ```
 
@@ -28,9 +31,13 @@ Where the `PreprocessorContext` is defined as
 pub struct PreprocessorContext {
     pub root: PathBuf,
     pub config: Config,
+    /// The `Renderer` this preprocessor is being used with.
+    pub renderer: String,
 }
 ```
 
+The `renderer` value allows you react accordingly, for example, PDF or HTML.
+
 ## A complete Example
 
 The magic happens within the `run(...)` method of the
@@ -68,8 +75,12 @@ The following code block shows how to remove all emphasis from markdown, and do
 so safely.
 
 ```rust
-fn remove_emphasis(num_removed_items: &mut i32, chapter: &mut Chapter) -> Result<String> {
+fn remove_emphasis(
+    num_removed_items: &mut usize,
+    chapter: &mut Chapter,
+) -> Result<String> {
     let mut buf = String::with_capacity(chapter.content.len());
+
     let events = Parser::new(&chapter.content).filter(|e| {
         let should_keep = match *e {
             Event::Start(Tag::Emphasis)
@@ -83,15 +94,16 @@ fn remove_emphasis(num_removed_items: &mut i32, chapter: &mut Chapter) -> Result
         }
         should_keep
     });
-    cmark(events, &mut buf, None)
-        .map(|_| buf)
-        .map_err(|err| Error::from(format!("Markdown serialization failed: {}", err)))
+
+    cmark(events, &mut buf, None).map(|_| buf).map_err(|err| {
+        Error::from(format!("Markdown serialization failed: {}", err))
+    })
 }
 ```
 
 For everything else, have a look [at the complete example][example].
 
-[preprocessor-docs]: https://docs.rs/mdbook/0.1.3/mdbook/preprocess/trait.Preprocessor.html
+[preprocessor-docs]: https://docs.rs/mdbook/latest/mdbook/preprocess/trait.Preprocessor.html
 [pc]: https://crates.io/crates/pulldown-cmark
 [pctc]: https://crates.io/crates/pulldown-cmark-to-cmark
 [example]: https://github.com/rust-lang-nursery/mdBook/blob/master/examples/de-emphasize.rs

book-example/src/format/config.md

@@ -14,6 +14,10 @@ description = "The example book covers examples."
 build-dir = "my-example-book"
 create-missing = false
 
+[preprocess.index]
+
+[preprocess.links]
+
 [output.html]
 additional-css = ["custom.css"]
 
@@ -27,7 +31,6 @@ It is important to note that **any** relative path specified in the in the
 configuration will always be taken relative from the root of the book where the
 configuration file is located.
 
-
 ### General metadata
 
 This is general information about your book.
@@ -59,15 +62,25 @@ This controls the build process of your book.
   will be created when the book is built (i.e. `create-missing = true`). If this
   is `false` then the build process will instead exit with an error if any files
   do not exist.
-- **preprocess:** Specify which preprocessors to be applied. Default is
-  `["links", "index"]`. To disable default preprocessors, pass an empty array
-  `[]` in.
+- **use-default-preprocessors:** Disable the default preprocessors of (`links` &
+  `index`) by setting this option to `false`.
 
+  If you have the same, and/or other preprocessors declared via their table
+  of configuration, they will run instead.
+
+  - For clarity, with no preprocessor configuration, the default `links` and 
+    `index` will run.
+  - Setting `use-default-preprocessors = false` will disable these
+    default preprocessors from running.
+  - Adding `[preprocessor.links]`, for example, will ensure, regardless of 
+    `use-default-preprocessors` that `links` it will run.
+
+## Configuring Preprocessors
 
 The following preprocessors are available and included by default:
 
-- `links`: Expand the `{{# playpen}}` and `{{# include}}` handlebars helpers in
-  a chapter.
+- `links`: Expand the `{{ #playpen }}` and `{{ #include }}` handlebars helpers in
+  a chapter to include the contents of a file.
 - `index`: Convert all chapter files named `README.md` into `index.md`. That is
   to say, all `README.md` would be rendered to an index file `index.html` in the
   rendered book.
@@ -78,10 +91,39 @@ The following preprocessors are available and included by default:
 [build]
 build-dir = "build"
 create-missing = false
-preprocess = ["links", "index"]
+
+[preprocess.links]
+
+[preprocess.index]
 ```
 
+### Custom Preprocessor Configuration
+
+Like renderers, preprocessor will need to be given its own table (e.g. `[preprocessor.mathjax]`). 
+In the section, you may then pass extra configuration to the preprocessor by adding key-value pairs to the table.
+
+For example
+
+```
+[preprocess.links]
+# set the renderers this preprocessor will run for
+renderers = ["html"]
+some_extra_feature = true
+```
+
+#### Locking a Preprocessor dependency to a renderer
+
+You can explicitly specify that a preprocessor should run for a renderer by binding the two together.
+
+```
+[preprocessor.mathjax]
+renderers = ["html"]  # mathjax only makes sense with the HTML renderer
+```
+
+## Configuring Renderers
+
 ### HTML renderer options
+
 The HTML renderer has a couple of options as well. All the options for the
 renderer need to be specified under the TOML table `[output.html]`.
 
@@ -214,4 +256,4 @@ book's title without needing to touch your `book.toml`.
 
 The latter case may be useful in situations where `mdbook` is invoked from a
 script or CI, where it sometimes isn't possible to update the `book.toml` before
-building.
+building.