backend module

The backend Module

The backend module provides low-level access to the PDF generation and typesetting features of the boxes and glue library. It is intended for advanced users who need fine-grained control over document creation, typesetting, and PDF output.

Features

Direct access to PDF document structure and metadata
Page creation and management
Font and image loading
Node list manipulation (boxes, glue, glyphs, etc.)
Hyphenation and language support
Color management
Logging and debugging tools

Typical Usage

The backend module is usually accessed via the frontend document:

f := frontend.new("out.pdf")
backend_doc := f.doc
backend_doc.title = "A test document"
backend_doc.language = frontend.get_language("en")

You can then use the backend document to set metadata, create pages, and access advanced features.

Example: Setting PDF Metadata

backend_doc.title = "A test document"
backend_doc.author = "A. U. Thor"
backend_doc.subject = "Demo PDF"

Example: Creating a Page

page := backend_doc.new_page()
// ... add content to the page ...
page.shipout()

Advanced Features

Node manipulation: Create and modify low-level typesetting nodes for custom layouts.
Font handling: Load and use custom fonts for advanced text shaping.
Image inclusion: Embed images directly into the PDF.
Debugging: Output XML dumps and enable trace logging for troubleshooting.

Reference

The backend document

Get with

f := frontend.new("out.pdf")
doc := f.doc

Name	R/W	Parameters	Description
`attachments`	r	-	A list with attachments
`author`	w	string	Set the author of the document
`bleed`	w	scaled point	The amount of extra space on each side of the page
`compresslevel`	w	int (0-9)	The zlib compression level.
`create_image_node_from_imagefile()`		?	Turns an image object into a node
`creation_date`	w	time	The creation date of the document
`creator`	w	string	The document creator software
`default_page_height`	w	scaled point	The default page height
`default_page_width`	w	scaled point	The default page width
`dump_output`	w	bool	Collect info for later XML output.
`filename`	r	-	The file name of the PDF
`finish()`		-	Write all objects to the PDF file
`format`	w	string	One of “”, “PDF/A-3b”, “PDF/X-3”, “PDF/X-4”, “PDF/UA”
`keywords`	w	string	Comma separated list
`language`	w	string or language object	Set the document’s default language for hyphenation
`load_imagefile()`		?	Load an image object (PNG, PDF, JPEG)
`new_page()`		?	Create a new page
`output_xml_dump()`		?	Creates an XML dump from the document (might be large!)
`show_cutmarks`	w	bool	Show cropmarks
`show_hyperlinks`	w	bool	Toggle hyperlink borders
`subject`	w	string	The document’s subject
`suppressinfo`	w	bool	Set to true if you need a fixed document id and date
`title`	w	string	The document’s title
`viewer_preferences`	w	Map	A key value-map from section 8.1 of the PDF 1.7 spec

Page

Name	R/W	Parameters	Description
`height`	r/w	scaled point	Set the height of the page
`width`	r/w	scaled point	Set the width of the page
`output_at()`		?	Place object on page
`shipout()`		scaled point, scaled point and vlist	Place page in PDF

PDF backend (baseline-pdf)

Name	R/W	Parameters	Description
`baselinepdf.new()`		string (filename)	Create a new PDF backend object based on the file given with filename. The file is created if it does not exist. If it exists, it is overwritten.

PDF object

Name	R/W	Parameters	Description
`new_face()`		string (name)	Create a font instance from the font paath with the given name.

Fonts

Name	R/W	Parameters	Description
`font.new()`		face, scaled_point (size)	Create a font from a face. A font is an instance of a face with a given size.
`font.new_feature()`		string (name)	Create a new font feature with the given name, for example “+liga”.

The font object can now be used to shape text.

Name	R/W	Parameters	Description
`font.shape()`		string (text), features (font.feature) …	Shape the text with the font. Returns a list of atoms (glyphs). The text is shaped with the font’s features.

Atoms

Name	R/W	Parameters	Description
`advance`	r	scaled point	The advance width of the atom.
`components`	r	string	The “string value” (optional) of the glyph.
`codepoint`	r	int	The font specific codepoint of the glyph.
`depth`	r	scaled point	The depth of the glyph.
`is_space`	r	bool	True if the glyph is a space.
`height`	r	scaled point	The height of the glyph.
`hyphenate`	r	bool	True if the glyph is part of a word.
`kernafter`	r	scaled point	The kerning after the glyph.

Example:

outfile := baselinepdf.new("/dev/null")
f := outfile.new_face("fonts/CrimsonPro-Regular.ttf")
fnt := font.new(f,bag.sp("12pt"))
ff := font.new_feature("+liga")
atoms := fnt.shape("fluffy",ff)

for i,a := range atoms {
    print(a)
}

prints

Load font (filename=fonts/CrimsonPro-Regular.ttf)
font.atom(fl) advance=6.51 depth=2.32 height=9.68 codepoint=481 hyphenate=true
font.atom(u) advance=6.36 depth=2.32 height=9.68 codepoint=428 hyphenate=true
font.atom(f) advance=3.55 depth=2.32 height=9.68 codepoint=304 hyphenate=true
font.atom(f) advance=3.55 depth=2.32 height=9.68 kernafter=-0.16 codepoint=304 hyphenate=true
font.atom(y) advance=5.52 depth=2.32 height=9.68 codepoint=458 hyphenate=true

