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

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

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