Add complete preprocessor example (#629)

* First version of preprocessor example, with quicli

It seems it's not worth it right now.

* Remove quicli, just to simplify everything

* Finish de-emphasise example

* Finish preprocessor example in book

* Rename preprocessor type

* Apply changes requested in review

* Update preprocessor docs with latest code

[skip CI]

Author: Byron

Cargo.lock

@@ -57,6 +57,7 @@ error-chain = "0.11"
 select = "0.4"
 pretty_assertions = "0.4"
 walkdir = "2.0"
+pulldown-cmark-to-cmark = "1.1.0"
 
 [features]
 default = ["output", "watch", "serve"]

Cargo.toml

@@ -5,13 +5,13 @@ book is loaded and before it gets rendered, allowing you to update and mutate
 the book. Possible use cases are:
 
 - Creating custom helpers like `\{{#include /path/to/file.md}}`
-- Updating links so `[some chapter](some_chapter.md)` is automatically changed 
+- Updating links so `[some chapter](some_chapter.md)` is automatically changed
   to `[some chapter](some_chapter.html)` for the HTML renderer
-- Substituting in latex-style expressions (`$$ \frac{1}{3} $$`) with their 
+- Substituting in latex-style expressions (`$$ \frac{1}{3} $$`) with their
   mathjax equivalents
 
 
-## Implementing a Preprocessor 
+## Implementing a Preprocessor
 
 A preprocessor is represented by the `Preprocessor` trait.
 
@@ -29,4 +29,68 @@ pub struct PreprocessorContext {
     pub root: PathBuf,
     pub config: Config,
 }
-```
+```
+
+## A complete Example
+
+The magic happens within the `run(...)` method of the [`Preprocessor`][preprocessor-docs] trait implementation.
+
+As direct access to the chapters is not possible, you will probably end up iterating
+them using `for_each_mut(...)`:
+
+```rust
+book.for_each_mut(|item: &mut BookItem| {
+    if let BookItem::Chapter(ref mut chapter) = *item {
+      eprintln!("{}: processing chapter '{}'", self.name(), chapter.name);
+      res = Some(
+          match Deemphasize::remove_emphasis(&mut num_removed_items, chapter) {
+              Ok(md) => {
+                  chapter.content = md;
+                  Ok(())
+              }
+              Err(err) => Err(err),
+          },
+      );
+  }
+});
+```
+
+The `chapter.content` is just a markdown formatted string, and you will have to
+process it in some way. Even though it's entirely possible to implement some sort of
+manual find & replace operation, if that feels too unsafe you can use [`pulldown-cmark`][pc]
+to parse the string into events and work on them instead.
+
+Finally you can use [`pulldown-cmark-to-cmark`][pctc] to transform these events back to
+a string.
+
+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> {
+    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)
+            | Event::Start(Tag::Strong)
+            | Event::End(Tag::Emphasis)
+            | Event::End(Tag::Strong) => false,
+            _ => true,
+        };
+        if !should_keep {
+            *num_removed_items += 1;
+        }
+        should_keep
+    });
+    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
+[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/for_developers/preprocessors.md

@@ -0,0 +1,94 @@
+//! This program removes all forms of emphasis from the markdown of the book.
+extern crate mdbook;
+extern crate pulldown_cmark;
+extern crate pulldown_cmark_to_cmark;
+
+use mdbook::errors::{Error, Result};
+use mdbook::MDBook;
+use mdbook::book::{Book, BookItem, Chapter};
+use mdbook::preprocess::{Preprocessor, PreprocessorContext};
+use pulldown_cmark::{Event, Parser, Tag};
+use pulldown_cmark_to_cmark::fmt::cmark;
+
+use std::ffi::OsString;
+use std::env::{args, args_os};
+use std::process;
+
+struct Deemphasize;
+
+impl Preprocessor for Deemphasize {
+    fn name(&self) -> &str {
+        "md-links-to-html-links"
+    }
+
+    fn run(&self, _ctx: &PreprocessorContext, book: &mut Book) -> Result<()> {
+        eprintln!("Running '{}' preprocessor", self.name());
+        let mut res: Option<_> = None;
+        let mut num_removed_items = 0;
+        book.for_each_mut(|item: &mut BookItem| {
+            if let Some(Err(_)) = res {
+                return;
+            }
+            if let BookItem::Chapter(ref mut chapter) = *item {
+                eprintln!("{}: processing chapter '{}'", self.name(), chapter.name);
+                res = Some(
+                    match Deemphasize::remove_emphasis(&mut num_removed_items, chapter) {
+                        Ok(md) => {
+                            chapter.content = md;
+                            Ok(())
+                        }
+                        Err(err) => Err(err),
+                    },
+                );
+            }
+        });
+        eprintln!(
+            "{}: removed {} events from markdown stream.",
+            self.name(),
+            num_removed_items
+        );
+        match res {
+            Some(res) => res,
+            None => Ok(()),
+        }
+    }
+}
+
+fn do_it(book: OsString) -> Result<()> {
+    let mut book = MDBook::load(book)?;
+    book.with_preprecessor(Deemphasize);
+    book.build()
+}
+
+fn main() {
+    if args_os().count() != 2 {
+        eprintln!("USAGE: {} <book>", args().next().expect("executable"));
+        return;
+    }
+    if let Err(e) = do_it(args_os().skip(1).next().expect("one argument")) {
+        eprintln!("{}", e);
+        process::exit(1);
+    }
+}
+
+impl Deemphasize {
+    fn remove_emphasis(num_removed_items: &mut i32, 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)
+                | Event::Start(Tag::Strong)
+                | Event::End(Tag::Emphasis)
+                | Event::End(Tag::Strong) => false,
+                _ => true,
+            };
+            if !should_keep {
+                *num_removed_items += 1;
+            }
+            should_keep
+        });
+        cmark(events, &mut buf, None)
+            .map(|_| buf)
+            .map_err(|err| Error::from(format!("Markdown serialization failed: {}", err)))
+    }
+}