build

Documentation

Overview

Package build is the layout engine.

It applies a template to a sequence of records and produces a printout, per doc/layout.md.

Layout is speculative. Every band is measured into a scratch context, then decided against the space remaining, and only then committed. Band splitting, keep-together, orphan and widow control, measured header reservation, and correct deferred page counts are all consequences of that separation.

Index

• func Build(report *tmpl.Report, rows []map[string]any, opts Options) (*printout.Printout, error)
• type FontCheck
  • func Fonts(report *tmpl.Report, opts Options) (*FontCheck, error)
• type Options

Functions

func Build

func Build(report *tmpl.Report, rows []map[string]any, opts Options) (*printout.Printout, error)

Build applies a template to records and returns a printout.

Types

type FontCheck

type FontCheck struct {
	// Fonts are the fonts that resolved, sorted by name
	// as a printout header holds them.
	Fonts []printout.FontEntry
	// Failures name the fonts that did not resolve, one message each.
	Failures []string
	// Warnings are diagnostics about the document: a typeface that reached
	// the substitute, a face whose style bits contradict the declaration.
	Warnings []string
	// Diagnostics describe the machine rather than the document:
	// a font file that could not be read, two faces claiming one identity.
	Diagnostics []string
}

FontCheck is what resolving a template's fonts found out.

func Fonts

func Fonts(report *tmpl.Report, opts Options) (*FontCheck, error)

Fonts resolves every font a template declares, without any data.

It is what a template check works from. Everything else in a template is settled at load, from the document alone; font resolution is the one part that depends on the machine, so it is the one part a check has to run.

A font that does not resolve is collected rather than returned, so that one missing typeface does not hide the next.

type Options

type Options struct {
	// TextParams are values supplied as text, parsed per the parameter's type.
	TextParams map[string]string
	// Values are values supplied already typed.
	Values map[string]starlark.Value
	// BuildTime fixes BUILD_TIME. The zero value means now.
	BuildTime gotime.Time
	// StrictFonts resolves only fonts the template names by file or data.
	StrictFonts bool
	// AllowOverflow downgrades oversized-band errors to warnings
	// recorded in the printout.
	AllowOverflow bool
	// Engine names the producing engine in the printout header.
	Engine string
	// Diagnostics receives messages about the machine: fonts that
	// could not be read, faces that collided. They describe the host
	// rather than the document, so they never enter the printout's warning list.
	Diagnostics func(string)
}

Options configure a build.