Architecture overview of “boxes and glue”
Here is an attempt go give you an overview of the “boxes and glue” PDF typesetting library
There is a high level API (the frontend) and a low level API. Both can be used to create PDF documents. While the frontend gives you ready to use data structures and methods, you can still use the backend and create all the items yourself.
The typesetting frontend knows about these building blocks:
- font sources: A font source represents a physical font file (OpenType, TrueType).
- font families: font families group font sources together to ease switching to different font styles and weights.
- document: This is the main object and represents a PDF document.
- page: A document contains pages and each page has vertical lists (vlist nodes) containing typesetting material.
- typesetting element: a typesetting element is a hierarchical data structure which contains paragraphs and font switches and other elements such as hyperlinks.
The backend has all low level functions to handle typesetting (basic font loading and accessing, language handling and hyphenation, justification of paragraphs, …). It also contains the logging API that is used in the frontend can which can be used in the underlying application.
The basic typesetting unit is a “scaled point”. 65535 scaled points are in one dtp point. There are two methods (
bag.MustSp()) to convert from other units to sp.
The part that needs the most explanation is the one on nodes:
A node is a tiny piece of information that can be chained with other nodes to node lists. A node can be a glyph, a rule, an image or a box that holds other nodes.
These are the known node types:
- disc: a disc node holds information about a (line-)break point.
- glue: a glue node is a length with a stretchable and shrinkable part (similar to a metal spring which has a natural width but can be squeezed and stretched).
- glyph: a glyph is a visible entity such as the letter
- hlist: a box containing nodes that are stacked horizontally next to each other.
- image: a picture or a drawing which can be included in the PDF file.
- kern: a non-stretchable space between glyphs.
- lang: a node that switches to a language.
- penalty: a penalty node can allow or inhibit line breaks.
- rule: a colored box which can include PDF code.
- startstop: a paired set of nodes that switches temporarily to a different color or inserts a hyperlinked text.
- vlist: a box containing nodes that are stacked above each other.
(to be continued/extended)