Using glu

The glu command line tool executes Lua scripts for PDF typesetting. It accepts a Lua filename as an argument.

glu - Lua typesetting with boxes and glue
-h, --help                   Show this help
    --loglevel=LVL           Set the log level (debug, info, warn, error)
-q, --quiet                  Suppress output on console

Commands
      help                   Show the help message
      version                Print version and exit

Usage: glu [options] <filename.lua>

By default, glu shows log output on the console and writes a log file (<filename>.log). Use --quiet to suppress console output.

The CLI does not create any files by itself. The script is expected to open a PDF file for writing.

Hello world example explained

The sample program from the start page is analyzed here in detail. The program creates a PDF file with a single page containing some text.

local frontend = require("glu.frontend")

Loads the frontend module. All glu modules must be loaded with require().

local doc = frontend.new("hello.pdf")

Creates a new PDF document with the filename hello.pdf. The glu.frontend module is the main API for creating PDF documents with glu.

local ff = doc:new_font_family("text")
local fs = frontend.fontsource({ location = "fonts/CrimsonPro-Regular.ttf" })
ff:add_member(fs, "regular", "normal")

Fonts are organized in font families. A font family can have multiple members with different weights (regular, bold, etc.) and styles (normal, italic). Here we create a font family named “text” and add a single regular font.

local txt = frontend.text({
    font_family = ff,
    font_size = "12pt",
    color = "black"
})

Creates a text object with styling. Settings can be passed directly to the constructor. Text objects can contain strings and other text objects, allowing for nested formatting (e.g., italic text within a paragraph).

local str = [[The quick brown fox jumps over the lazy dog...]]
str = str:gsub("\n", " ")
txt:append(str)

Adds the text content to the text object. The append method accepts strings, other Text objects, VLists, or Tables.

local vlist = doc:format_paragraph(txt, "225pt", { leading = "14pt" })

The format_paragraph() function turns the text object into a vertical list (vlist) that can be placed on the page. The width is specified as the second argument, and optional settings like leading (line height) can be passed in a table.

local page = doc:new_page()
page.width = "210mm"
page.height = "297mm"
page:output_at("1cm", "28cm", vlist)
page:shipout()

Creates a new page, sets its dimensions to A4 size, and places the vertical list at the specified coordinates (1cm from the left, 28cm from the bottom).

All dimension parameters accept either numbers (interpreted as points) or strings with units like "12pt", "1cm", "10mm", or "1in".

doc:finish()

Finalizes the PDF document and writes it to the file.

Available modules

All modules must be loaded with require():

local glu = require("glu")
local frontend = require("glu.frontend")
local pdf = require("glu.pdf")
local node = require("glu.node")
local font = require("glu.font")

The glu.frontend and glu.pdf modules are for document creation. The glu, glu.node, and glu.font modules provide low-level access to the typesetting engine for advanced use cases.