Přemysl Eric Janouch
e8752e53ac
Publishing my old invoice layouter in a reusable scripting-based form, rather than an annoyingly fixed binary. Because Lua compiled for C++ might be hard to find, we provide a wrap. Curiously, only GitHub releases seem to contain onelua.c, which is a very handy file. We could have also subprojected libqr, which is in the public domain, however the other main dependencies are also LGPL like libqrencode is. And it is likely to be installed. The user manual also serves as a test.
241 lines
8.5 KiB
Lua
241 lines
8.5 KiB
Lua
#!/usr/bin/env lpg
|
||
local project_url = "https://git.janouch.name/p/pdf-simple-sign"
|
||
|
||
function h1 (title)
|
||
return lpg.VBox {fontsize=18., fontweight=600,
|
||
title, lpg.HLine {2}, lpg.Filler {-1, 6}}
|
||
end
|
||
function h2 (title)
|
||
return lpg.VBox {fontsize=16., fontweight=600,
|
||
lpg.Filler {-1, 8}, title, lpg.HLine {1}, lpg.Filler {-1, 6}}
|
||
end
|
||
function h3 (title)
|
||
return lpg.VBox {fontsize=14., fontweight=600,
|
||
lpg.Filler {-1, 8}, title, lpg.HLine {.25}, lpg.Filler {-1, 6}}
|
||
end
|
||
function p (...)
|
||
return lpg.VBox {..., lpg.Filler {-1, 6}}
|
||
end
|
||
function code (...)
|
||
return lpg.VBox {
|
||
lpg.Filler {-1, 4},
|
||
lpg.HBox {
|
||
lpg.Filler {12},
|
||
lpg.VBox {"<tt>" .. table.concat {...} .. "</tt>"},
|
||
lpg.Filler {},
|
||
},
|
||
lpg.Filler {-1, 6},
|
||
}
|
||
end
|
||
function define (name, ...)
|
||
return lpg.VBox {
|
||
lpg.Filler {-1, 2},
|
||
lpg.Text {fontweight=600, name}, lpg.Filler {-1, 2},
|
||
lpg.HBox {lpg.Filler {12}, lpg.VBox {...}, lpg.Filler {}},
|
||
lpg.Filler {-1, 2},
|
||
}
|
||
end
|
||
function pad (widget)
|
||
return lpg.VBox {
|
||
lpg.Filler {-1, 2},
|
||
lpg.HBox {lpg.Filler {4}, widget, lpg.Filler {}, lpg.Filler {4}},
|
||
lpg.Filler {-1, 2},
|
||
}
|
||
end
|
||
|
||
local page1 = lpg.VBox {fontfamily="sans serif", fontsize=12.,
|
||
h1("lpg User Manual"),
|
||
p("<b>lpg</b> is a Lua-based PDF document generator, exposing a trivial " ..
|
||
"layouting engine on top of the Cairo graphics library, " ..
|
||
"with manual paging."),
|
||
p("The author has primarily been using this system to typeset invoices."),
|
||
|
||
h2("Synopsis"),
|
||
p("<b>lpg</b> <i>program.lua</i> [<i>args...</i>]"),
|
||
|
||
h2("API"),
|
||
p("The Lua program receives <b>lpg</b>'s and its own path joined " ..
|
||
"as <tt>arg[0]</tt>. Any remaining sequential elements " ..
|
||
"of this table represent the passed <i>args</i>."),
|
||
|
||
h3("Utilities"),
|
||
|
||
define("lpg.cm (centimeters)",
|
||
p("Returns how many document points are needed " ..
|
||
"for the given physical length.")),
|
||
|
||
define("lpg.ntoa {number [, precision=…]\n" ..
|
||
"\t[, thousands_sep=…] [, decimal_point=…] [, grouping=…]}",
|
||
p("Formats a number using the C++ localization " ..
|
||
"and I/O libraries. " ..
|
||
"For example, the following call results in “3 141,59”:"),
|
||
code("ntoa {3141.592, precision=2,\n" ..
|
||
" thousands_sep=\" \", decimal_point=\",\", " ..
|
||
"grouping=\"\\003\"}")),
|
||
|
||
define("lpg.escape (values...)",
|
||
p("Interprets all values as strings, " ..
|
||
"and escapes them to be used as literal text—" ..
|
||
"all text within <b>lpg</b> is parsed as Pango markup, " ..
|
||
"which is a subset of XML.")),
|
||
|
||
h3("PDF documents"),
|
||
|
||
define("lpg.Document (filename, width, height [, margin])",
|
||
p("Returns a new <i>Document</i> object, whose pages are all " ..
|
||
"the same size in 72 DPI points, as specified by <b>width</b> " ..
|
||
"and <b>height</b>. The <b>margin</b> is used by <b>show</b> " ..
|
||
"on all sides of pages."),
|
||
p("The file is finalized when the object is garbage collected.")),
|
||
|
||
define("<i>Document</i>.title, author, subject, keywords, " ..
|
||
"creator, create_date, mod_date",
|
||
p("Write-only PDF <i>Info</i> dictionary metadata strings.")),
|
||
|
||
define("<i>Document</i>:show ([widget...])",
|
||
p("Starts a new document page, and renders <i>Widget</i> trees over " ..
|
||
"the whole print area.")),
|
||
|
||
lpg.Filler {},
|
||
}
|
||
|
||
local page2 = lpg.VBox {fontfamily="sans serif", fontsize=12.,
|
||
h3("Widgets"),
|
||
p("The layouting system makes heavy use of composition, " ..
|
||
"and thus stays simple."),
|
||
p("For convenience, anywhere a <i>Widget</i> is expected but another " ..
|
||
"kind of value is received, <b>lpg.Text</b> widget will be invoked " ..
|
||
"on that value."),
|
||
p("Once a <i>Widget</i> is included in another <i>Widget</i>, " ..
|
||
"the original Lua object can no longer be used, " ..
|
||
"as its reference has been consumed."),
|
||
p("<i>Widgets</i> can be indexed by strings to get or set " ..
|
||
"their <i>attributes</i>. All <i>Widget</i> constructor tables " ..
|
||
"also accept attributes, for convenience. Attributes can be " ..
|
||
"either strings or numbers, mostly only act " ..
|
||
"on specific <i>Widget</i> kinds, and are hereditary. " ..
|
||
"Prefix their names with an underscore to set them ‘privately’."),
|
||
p("<i>Widget</i> sizes can be set negative, which signals to their " ..
|
||
"container that they should take any remaining space, " ..
|
||
"after all their siblings’ requests have been satisfied. " ..
|
||
"When multiple widgets make this request, that space is distributed " ..
|
||
"in proportion to these negative values."),
|
||
|
||
define("lpg.Filler {[width] [, height]}",
|
||
p("Returns a new blank widget with the given dimensions, " ..
|
||
"which default to -1, -1.")),
|
||
define("lpg.HLine {[thickness]}",
|
||
p("Returns a new widget that draws a simple horizontal line " ..
|
||
"of the given <b>thickness</b>.")),
|
||
define("lpg.VLine {[thickness]}",
|
||
p("Returns a new widget that draws a simple vertical line " ..
|
||
"of the given <b>thickness</b>.")),
|
||
define("lpg.Text {[value...]}",
|
||
p("Returns a new text widget that renders the concatenation of all " ..
|
||
"passed values filtered through Lua’s <b>tostring</b> " ..
|
||
"function. Non-strings will additionally be escaped."),
|
||
define("<i>Text</i>.fontfamily, fontsize, fontweight, lineheight",
|
||
p("Various font properties, similar to their CSS counterparts."))),
|
||
define("lpg.Frame {widget}",
|
||
p("Returns a special container widget that can override " ..
|
||
"a few interesting properties."),
|
||
define("<i>Frame</i>.color",
|
||
p("Text and line colour, for example <tt>0xff0000</tt> for red.")),
|
||
define("<i>Frame</i>.w_override",
|
||
p("Forcefully changes the child <i>Widget</i>’s " ..
|
||
"requested width, such as to negative values.")),
|
||
define("<i>Frame</i>.h_override",
|
||
p("Forcefully changes the child <i>Widget</i>’s " ..
|
||
"requested height, such as to negative values."))),
|
||
|
||
lpg.Filler {},
|
||
}
|
||
|
||
local page3 = lpg.VBox {fontfamily="sans serif", fontsize=12.,
|
||
define("lpg.Link {target, widget}",
|
||
p("Returns a new hyperlink widget pointing to the <b>target</b>, " ..
|
||
"which is a URL. The hyperlink applies " ..
|
||
"to the entire area of the child widget. " ..
|
||
"It has no special appearance.")),
|
||
define("lpg.HBox {[widget...]}",
|
||
p("Returns a new container widget that places children " ..
|
||
"horizontally, from left to right."),
|
||
p("If any space remains after satisfying the children widgets’ " ..
|
||
"requisitions, it is distributed equally amongst all of them. " ..
|
||
"Also see the note about negative sizes.")),
|
||
define("lpg.VBox {[widget...]}",
|
||
p("Returns a new container widget that places children " ..
|
||
"vertically, from top to bottom.")),
|
||
define("lpg.Picture {filename}",
|
||
p("Returns a new picture widget, showing the given <b>filename</b>, " ..
|
||
"which currently must be in the PNG format. " ..
|
||
"Pictures are rescaled to fit, but keep their aspect ratio.")),
|
||
define("lpg.QR {contents, module}",
|
||
p("Returns a new QR code widget, encoding the <b>contents</b> " ..
|
||
"string using the given <b>module</b> size. " ..
|
||
"The QR code version is chosen automatically.")),
|
||
|
||
h2("Examples"),
|
||
p("See the source code of this user manual " ..
|
||
"for the general structure of scripts."),
|
||
|
||
h3("Size distribution and composition"),
|
||
lpg.VBox {
|
||
lpg.HLine {},
|
||
lpg.HBox {
|
||
lpg.VLine {}, lpg.Frame {_w_override=lpg.cm(3), pad "3cm"},
|
||
lpg.VLine {}, lpg.Frame {pad "Measured"},
|
||
lpg.VLine {}, lpg.Frame {_w_override=-1, pad "-1"},
|
||
lpg.VLine {}, lpg.Frame {_w_override=-2, pad "-2"},
|
||
lpg.VLine {},
|
||
},
|
||
lpg.HLine {},
|
||
},
|
||
lpg.Filler {-1, 6},
|
||
code([[
|
||
<small><b>function</b> pad (widget)
|
||
<b>local function</b> f (...) <b>return</b> lpg.Filler {...} <b>end</b>
|
||
<b>return</b> lpg.VBox {f(-1, 2), lpg.HBox {f(4), w, f(), f(4)}, f(-1, 2)}
|
||
<b>end</b>
|
||
|
||
lpg.VBox {lpg.HLine {}, lpg.HBox {
|
||
lpg.VLine {}, lpg.Frame {_w_override=lpg.cm(3), pad "3cm"},
|
||
lpg.VLine {}, lpg.Frame {pad "Measured"},
|
||
lpg.VLine {}, lpg.Frame {_w_override=-1, pad "-1"},
|
||
lpg.VLine {}, lpg.Frame {_w_override=-2, pad "-2"},
|
||
lpg.VLine {},
|
||
}, lpg.HLine {}}</small>]]),
|
||
|
||
h3("Clickable QR code link"),
|
||
lpg.HBox {
|
||
lpg.VBox {
|
||
p("Go here to report bugs, request features, " ..
|
||
"or submit pull requests:"),
|
||
code(([[
|
||
url = "%s"
|
||
lpg.Link {url, lpg.QR {url, 2.5}}]]):format(project_url)),
|
||
},
|
||
lpg.Filler {},
|
||
lpg.Link {project_url, lpg.QR {project_url, 2.5}},
|
||
},
|
||
|
||
lpg.Filler {},
|
||
}
|
||
|
||
if #arg < 1 then
|
||
io.stderr:write("Usage: " .. arg[0] .. " OUTPUT-PDF..." .. "\n")
|
||
os.exit(false)
|
||
end
|
||
local width, height, margin = lpg.cm(21), lpg.cm(29.7), lpg.cm(2.0)
|
||
for i = 1, #arg do
|
||
local pdf = lpg.Document(arg[i], width, height, margin)
|
||
pdf.title = "lpg User Manual"
|
||
pdf.subject = "lpg User Manual"
|
||
pdf.author = "Přemysl Eric Janouch"
|
||
pdf.creator = ("lpg (%s)"):format(project_url)
|
||
|
||
pdf:show(page1)
|
||
pdf:show(page2)
|
||
pdf:show(page3)
|
||
end
|