Architecture

[pgundlach]

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 frontend

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 vlists 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

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.

Units

The basic typesetting unit is a “scaled point”. 65535 scaled points are in one dtp point. There are two methods (bag.Sp() and bag.MustSp()) to convert from other units to sp.

The part that needs the most explanation is the one on nodes:

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 a or the fi ligature.
• 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.
• 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)

[simoncozens]

In the TeX system, glue nodes were flexible spaces; is this true in your implementation? TeX's algorithm was designed for text using the Latin script, where the way to implement justification was to add flexible spaces between (essentially fixed-size) words. This is obviously not optimal for scripts which justify text in other ways - through varying the width of a glyph, or using substitutions, ligatures and replacements to create text nodes of alternative sizes. I've been trying to develop an algorithm which works well for flexible glyph/hlist nodes, but I'm interested to see if there is other work in this area.

[pgundlach]

The glue has the same attributes as in TeX, so yes, it is flexible (fixed, stretch or shrink with different levels of stretch/shrink).

In the speedata Publisher (based on LuaTeX) I add a penalty of 0 and a zero width 1fil stretch after each Chinese character (this is what my code tells me, I implemented this long time ago). It doesn't look too bad, and nobody has complained so far. That said, I am sure that this is not correct and I need some better way... If someone tells me the correct way to do that.

[simoncozens]

That doesn't sound right; Chinese characters are normally typeset fixed on a grid.

I was thinking more along the lines of Arabic typesetting, where the spaces do not normally stretch to fill lines but the letters themselves either expand in width or take different forms to fill the lines.

[pgundlach]

I know about the grid, but the above trivial procedure works well for most of my text, so I didn't bother to implement a better algorithm until someone complains or funds me. Similar for Arabic typesetting, I chose the simple ragged left typesetting until someone asks me to do better, then I start thinking about a better implementation.

More than 99% of my paid work is for documents using the Latin script, so my motivation to come up with something good for non-Latin scripts is not too high. So don't count on my for any ideas...