ela
Contents

ManualPackages

PDF documents

In the terminalela --spec pdf-documents

pdf.write(path, blocks, title = "", size = "A4", font = "", mono = "") lays a list of blocks out down A4 pages, an inch of margin all round, and writes them as a PDF at path. Each block is a map with one key that says what it is:

BlockLays out
{"heading": text, "level": 2}A heading in bold, level 1 (the default), 2 or 3 from largest to smallest; never left alone at a page's foot, and an entry in the reader's outline
{"paragraph": text}Paragraphs, as Markdown has them: the lines of one join with a space and reflow to the page, and an empty line starts the next
{"lines": text}The text with its line breaks kept, as an address or a signature; a line longer than the page wraps, and the next line starts afresh
{"code": text}Monospace, every line and space kept, a tab moved on to the next multiple of 4 columns; a line longer than the page breaks with → at its end
{"image": path, "caption": text, "height": 200}A JPEG or PNG fitted to the page's width, centred, at most height points tall when given, its caption under it; without its metadata (camera, GPS, a generator's prompt)
{"table": rows, "columns": ["name", "seconds"]}A list of maps, as json.decode and toml.decode give them, one a row; columns picks and orders the keys, the first row's keys when left out. A column of numbers is set to the right, and null or a missing key is an empty cell. The heading row repeats at the top of each page
{"page_break": true}The next block starts a new page
results = json.decode(file.read("results.json"))failed = 0for r in $results    if $r["status"] != "passed"        failed = $failed + 1    end ifend forsummary = """    The nightly build ran ${len($results)} suites on the runner.    $failed of them failed; the log's last lines are below.     Times are in seconds, from the start of each suite.    """log = $(tail -n 20 build.log)pdf.write("nightly.pdf", [    {"heading": "Nightly build"},    {"paragraph": $summary},    {"table": $results, "columns": ["suite", "status", "seconds"]},    {"heading": "Log", "level": 2},    {"code": $log},], title = "Nightly build")

summary gives two paragraphs: its first two lines join into one, and the empty line starts the second.

  • size is "A4", "A4 landscape", "letter" or "letter landscape"; title is the document's title, which a reader shows in its title bar. A document of more than one page has its pages numbered at the foot, 2 of 5.
  • Text is set in a TrueType font embedded in the file: font and mono name one by path, for the text and for code. Without them the first family found in /usr/share/fonts/truetype is used: Source Sans 3 (amber-fonts), DejaVu Sans, Liberation Sans, Noto Sans or FreeSans, with its bold for headings, and Source Code Pro, DejaVu Sans Mono, Liberation Mono, Noto Sans Mono or FreeMono for code. Fonts are looked for there only, never through fontconfig or a home folder, so a script writes the same document for every user. A named font is used for headings too. A CFF .otf and a font collection can't be embedded.
  • Every block is checked before anything is written: a block with no kind or two, a key its kind doesn't take, text that isn't a string or a cell that is a list is an error that says what to write, and no file is left half written. So is a character the font lacks, which would show as an empty box: the error names it and says to give a font that has it.
  • A text block is a string: a number goes in through interpolation, "$count tests", and a list through str.join.
  • pdf writes only; reading a PDF is not offered.