Nodes

There are several types of nodes: node.disc, node.glue, node.glyph, node.hlist, node.image, node.kern, node.lang, node.penalty, node.rule, node.startstop and node.vlist.

You can create a new node with node.new(). The expected argument is a string, one of disc, glue, glyph, hlist, image, kern, lang, penalty, rule, startstop or vlist.

Package functions

Name	Parameters	Description
`node.new()`	`string`	Create (and return ) a new node.
`node.insert_after()`	`node` (head), `node` (cur), `node` (new)	Insert the new node after cur in a list starting with head. The head is returned.
`node.insert_before()`	`node` (head), `node` (cur), `node` (new)	Insert the new node before cur in a list starting with head. The (perhaps new) head is returned.
`node.copy_list()`	`node` (head)	Create a deep copy of a list starting at head.

Disc node

Field	R/W	Parameters	Description
`pre`	w	node	The node before the disc
`post`	w	node	The node after the disc
`replace`	w	node	The replacement
`penalty`	w	int	The penalty for breaking at this point

Glue node

Field	R/W	Parameters	Description
`subtype`	w	string	The subtype of the glue
`width`	w	scaled point	The natural width of the glue
`stretch`	w	scaled point	The stretchability of the glue
`shrink`	w	scaled point	The shrinkability of the glue
`stretchorder`	w	int	The order of infinity of stretching
`shrinkorder`	w	int	The order of infinity of shrinking

Glyph node

Field	R/W	Parameters	Description
`font`	w	font object	The font of the glyph
`codepoint`	w	int	The codepoint of the glyph
`components`	w	string	The components of the glyph
`width`	w	scaled point	The width of the glyph
`height`	w	scaled point	The height of the glyph
`depth`	w	scaled point	The depth of the glyph
`yoffset`	w	scaled point	The vertical offset of the glyph
`hyphenate`	w	bool	Set the hyphenation flag for the glyph

Hlist node

Field	R/W	Parameters	Description
`width`	w	scaled point	The width of the hlist
`height`	w	scaled point	The height of the hlist
`depth`	w	scaled point	The depth of the hlist
`badness`	w	int	The badness of the hlist
`glueset`	w	float	The ratio of the glue. Positive means stretching, negative shrinking.
`gluesign`	w	int	0 = normal, 1 = stretching, 2 = shrinking
`glueorder`	w	int	The level of infinity
`shift`	w	scaled point	The displacement perpendicular to the progressing direction. Not used.
`valign`	w	int	The vertical alignment of the hlist
`list`	w	node	The list itself

Image node

Field	R/W	Parameters	Description
`width`	w	scaled point	Set the resulting width of the image
`height`	w	scaled point	Set the resulting height of the image
`image`	w	image object	The image object
`page`	w	int	The page number of the image
`used`	w	bool	Set to true if the image is written to the page

Kern node

Field	R/W	Parameters	Description
`kern`	w	scaled point	The width of the kern

Lang node

Field	R/W	Parameters	Description
`lang`	w	Lang	The language of the node

Penalty node

Field	R/W	Parameters	Description
`penalty`	w	int	Set the penalty when breaking at this point
`width`	w	scaled point	Set the width of the penalty

Rule node

Field	R/W	Parameters	Description
`width`	w	scaled point	The width of the rule
`height`	w	scaled point	The height of the rule
`depth`	w	scaled point	The depth of the rule
`pre`	w	string	The pdf instructions before the rule
`post`	w	string	The pdf instructions after the rule
`hide`	w	bool	Set to true if the rule is hidden

StartStop node

Field	R/W	Parameters	Description
`action`	w	ActionType	The action type
`startnode`	w	StartStop	The start node
`position`	w	PDFDataOutput	The position of the node
`shipout_callback`	w	StartStopFunc	The shipout callback
`value`	w	any	The value of the node

Vlist node

Field	R/W	Parameters	Description
`width`	w	scaled point	The width of the vlist
`height`	w	scaled point	The height of the vlist
`depth`	w	scaled point	The depth of the vlist
`glueset`	w	float	The ratio of the glue. Positive means stretching, negative shrinking.
`gluesign`	w	int	0 = normal, 1 = stretching, 2 = shrinking
`shift_x`	w	scaled point	The displacement perpendicular to the progressing direction.
`list`	w	node	The list itself

Logging

The logging is based on Go’ standard library slog. It allows several log levels, a main message and a set of key/value pairs, where each key is a string. You have to provide an even number of arguments for the key/value pairs.

The commands for logging are bag.debug(), bag.info(), bag.warn() and bag.error(). Each of these follow the same schema:

bag.info("something happens", "key1", value1, "key2", value2, ...)

for example:

filename := "somefile.png"
bag.info("File loaded", "filename", filename)

frontend module Go API