Diagnostics

fleuron reports trouble two ways: warnings and errors. Unsupported CSS, a font that would not load, a family that resolved nothing, all are reported as warnings. Whatever caused the warning is ignored by the engine, and the book is still successfully rendered.

Any errors prevent the book from being rendered. Malformed input, a face that cannot be embedded, or geometry a PDF cannot express.

The stylesheet below has two declarations the engine does not support. Both are reported, with the line and column they were written at, and the content still renders.

Stylesheet, as CSS

A stylesheet outside the subset, and the page it did not stop.

Reading warnings

Warnings come back on the output:

let output = fleuron::layout::layout_book(&book, &styles, &registry, &assets);
for warning in &output.warnings {
    match &warning.origin {
        Some(origin) => eprintln!("warning: {origin}: {}", warning.message),
        None => eprintln!("warning: {}", warning.message),
    }
}

origin is a source location when one exists. For CSS it is the sheet’s name with a line and column, the name being whatever you passed to Source::author. For content it is the source file and position, like chapter-01.md:12:3, recorded on the node the markdown was read into. A node with no position degrades to the bare file name.

Style compilation collects its own warnings before layout runs, and Stylesheets::warnings() has them as soon as parsing and font loading are done. LayoutOutput::warnings is the whole run’s, compilation included, so reading it once at the end is enough.

What warns


a construct the content structure does not support	A definition list, strikethrough, math. The frontend falls back to plain prose and names the line and column. Prose is never dropped, so the page has changed shape rather than lost anything. The markdown mapping is the full list.
a CSS declaration outside the supported subset	The property, the at-rule or the selector, at the line and column it was written at. See the CSS subset.
a font that would not load	An `@font-face` whose `src` the loader could not resolve, or resolved to bytes that are not a readable font. Text falls back to the next family in the list.
a family that resolved nothing	The whole `font-family` stack came up empty. Usually a spelling mistake, or a loader rooted in the wrong directory.
a font without a feature the stylesheet named	The stylesheet names an OpenType feature the face does not have, with `font-feature-settings` or a `font-variant` longhand. The warning names the family and the tag, and the text is laid out without the feature. See font features.
a missing font style	An italic or a weight the family does not have. Nothing is synthesized, so the text is rendered with the closest style and the warning names the style that was asked for.
a language with no hyphenation patterns	The book declares a language the engine has no patterns for. The warning names the tag, and hyphenation is skipped for that language. See `hyphens: auto`.
an image not supplied to the engine	A url that is missing, or bytes the header probe does not recognize. A url comes from the manuscript, for an image it places, or from the stylesheet, for a `background-image`. The image is skipped. For a url the stylesheet named, the engine names the line and column it was written at.
an image taller than the page	The image is scaled down to the content box.
a code block wider than the measure	A line of a code block is wider than the measure. The line runs past the measure, because a code block breaks only where its own text does. The engine names the line and column of the block. See code blocks.
a reference that names nothing	A `target-counter()` or a `target-text()` names a source, a heading, or an id that the book does not have. The engine warns the same way for `attr(href url)` on an element that is not a link. The pseudo-element prints nothing. The engine names the line and column of the link. A reference to a web address, such as `https://example.com`, prints nothing, and the engine does not warn. See the CSS subset.
a link that names nothing	A link names a source, a heading, or an id that the book does not have. The text of the link is not a link in the PDF or in the preview. The engine names the line and column of the link. A link to a web address, such as `https://example.com`, is a link, and the engine does not warn.
CSS that describes pages, in an EPUB	An author stylesheet has CSS that describes pages, such as `@page` or `orphans`, and the output is an EPUB. The reading system makes the pages, so fleuron leaves the CSS out of the EPUB. The warning names the line and column. See CSS in an EPUB.
a target that moved to another page	Printing the page numbers moved a target to another page. The reference prints the page from before the move. The engine warns and names the target and both pages.

What fails


input that is not markdown	A file the CLI cannot read.
a font that could not be embedded	`PdfError::Font`, naming the face. Usually a font whose license bits or table layout the writer cannot embed.
an image that could not be embedded	`PdfError::Image`, naming the url. The header probe and the writer read the same file, so this is a format one supports and the other does not.
geometry a PDF cannot express	`PdfError::Geometry`, naming the page number and the kind of item. A non-finite coordinate reaching the writer is the usual cause, and that is a bug in the engine rather than a problem with the document.
serialization	`PdfError::Serialize`, with the writer’s own message.

From the command line

The CLI prints warnings to stderr, one per line, prefixed with the input they came from, and then a count. It still exits 0, because the PDF or the EPUB was written. The CLI reference has the exit codes.