%% florilegium.sty -- a procedurally generated page margin, drawn by Lua: plants, their %% visitors, shells and Gothic tracery, each sampled from a genome %% https://github.com/kevinraymond/florilegium %% Copyright (c) 2026 Kevin Raymond. MIT License, in full at the end of these notes, for %% every file of florilegium but florilegium-pgfmath.lua, which reimplements part of pgf and %% is under the LaTeX Project Public License 1.3c, as its header says. %% %% LuaLaTeX only. The geometry of every petal, leaf and stem is computed in Lua %% (florilegium-ink.lua, florilegium-flora.lua, florilegium-native.lua) and written straight %% into the page as PDF path operators; TeX does none of the drawing's arithmetic. A page %% takes a few seconds. %% %% Usage %% \usepackage{florilegium} authored composition (hand-placed, florilegium-authored.lua) %% \usepackage[grown]{florilegium} composition grown to fit the page (florilegium-grow.lua), %% each main stem a plant of its own species, sampled %% from a genome (florilegium-species.lua), four to a %% page from a pool of eight per document %% \usepackage[nomargin]{florilegium} no margin, only \florilegiumdraw %% \usepackage[grown,novisitors]{florilegium} no visitors (insects, snails, birds) %% \usepackage[grown,noshells]{florilegium} no shells on the margin's ground %% \usepackage[grown,sections]{florilegium} a flower beside every numbered \section %% and \subsection (standard classes) %% \usepackage[grown,headpieces]{florilegium} a headpiece of Gothic tracery over every %% \section, a vine up its jamb from the margin %% \usepackage[grown,aging]{florilegium} the garden ages from spring on the first %% page to autumn on the last (two runs: the page %% count is read from the .aux of the run before) %% \usepackage[grown,theme=geometric]{florilegium} v1.3's garden cut from flat shapes %% with straight edges (florilegium-theme-geometric.lua) %% \usepackage[grown,theme=math]{florilegium} no plant: figures, symbols and equations %% cascading down the margin (florilegium-theme-math.lua) %% \usepackage[grown,theme=shells]{florilegium} no plant: shells among strands of wrack %% (florilegium-theme-shells.lua) %% \usepackage[grown,density=0.4]{florilegium} less in the margin: 1 is full, 0.05 a %% single vine %% \usepackage[intensity=0.5]{florilegium} a paler margin: 1 as painted, 0.3 faint %% \florilegiumbloom[motif] (grown) a flower, or any motif of florilegium-grow.lua, in %% the margin beside the current line %% \florilegiumage{a} (grown) the age of the following pages: 0 spring, %% 0.5 summer, 1 autumn %% \florilegiumtheme{name} the theme from the page this stands on (flora: %% none); in the preamble, for the whole document %% \florilegiumoff, \florilegiumon no margin from the page this stands on, and the %% margin again; in the preamble, from the first page %% \florilegiumhide no margin on the page this stands on (in a float: %% the page the float lands on) %% \florilegiumhide[1,3,5-8] no margin on those pages of the PDF, counted from 1 %% \florilegiuminitial[lines]{L} at the start of a paragraph: the letter L as a %% decorated initial, a tile `lines' lines tall %% (default 4), the text wrapped around it %% \florilegiuminitialfont{file.otf} the OpenType font the initial's outline is read %% from (default lmroman10-bold.otf) %% \def\florilegiumseed{7} before \usepackage: a fixed seed (any positive %% integer) instead of the page-number seed; on the %% command line: lualatex "\def\florilegiumseed{7}\input{doc}" %% \florilegiumtextend at the very end of the text (grown only): the %% garden then also fills the space below it %% \florilegiumframe[explain]{k}{n} grown only: the following pages show frame k of %% n of their garden's growth (animation.tex) %% \definecolor{ink}{HTML}{...} after loading: the hue of the whole palette %% \definecolor{accent}{HTML}{...} the copper of the hairline accents %% \florilegiumornament[size=1.5em,ink=5B2A1F,angle=10,seed=random]{leaf} %% one primitive in the text, sized like a letter %% (default 1em); each one in a document differs, %% seed=random gives a new shape on every build %% (a tagged PDF: alt={...} or actualtext={...}) %% \florilegiumdraw{flower}{1.2} any primitive at the origin of the current TikZ %% scope; see florilegium-flora.lua for the list and options, %% e.g. \florilegiumdraw{leaf}{2.0, {depth=0.6}}; %% with a theme its primitives too, e.g. {rose}{1.5} %% %% The garden grows in the wider side margin: in a two-sided document (twoside, %% a wide outer margin) it changes sides with the page and is drawn mirrored. %% %% MIT License %% %% Copyright (c) 2026 Kevin Raymond %% %% Permission is hereby granted, free of charge, to any person obtaining a copy %% of this software and associated documentation files (the "Software"), to deal %% in the Software without restriction, including without limitation the rights %% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell %% copies of the Software, and to permit persons to whom the Software is %% furnished to do so, subject to the following conditions: %% %% The above copyright notice and this permission notice shall be included in all %% copies or substantial portions of the Software. %% %% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR %% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, %% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE %% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER %% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, %% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE %% SOFTWARE. %% \NeedsTeXFormat{LaTeX2e}[2020-10-01] \ProvidesPackage{florilegium}[2026/11/17 v2.1.0 procedural page margin, Lua-drawn] \ifdefined\directlua\else \PackageError{florilegium}{florilegium needs LuaLaTeX}{Compile with lualatex.}\endinput\fi \RequirePackage{tikz} \RequirePackage{eso-pic} \newif\ifflorilegium@grown \newif\ifflorilegium@margin \florilegium@margintrue \newif\ifflorilegium@visitors \florilegium@visitorstrue \newif\ifflorilegium@shells \florilegium@shellstrue \newif\ifflorilegium@sections \newif\ifflorilegium@headpieces \newif\ifflorilegium@aging \DeclareOption{authored}{\florilegium@grownfalse} \DeclareOption{grown}{\florilegium@growntrue} \DeclareOption{nomargin}{\florilegium@marginfalse} \DeclareOption{novisitors}{\florilegium@visitorsfalse} \DeclareOption{noshells}{\florilegium@shellsfalse} \DeclareOption{sections}{\florilegium@sectionstrue} \DeclareOption{headpieces}{\florilegium@headpiecestrue} \DeclareOption{aging}{\florilegium@agingtrue} %% key=value options: theme=, density=<0..1>, intensity=<0..1> \def\florilegium@theme{} \DeclareOption*{\expandafter\florilegium@option\CurrentOption==\@nil} \def\florilegium@option#1=#2=#3\@nil{% \ifcsname florilegium@set@#1\endcsname\csname florilegium@set@#1\endcsname{#2}% \else\PackageWarning{florilegium}{Unknown option `\CurrentOption'}\fi} \def\florilegium@set@theme#1{\def\florilegium@theme{#1}} \def\florilegium@set@density#1{\def\florilegium@density{#1}} \def\florilegium@set@intensity#1{\def\florilegium@intensity{#1}} \ProcessOptions\relax \ifdefined\florilegiumseed\else\def\florilegiumseed{}\fi %% ---------------------------------------------------------------- palette %% `ink` gives the hue and saturation; the ramp from navy to mist is derived %% from it in OKLCH (florilegium-ink.lua). `accent` is used for the fine copper lines. \definecolor{ink}{HTML}{2456C4} \definecolor{accent}{HTML}{B4662F} \directlua{florilegium = require("florilegium")} %% Every Lua file of a release carries its version, and florilegium.lua compares them %% and this file's \ProvidesPackage as it loads. A florilegium.lua from before that %% has no version at all, so this file says so itself. \directlua{if not florilegium.version then tex.error("florilegium: florilegium.lua is from an earlier release than florilegium.sty", {"Copy florilegium.sty and every florilegium*.lua from one release."}) end} \ifflorilegium@visitors\else\directlua{florilegium.visitors = false}\fi \ifflorilegium@shells\else\directlua{florilegium.shells = false}\fi %% a number that is not one warns in the log and takes the default (florilegium.lua: number) \ifdefined\florilegium@density \directlua{florilegium.density = florilegium.number("density", "\luaescapestring{\florilegium@density}", 1)}\fi \ifdefined\florilegium@intensity \directlua{florilegium.intensity = florilegium.number("intensity", "\luaescapestring{\florilegium@intensity}", 1)}\fi %% the theme: in the preamble for the whole document; in the text a mark, so that %% the theme changes from the page that the mark is on (florilegium.lua) \newcommand\florilegiumtheme[1]{% \ifx\@nodocument\relax\directlua{florilegium.mark("theme", "\luaescapestring{#1}")}% \else\directlua{florilegium.theme = "\luaescapestring{#1}"}\fi} \ifx\florilegium@theme\@empty\else\expandafter\florilegiumtheme\expandafter{\florilegium@theme}\fi %% the margin off and on: in the preamble from the first page; in the text a mark, as the %% theme's, so that the margin stops or starts with the page that the mark is on. The option %% nomargin installs no margin at all, so there is nothing to switch \def\florilegium@switch#1{\ifflorilegium@margin \ifx\@nodocument\relax\directlua{florilegium.mark("margin", "#1")}% \else\directlua{florilegium.margin = "#1" == "on"}\fi\fi} \newcommand\florilegiumoff{\florilegium@switch{off}} \newcommand\florilegiumon{\florilegium@switch{on}% \ifflorilegium@margin\else\PackageWarning{florilegium}{% \string\florilegiumon\space has no margin to turn on, since the option nomargin is set}\fi} %% one page without its margin: a mark on the page itself (in the preamble, the first page), %% or with an argument the pages of the PDF by their number, counted from 1 whatever the %% page numbers say, as 1,3,5-8 \newcommand\florilegiumhide[1][]{\ifflorilegium@margin \if\relax\detokenize{#1}\relax \ifx\@nodocument\relax\directlua{florilegium.mark("hide", "")}% \else\directlua{florilegium.hide("1")}\fi \else\directlua{florilegium.hide("\luaescapestring{#1}")}\fi\fi} %% pass the current colors to Lua, whether the pages are two-sided, and the sheet's number \def\florilegium@twoside{\directlua{florilegium.sheet = \number\ReadonlyShipoutCounter; florilegium.twoside = \if@twoside true\else false\fi}} \def\florilegium@colors{% \extractcolorspecs{ink}{\flo@colm}{\flo@cols}\convertcolorspec{\flo@colm}{\flo@cols}{rgb}\flo@ink \extractcolorspecs{accent}{\flo@colm}{\flo@cols}\convertcolorspec{\flo@colm}{\flo@cols}{rgb}\flo@accrgb \directlua{florilegium.colors(\flo@ink, \flo@accrgb)}} %% one primitive inside a tikzpicture, under the current transformation \newcommand\florilegiumdraw[2]{\florilegium@colors\directlua{florilegium.draw("#1", #2)}} %% tagged PDF (\DocumentMetadata{tagging=on}): what is drawn in the text is decoration %% (\florilegium@artifact) unless it is given a structure of its own (\florilegium@tagged, %% its first argument the structure's keys: an ornament with alt or actualtext). The margin %% needs neither, since LaTeX marks what the shipout hook draws as decoration. %% \florilegium@iftagging asks the kernel whether tagging is on, and not paused, here; the %% tagging commands exist whenever a document has \DocumentMetadata, tagging on or off. TeX %% Live 2023 without \DocumentMetadata has no \tag_if_active: either, and draws as before. %% An artifact group marks its contents as decoration and pauses tagging inside, so a %% headpiece's paragraph makes no empty paragraph in the structure. \ExplSyntaxOn \cs_new_protected:Npn \florilegium@iftagging #1#2 { \cs_if_exist:NTF \tag_if_active:TF { \tag_if_active:TF { #1 } { #2 } } { #2 } } \cs_new_protected:Npn \florilegium@artifact #1 { \florilegium@iftagging { \tag_mc_artifact_group_begin:n { } #1 \tag_mc_artifact_group_end: } { #1 } } \cs_new_protected:Npn \florilegium@tagged #1#2 { \florilegium@iftagging { \tag_mc_end_push: \tag_struct_begin:n { #1 } \tag_mc_begin:n { } #2 \tag_mc_end: \tag_struct_end: \tag_mc_begin_pop:n { } } { #2 } } \ExplSyntaxOff %% one primitive in the text, in a box the size of a letter (florilegium.lua): %% \florilegiumornament{leaf}, \florilegiumornament[size=2em,ink=5B2A1F,angle=20,seed=random]{flower}. %% In a tagged PDF it is decoration, a figure with alt={an ivy leaf}, or a span that reads %% as text with actualtext={*} (alt wins when both are given) \newdimen\flo@orn@size \pgfqkeys{/florilegium/ornament}{ size/.store in=\flo@orn@sz, size=1em, ink/.store in=\flo@orn@ink, ink=, accent/.store in=\flo@orn@acc, accent=, angle/.store in=\flo@orn@angle, angle=0, seed/.store in=\flo@orn@seed, seed=, alt/.store in=\flo@orn@alt, alt=, actualtext/.store in=\flo@orn@text, actualtext=} \newcommand\florilegiumornament[2][]{\leavevmode\begingroup \pgfqkeys{/florilegium/ornament}{#1}% \flo@orn@size=\flo@orn@sz\relax \florilegium@colors \def\flo@orn@box{\hbox to\flo@orn@size{\directlua{florilegium.ornament("\luaescapestring{#2}", \number\flo@orn@size, "\luaescapestring{\flo@orn@ink}", "\luaescapestring{\flo@orn@acc}", florilegium.number("angle", "\luaescapestring{\flo@orn@angle}", 0), "\luaescapestring{\flo@orn@seed}")}% \hss\vrule height .85\flo@orn@size depth .15\flo@orn@size width 0pt}}% \ifx\flo@orn@alt\@empty \ifx\flo@orn@text\@empty \florilegium@artifact{\flo@orn@box}% \else \florilegium@tagged{tag=Span, actualtext={\flo@orn@text}}{\flo@orn@box}\fi \else \florilegium@tagged{tag=Figure, alt={\flo@orn@alt}}{\flo@orn@box}% \fi \endgroup} %% a headpiece of Gothic tracery across the text (florilegium-tracery.lua), its sill on %% the baseline, the k-th of the document unless a seed is given. With the margin on it %% is drawn at shipout, from a mark, with a vine up the jamb on the margin's side and a %% branch from the margin to the vine's foot: \florilegiumheadpiece, %% \florilegiumheadpiece[seed=7,width=10cm,traits={period=perpendicular},vine=none] %% (vine: auto, the margin's side; left, right, none). Option headpieces sets one over %% every \section, after the space above it and kept with its title (standard classes) \newdimen\flo@hp@width \pgfqkeys{/florilegium/headpiece}{ seed/.store in=\flo@hp@seed, seed=, role/.store in=\flo@hp@role, role=headpiece, width/.store in=\flo@hp@w, width=\linewidth, traits/.store in=\flo@hp@traits, traits=, vine/.store in=\flo@hp@vine, vine=auto} \newcommand\florilegiumheadpiece[1][]{\par\begingroup \pgfqkeys{/florilegium/headpiece}{#1}% \flo@hp@width=\flo@hp@w\relax \florilegium@colors \florilegium@artifact{\noindent\hbox to\flo@hp@width{\def\flo@hp@height{0pt}\directlua{florilegium.headpiece("\luaescapestring{\flo@hp@seed}", "\luaescapestring{\flo@hp@role}", \number\flo@hp@width, "\luaescapestring{\flo@hp@traits}", "\luaescapestring{\flo@hp@vine}", \ifflorilegium@margin true\else false\fi)}% \hss\vrule height \flo@hp@height depth 0pt width 0pt}\par}% \endgroup} \ifflorilegium@headpieces % \@startsection knows the level; \@sect and \@ssect (starred) set the title after % its space above, so the headpiece goes in front of them, and nothing may break % between it and the title \def\flo@hp@level{0} \def\flo@hp@before{\ifnum\flo@hp@level=1 \florilegiumheadpiece\nobreak\vskip.4\baselineskip\nobreak\fi} \AtBeginDocument{% \let\flo@hp@start\@startsection \def\@startsection#1#2{\def\flo@hp@level{#2}\flo@hp@start{#1}{#2}}% \let\flo@hp@sect\@sect \def\@sect{\flo@hp@before\flo@hp@sect}% \let\flo@hp@ssect\@ssect \def\@ssect{\flo@hp@before\flo@hp@ssect}} \fi %% ---------------------------------------------------------------- page seed \def\florilegium@seed{% \directlua{tex.sprint(florilegium.seed(\number\value{page}\ifx\florilegiumseed\@empty\else, florilegium.number("\string\\florilegiumseed", "\luaescapestring{\florilegiumseed}", nil, "the page's own seed")\fi))}} %% ---------------------------------------------------------------- compositions \newcommand\florilegium@authoredgarden{% \begin{tikzpicture}[overlay] \florilegium@colors\florilegium@twoside \edef\flo@seed{\florilegium@seed}% \directlua{florilegium.authored(\flo@seed, \number\ShipoutBox)}% \end{tikzpicture}} %% where the text ends, measured in the same pass: \pagetotal is the height of %% the material already on the current page \def\flo@endpage{-1}\def\flo@endtotal{0pt} \newcommand\florilegium@growngarden{% \begin{tikzpicture}[overlay] \florilegium@colors\florilegium@twoside \edef\flo@seed{\florilegium@seed}% % aging: the sheet's place among all the sheets of the last run, whatever the page numbers \ifflorilegium@aging\ifnum\PreviousTotalPages>0 \directlua{florilegium.auto_age(\number\ReadonlyShipoutCounter, \PreviousTotalPages)}\fi\fi \ifnum\value{page}=\flo@endpage\relax \directlua{florilegium.grown(\flo@seed, 1, florilegium.geometry().ytop - \number\dimexpr\flo@endtotal\relax * 2.54 / (72.27 * 65536), \number\ShipoutBox)}% \else \directlua{florilegium.grown(\flo@seed, 0, 0, \number\ShipoutBox)}% \fi \end{tikzpicture}} \newcommand\florilegiumtextend{\par \xdef\flo@endpage{\number\value{page}}% \xdef\flo@endtotal{\the\dimexpr\pagetotal+\pagedepth\relax}} %% the margin follows the text (grown only): a whatsit marks the line, and the %% shipout hook finds it in the page box (florilegium.lua) \newcommand\florilegiumbloom[1][]{\directlua{florilegium.mark("bloom", "\luaescapestring{#1}")}} \protected\def\florilegium@headmark#1{\ifnum#1<3 \directlua{florilegium.mark("heading", \number#1)}\fi} \ifflorilegium@sections % standard classes build every heading with \@sect; its last argument is the % text that is typeset (the TOC and marks get the optional one), so the mark % goes there, after the number \AtBeginDocument{% \let\flo@sect\@sect \def\@sect#1#2#3#4#5#6[#7]#8{\flo@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}]{\florilegium@headmark{#2}#8}}} \fi \newcommand\florilegiumage[1]{\directlua{florilegium.age = florilegium.number("\string\\florilegiumage", "\luaescapestring{#1}", nil, "no age")}} %% a decorated initial: a square tile from the cap height of the first line to %% the baseline of line #1, the paragraph's first #1 lines indented beside it \newdimen\flo@ini@tile \newdimen\flo@ini@cap \newcommand\florilegiuminitial[2][4]{\par \global\flo@ini@cap=\fontcharht\font`\H \global\flo@ini@tile=\dimexpr\baselineskip*\numexpr#1-1\relax+\flo@ini@cap\relax \hangindent=\dimexpr\flo@ini@tile+0.6em\relax \hangafter=-#1\relax \noindent\florilegium@colors \florilegium@artifact{\directlua{florilegium.initial("\luaescapestring{\csname text_purify:n\endcsname{#2}}", \number\flo@ini@tile, \number\hangindent, \number\flo@ini@cap)}}% \llap{\directlua{florilegium.hidden(true)}#2\directlua{florilegium.hidden(false)}}% \ignorespaces} \newcommand\florilegiuminitialfont[1]{\directlua{florilegium.initial_font = "\luaescapestring{#1}"}} %% the tile's frame from here on: plain (a square), or arch (a cusped arch of tracery) \newcommand\florilegiuminitialframe[1]{\directlua{florilegium.initial_frame = "\luaescapestring{#1}"}} \ifflorilegium@aging % the kernel records the number of sheets in the .aux, and the next run reads it back % (\PreviousTotalPages); after the last sheet, a run whose count changed asks for another \AddToHook{enddocument/afterlastpage}{% \ifnum\PreviousTotalPages=\ReadonlyShipoutCounter\else \PackageWarningNoLine{florilegium}{The page count changed. Rerun to get the aging right}\fi} \fi %% growth animation (grown only; animation.tex, tools/animate.py): the pages %% that follow show frame #2 of #3 of their garden's growth; the option %% [explain] also marks the free disc that each branch grows to \newcommand\florilegiumframe[3][]{\directlua{florilegium.frame(#2, #3, "#1")}} %% ---------------------------------------------------------------- plumbing \ifflorilegium@margin \ifflorilegium@grown \AddToShipoutPictureBG{\AtPageLowerLeft{\put(-\hoffset,\voffset){\florilegium@growngarden}}} \else \AddToShipoutPictureBG{\AtPageLowerLeft{\put(-\hoffset,\voffset){\florilegium@authoredgarden}}} \fi \fi \endinput