Files
business-suite/bin/forms.lua
T

248 lines
9.4 KiB
Lua
Raw Normal View History

-- Copyright (c) 2026 Marc Wäckerlin. SPDX-License-Identifier: MIT
-- A chapter somebody ticks and writes into becomes a form of the PDF.
--
-- The two shapes a writer uses are the ones GitHub, GitLab and Gitea already
-- render, so the Markdown stays readable where it is read:
--
-- - [ ] **S1 Title.** What is to be confirmed
--
-- Remarks: ____________
--
-- A task list item becomes a checkbox, named after the identifier in the bold
-- lead-in of the item; where an item carries none, it is named after its place
-- in the document, `q1`, `q2`. A paragraph that is a label, a colon and a run
-- of underscores becomes a text field, named after the item it stands in,
-- `S1-remarks`, and after its label where it stands by itself.
--
-- A run of underscores ALONE is a thematic break in all three platforms and in
-- pandoc, so a field is only ever made where a label stands in front of it; a
-- rule stays a rule.
--
-- How many lines a field takes follows from where it stands, which is what the
-- writer has already said by writing it there: inside a list item it is the
-- remark on that item and takes three lines; alone in its section it is the
-- large field at the end of a form and takes six; anywhere else it is a line of
-- a signature block and takes one. Every one of them scrolls, so no entry is
-- ever cut off.
-- How many characters a line of the body text holds, measured in the probe the
-- converter builds with the identity of the company and handed over in the
-- environment, as the filters for tables and announcing sentences read it.
local LINE = (tonumber(os.getenv('MD2PDF_LINEWIDTH')) or 538)
/ (tonumber(os.getenv('MD2PDF_CHARACTER')) or 5.3)
local NESTED_LINES = 3
-- A field that stands alone between two headings is the large one at the end
-- of a form, where somebody writes as much as he has to say. Fourteen lines is
-- the free half of a page under a short section, measured on the sign-off
-- chapter it was written for; the field scrolls, so what is written is never
-- bounded by it.
local SECTION_LINES = 14
local SINGLE_LINES = 1
-- The character pandoc's gfm reader writes for a task list item, ticked and
-- unticked. They are the first inline of the item's first block.
local UNTICKED = '\u{2610}'
local TICKED = '\u{2612}'
local counted = 0
local seen = {}
local function unique(name)
local candidate, number = name, 1
while seen[candidate] do
number = number + 1
candidate = name .. '-' .. number
end
seen[candidate] = true
return candidate
end
-- The name of a field, out of the text the writer wrote: the identifier of the
-- bold lead-in, or the label of the line. Everything that is not a letter, a
-- digit or a dash becomes a dash, because a field name travels into the PDF and
-- is read there by whoever evaluates the filled file.
local function slug(text)
local name = text:gsub('[^%w%-]+', '-'):gsub('^%-+', ''):gsub('%-+$', '')
return name
end
local function identifier(blocks)
local first = blocks[1]
if not first or not first.content then return nil end
for _, inline in ipairs(first.content) do
if inline.t == 'Strong' then
local word = pandoc.utils.stringify(inline):match('^%s*([%w%._%-]+)')
if word then return slug(word) end
end
end
return nil
end
-- A paragraph that is a field: a label, a colon, and three or more underscores
-- with nothing after them.
local function field_of(block)
if block.t ~= 'Para' and block.t ~= 'Plain' then return nil end
local text = pandoc.utils.stringify(block)
local label, rule = text:match('^%s*(.-)%s*:%s*(_+)%s*$')
if not label or label == '' or #rule < 3 then return nil end
return label
end
local function task_of(block)
if block.t ~= 'Para' and block.t ~= 'Plain' then return nil end
local first = block.content and block.content[1]
if not first or first.t ~= 'Str' then return nil end
if first.text == UNTICKED or first.text == TICKED then
return first.text == TICKED
end
return nil
end
local function latex(text)
return pandoc.RawBlock('latex', text)
end
-- What stands beside the box: the item without the character pandoc wrote for
-- the box, and without the space behind it.
local function beside(block)
local kept = {}
for index, inline in ipairs(block.content) do
if index == 1 then
-- the box character itself
elseif index == 2 and inline.t == 'Space' then
-- the space behind it
else
kept[#kept + 1] = inline
end
end
return pandoc.Para(kept)
end
local function render(inlines)
local document = pandoc.Pandoc({pandoc.Plain(inlines)})
return pandoc.write(document, 'latex')
end
-- The label of a field as LaTeX text: a brace, a backslash, `%`, `&`, `#` or
-- `_` in it is written as the character, never read as a command.
local function text_of(label)
return (render({pandoc.Str(label)}):gsub('%s+$', ''))
end
-- One item of a task list: the box, the text beside it, and the fields the item
-- carries under it.
local function item(blocks, ticked)
local name = identifier(blocks)
if not name then
counted = counted + 1
name = 'q' .. counted
end
name = unique(name)
-- The room the whole item needs, so that it moves to the next page as one
-- thing: the lines its text takes, the label of every field under it, the
-- height of those fields, and the space around them. A page that breaks
-- inside an item lets the reader tick on one page and write on the next —
-- reported from a sign-off chapter where item S7 stood at the foot of page 4
-- and its frame began page 5.
local text = pandoc.utils.stringify(blocks[1])
local needed = math.max(1, math.ceil(#text / LINE)) + 1
for index = 2, #blocks do
if field_of(blocks[index]) then
needed = needed + NESTED_LINES + 2
end
end
local made = pandoc.Blocks{}
made:insert(latex('\\businessneed{' .. needed .. '}'))
local option = ticked and '[checked=true]' or ''
made:insert(latex('\\businesscheckbox' .. option .. '{' .. name .. '}{'
.. render(beside(blocks[1]).content) .. '}'))
for index = 2, #blocks do
local label = field_of(blocks[index])
if label then
-- The suffix is written small whatever the label looks like: the
-- identifier of the item is the name of the thing, the suffix says which
-- field of it, and whoever evaluates the filled file reads `S1-remarks`.
made:insert(latex('\\businessremark{' .. name .. '-'
.. slug(label):lower()
.. '}{' .. text_of(label) .. '}{' .. NESTED_LINES .. '}'))
else
made:insert(blocks[index])
end
end
return made
end
-- The document is walked from the top, and a list is descended into here. A
-- `Blocks` filter would run on the content of a list item as well, and the
-- remark under an item would be read there, out of reach of the item it
-- belongs to: it then became a line of a signature block named after its own
-- label, and three items carried three fields called «Remarks».
local function walk(blocks)
local kept = pandoc.Blocks{}
for index, block in ipairs(blocks) do
local label = field_of(block)
if label then
-- Alone between two headings it is the large field of the form, beside
-- other paragraphs it is a line of a signature block.
local before = blocks[index - 1]
local after = blocks[index + 1]
local alone = (not before or before.t == 'Header')
and (not after or after.t == 'Header')
local lines = alone and SECTION_LINES or SINGLE_LINES
local name = unique(slug(label))
if alone then
kept:insert(latex('\\businessremark{' .. name .. '}{' .. text_of(label)
.. '}{' .. lines .. '}'))
else
-- Every label of a block of lines gets the width of the widest of
-- them, so the frames begin on one edge: the labels of a signature
-- block are of different lengths, and each pushed its own frame.
local block_labels = {label}
for ahead = index + 1, #blocks do
local next_label = field_of(blocks[ahead])
if not next_label then break end
block_labels[#block_labels + 1] = next_label
end
for back = index - 1, 1, -1 do
local earlier = field_of(blocks[back])
if not earlier then break end
table.insert(block_labels, 1, earlier)
end
-- Which of them is the widest is measured in the type, by the
-- template; a label that carries a comma is left out, because the
-- list is read as one.
local listed = {}
for _, one in ipairs(block_labels) do
if not one:find(',') then listed[#listed + 1] = text_of(one) end
end
kept:insert(latex('\\businesslabelwidth{'
.. table.concat(listed, ',') .. '}'))
kept:insert(latex('\\businessline{' .. name .. '}{' .. text_of(label) .. '}'))
end
elseif block.t == 'BulletList' then
local tasks = pandoc.Blocks{}
local every = true
for _, entry in ipairs(block.content) do
local ticked = task_of(entry[1])
if ticked == nil then
every = false
break
end
tasks:extend(item(entry, ticked))
end
if every then
kept:extend(tasks)
else
kept:insert(block)
end
else
kept:insert(block)
end
end
return kept
end
function Pandoc(document)
if not FORMAT:match('latex') then return nil end
return pandoc.Pandoc(walk(document.blocks), document.meta)
end