Crate bookbinder_ast

This crate makes the building of a BookSrc easy; this struct can then be used to render to a specific backend after being adapted to various options.

General usage is to create a BookSrcBuilder, set metadata values and add content, then create a BookSrc from the builder.

Because books get complicated quickly, there are a lot of builder methods and toggles. Simple usage, however, is very simple.

use bookbinder_ast::BookSrcBuilder;
let src = BookSrcBuilder::new("A Book")
   .subtitle("Serving as an Example")
   .author("A.N. Author")
   .add_mainmatter("# Hello World\n\nText goes here...")
   .process();

Because we incorporate the idea of semantic divisions, various pieces of ancillary text can be added and formatted appropriately: see, for example, add_foreword.

Markdown

The markdown source interpreted has a few small extensions from CommonMark:

• footnotes: add footnotes using [^marker] ... [^marker]: definition
• formatting spans: text can be wrapped in a handful of spans to format it in various ways:
  • <span class="sans">Sans Text</span>
  • <span class="smallcaps">Small caps text</span>
  • <span class="centred">Centred text</span>
  • <span class="right-aligned">Right aligned text</span>
• escaping: -- and --- are turned into en and em-dashes respectively, while a row of three full stops (...) becomes an ellipsis.
• quotes: straight quotes are -- at least in theory -- turned into appropriate curly quotes; this is a problem impossible to get absolutely right without actually understanding text, but the algorithm used is fairly robust and takes into account semantics (so that, for example, quotes in code are not transformed). Still, for perfect accuracy, it's best to use curly quotes explicitly.
• sub and superscript: 22^nd^ July, H~2~0;

Modules

helpers

Helpers for common ast manipulations required across different crates, such as collating multi-event elements.

Structs

BookSrc	A processed book source ready to be rendered
BookSrcBuilder	The source for a particular book; essentially a way to create a BookSrc using a builder pattern.
Metadata	The metadata of a particular book
TextHeaderOptions	Specification of text headers

Enums

BookEvent	A particular event in a book, such as the beginning of a paragraph or a span of text
CowStr	A copy-on-write string that can be owned, borrowed or inlined.
Event	A markdown event
HeaderFormat	Specification of chapter header format
NumberFormat	The display format of a number
SemanticRole	Specification of a section's semantic role, such as being a foreword or a chapter. These are taken from Epub 3.2's structural semantics
Tag	A tag containing other events
TitlePageContributorRole	Indicate a contributor to the work who should appear on a titlepage

Traits

ContributorSource	Implemented for str-like types which can be interpreted as either a single name or multiple names; this is a convenience trait to allow overloading methods to add names rather than having to have a method to add a single name and one to add multiple names. It shouldn't really be a worry for end users, since it is pre-implemented for likely types.
EventHelper	Helper functions for collections of events
ParseHelper	A helper trait to parse source material