Crate API split

[ehuss]

This issue is to solicit feedback on an upcoming change to mdBook (planned for 0.5) to split it into multiple crates. The main intent here is to reduce the dependency tree for many preprocessors and renderers, and to try to have more well-established API boundaries.

A potential significant downside is that some methods that currently exist may need to get moved elsewhere due to the current monolithic structure. This may end up with APIs that are not quite as natural as they once were, such as needing newtype wrappers or free functions. There will need to be some exploration and experimentation to figure out the right fit.

Of course this will also be somewhat disruptive for existing preprocessors and renderers. My hope is that the long-term benefits will outweigh that cost.

I have done some small surveys of existing preprocessors and renderers to see which APIs are in use, and I think the following structure should accommodate most of them to have a much smaller dependency tree.

The general structure I am currently thinking of would look something like this:

• mdbook-preprocessor

  • Minimum code to deserialize. Preprocessor, PreprocessorContext, MDBOOK_VERSION
  • Rexports from mdbook-core

• mdbook-renderer

  • Minimum code to deserialize. Renderer, RenderContext, MDBOOK_VERSION
  • Rexports from mdbook-core

• mdbook-core

  • Book, Config, errors? utils?
  • It is not expected that anything outside of mdbook should depend on this.

• mdbook-markdown

  • All basic markdown support (new_cmark_parser, etc.)

• mdbook-html

  • HTML renderer

• mdbook-summary

  • Summary parsing

• mdbook-driver

  • MDBook, theme, utils?
  • This is the "run mdbook as a library" interface.

• mdbook

  • The CLI