% \iffalse meta-comment
%
% Copyright (C) 2025 Alan J. Cain
%
% This file may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version
% 1.3c of this license or (at your option) any later version. The latest version of this license is in:
%
% http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX version 2008-05-04 or later.
%
% \fi
%
% \iffalse
%<*driver>
\PassOptionsToPackage{inline}{enumitem}
\documentclass{l3doc}
\makeatletter
\ExplSyntaxOn
\cs_gset:Npn \l@subsection { \@dottedtocline{2}{2.5em}{2.8em} } % #2 = 1.5em
\cs_gset:Npn \l@subsubsection { \@dottedtocline{3}{5.3em}{3.5em} } % #2 = 1.5em
\cs_gset:Npn \l@paragraph { \@dottedtocline{4}{8.8em}{3.2em} } % #2 = 1.5em
\ExplSyntaxOff
\makeatother
\usepackage{xcolor}
\definecolor{linkcolor}{rgb}{0.0,0.4,0.7}
\colorlet{citecolor}{linkcolor}
\colorlet{urlcolor}{linkcolor}
\hypersetup{
linkcolor=linkcolor,%
citecolor=citecolor,%
urlcolor=urlcolor,%
}
\newcommand*\fullref[2]{%
\hyperref[#2]{#1\penalty 200\ \ref*{#2}}%
}
\setcounter{tocdepth}{7}
\numberwithin{figure}{section}
\usepackage{marginalia}
\marginaliasetup{
ysep=0pt,
ysep page top=10mm,
ysep page bottom=5mm,
}
\renewcommand*\marginpar[1]{\marginalia[pos=left]{#1}}
\usepackage{titleps}
\newpagestyle{sideheadings}[\normalfont]{
\sethead{%
\smash{%
\marginalia[
pos=left,
valign=b,
yshift={-\topskip-2\baselineskip},
type=optfixed,
xsep=2em,
ysep={2\baselineskip},
column=one,
width=40mm,
]{%
\raggedleft
\itshape
\large
\sectiontitle
}%
}%
}
{}
{}
\setfoot{}
{\thepage}
{}
}
\usepackage{booktabs}
\usepackage{graphicx}
\newlist{vallist}{description}{1}
\setlist[vallist]{
leftmargin=3em,
style=unboxed,
labelsep=1em,
font=\descriptionitemcolon,
nosep,
}
\newcommand*{\descriptionitemcolon}[1]{\kern 1em #1:}
\usepackage{siunitx}
\sisetup{
mode=match,
}
\DeclareSIUnit\inch{in}
\DeclareSIUnit\point{pt}
\usepackage{tikz}
\usetikzlibrary{decorations.pathmorphing}
\newrobustcmd*\examplelabel[1]{%
\smash{%
\begin{tikzpicture}[baseline=(labelnode.base)]
\node[node font=\sffamily\footnotesize] (labelnode) at (0,0) {#1};
\draw[gray] (labelnode.center) circle (5pt);
\end{tikzpicture}%
}%
}
\usepackage{mathtools}
\DeclarePairedDelimiter{\abs}{\lvert}{\rvert}
\DeclarePairedDelimiter{\set}{\lbrace}{\rbrace}
\newcommand*\key[1]{\texttt{#1}}
\newcommand*\val[1]{\texttt{#1}}
\newcommand*\keyvalue[2]{\texttt{#1=#2}}
\NewDocumentCommand{\default}{ m }{(\textit{Default:} #1)}
\newcommand*\luafunc[1]{\texttt{#1}}
\newcommand*\luavar[1]{\texttt{#1}}
\usepackage{listings}
\lstset{
language=[LaTeX]TeX,
basicstyle=\small\ttfamily,
basewidth=0.5em,
}
\newcounter{sidenote}
\newcommand*\sidenote[1]{%
\stepcounter{sidenote}%
\textsuperscript{\thesidenote}%
\marginalia[
pos=left,
style={\raggedright\footnotesize},
width=33mm,
xsep=1em,
]{%
\leavevmode\strut\llap{\thesidenote~}#1\strut%
}%
}
\begin{document}
\DocInput{\jobname.dtx}
\PrintIndex
\end{document}
%</driver>
% \fi
%
%
%
% \GetFileInfo{marginalia.sty}
%
%
%
% \title{^^A
% \pkg{marginalia} ^^A
% --- Non-floating marginal content with automatic placement for Lua\LaTeX^^A
% \thanks{This file describes \fileversion, last revised \filedate.}^^A
% }
%
% \author{^^A
% Alan J. Cain^^A
% }
%
% \date{Released \filedate}
%
% \maketitle
%
%
%
% \begin{abstract}
% This Lua\LaTeX\ package allows the placement of marginal content anywhere, without \cs{marginpar}'s limits, and
% automatically adjusts positions to prevent overlaps or content being pushed off the page. In short, it tries to
% combine the best features from the packages \pkg{marginnote}, \pkg{marginfix} and \pkg{marginfit} with key--value
% settings that allow fine-grained customization.
% \end{abstract}
%
%
%
% \tableofcontents
%
%
%
% \begin{documentation}
%
%
%
% \section{Introduction}
% \pagestyle{sideheadings}
%
% The \LaTeX\ \cs{marginpar} command is the basic method for placing content in the margin. For purposes such as drawing
% attention to particular points in the text, it functions well. Its main limitation is that \cs{marginpar} works via
% the \LaTeX\ float mechanism and so cannot be used to create marginal content next to a figure, table, or other float,
% or next to a footnote, or to place running heads in the margin, such as are found in the left-hand margin of this
% document except for the `implementation' section. (Bringhurst called this style `running shoulder\-heads'
% \cite[p.~65]{bringhurst_elements}, but the term may be non-standard.)
%
% Trying to set many separate pieces of marginal content using \cs{marginpar} can lead to other problems. If two
% \texttt{marginpar}s would clash, \LaTeX\ shifts the second item downward. But the cumulative effect can lead to
% \texttt{marginpar}s being shifted downward off the bottom of the page. Further, the asynchronous nature of \TeX's
% page-breaking can cause:
% \begin{enumerate*}[label={(\arabic*)}]
% \item a \texttt{marginpar} to be placed in the wrong margin;
% \item the topmost \texttt{marginpar} on a page to be unnecessarily shifted downward because of a hypothetical clash
% that would have occured with the previous \texttt{marginpar}, had they been on the same page.
% \end{enumerate*}
%
% Packages like \pkg{mparhack}\sidenote{\textsc{url:} \url{https://ctan.org/pkg/mparhack}} (Tom Sgouros \& Stefan
% Ulrich), \pkg{marginnote}\sidenote{\textsc{url}: \url{https://ctan.org/pkg/marginnote}} (Markus Kohm),
% \pkg{marginfix}\sidenote{\textsc{url:} \url{https://ctan.org/pkg/marginfix}} (Stephen Hicks) and
% \pkg{marginfit}\sidenote{\textsc{url:} \url{https://ctan.org/pkg/marginfit}} (Maurice Leclaire) were created to avoid
% these limitations and problems. \pkg{mparhack} only ensures that each \texttt{marginpar} appears on the correct side
% of the page. \pkg{marginnote} allows marginal content to be placed anywhere, but does not adjust positions to avoid
% clashes. \pkg{marginfix} adjusts positions, but the unadjusted vertical positioning can be slightly off, and the
% package still uses floats. \pkg{marginfit} gets positions exactly right, but uses the insert mechanism and so marginal
% content cannot appear next to floats or footnotes.
%
% This Lua\LaTeX\ package, \pkg{marginalia}, provides a \cs{marginalia} command that attempts to avoid these
% limitations. Marginal content is placed, not via floats or inserts, but by a calculated per-item horizontal shift
% inside an (invisible) \cs{rlap} or \cs{llap} from the position where the \cs{marginalia} command was issued (which is
% similar to the technique used by \pkg{marginnote}), plus a calculated per-item vertical shift to avoid clashes with
% other content. The vertical shift is usually downward, but may be upward when necessary to prevent content from being
% shifted off the bottom of the page (which is similar to the vertical shifts performed by \pkg{marginfix} and
% \pkg{marginfit}).
%
% The calculation of the horizontal and vertical shifts uses information written to the \file{.aux} file during the
% previous Lua\LaTeX\ run. It thus takes at least two runs for all content to appear in the correct places. The package
% reports any changes from the previous run and any problems encountered.
%
% \bigskip
%
% \noindent\emph{Caveat:} \pkg{marginalia} was written to typeset running heads in the margin, sidenote references,
% side-captions for floats, and small marginal figures in the author's book \textit{Form \& Number: A History of
% Mathematical Beauty} \cite{cain_formandnumber_ebook_large}.\sidenote{\textit{Form \& Number} is freely available on
% the Internet Archive under a Creative Commons licence.
% \textsc{url}:~\url{https://archive.org/details/cain_formandnumber_ebook_large}} Thus the basic functionality has been
% tested extensively, and it has performed correctly.
%
%
%
% \paragraph*{Licence.} \noindent\pkg{marginalia} is released under the \LaTeX\ Project Public Licence v1.3c or
% later.\footnote{\textsc{url}: \url{https://www.latex-project.org/lppl.txt}}
%
%
%
% \section{Requirements}
%
% \pkg{marginalia} requires
% \begin{enumerate*}[label={(\arabic*)}]
% \item Lua\LaTeX,
% \item a recent \LaTeX\ kernel with \pkg{expl3} support (any kernel version since 2020-02-02 should suffice).
% \end{enumerate*}
% It does not depend on any other packages.
%
%
%
% \section{Installation}
%
% To install \pkg{marginalia} manually, run \texttt{luatex marginalia.ins} and copy \texttt{marginalia.sty} and
% \texttt{marginalia.lua} to somewhere Lua\LaTeX\ can find them.
%
%
%
% \section{Getting started}
%
% \pkg{marginalia} works `out of the box'. Load the package (there are no package options) and use the main
% \cs{marginalia} command to place marginal content. \fullref{Figure}{fig:getting-started} shows the source code for a
% small demonstration and the resulting document. \emph{The source code must be processed \textsl{twice} by Lua\LaTeX\
% for the marginal content to be placed correctly.} (See \fullref{Section}{sec:usage} for discussion of the need for
% multiple runs.)
%
% \begin{figure}[t]
% \lstinputlisting{marginalia-doc-example.tex}
% \begin{tikzpicture}
% \pgfmathsetmacro{\s}{(\textwidth+.4pt)/210mm}
% \pgfmathsetlengthmacro{\w}{\s*210mm}
% \pgfmathsetlengthmacro{\h}{\s*100mm}
% \path[save path=\outline] (0,0) -| ++(\w,-\h) -| cycle;
% \begin{scope}
% \clip[use path=\outline];
% \node[anchor=north west,inner sep=0] at (0,0) {\includegraphics[scale=\s]{marginalia-doc-example.pdf}};
% \end{scope}
% \draw[gray,use path=\outline];
% \end{tikzpicture}
%
% \caption{A small demonstration of \pkg{marginalia}.}
% \label{fig:getting-started}
% \end{figure}
%
% Turn to \fullref{Section}{sec:commands} for a detailed description of the available user commands, and
% \fullref{Section}{sec:options} for the various options (such as \keyvalue{style}{\meta{code}}) than can be used to
% change the placement and formatting of the marginal content.
%
%
%
% \section{User commands}
% \label{sec:commands}
%
% \begin{function}{\marginalia}
% \begin{syntax}
% \cs{marginalia}\oarg{options}\marg{content}
% \end{syntax}
% This is the basic command for placing marginal content. The \meta{content} can, roughly speaking, be anything: text,
% mathematics, included graphics, Ti\textit{k}Z. The optional argument \meta{options} is a key--value list that
% specifies how the content is typeset. The keys are described in \fullref{Subsection}{sec:options}.
% \end{function}
%
%
%
% \begin{function}{\marginaliasetup}
% \begin{syntax}
% \cs{marginaliasetup}\marg{options}
% \end{syntax}
% This command is used to set options globally. The argument \meta{options} is the same kind of key--value list as the
% \meta{options} argument for the \cs{marginalia} command, and are described in \fullref{Subsection}{sec:options}.
% \end{function}
%
%
%
% \begin{function}{\marginalianewgeometry}
% \begin{syntax}
% \cs{marginalianewgeometry}
% \end{syntax}
% This command signals to \pkg{marginalia} that the page layout has been changed, for instance by using the
% \cs{newgeometry} command from the \pkg{geometry} package,\sidenote{\textsc{url}:
% \url{https://ctan.org/pkg/geometry}} or by using the \LaTeX\ command \cs{twocolumn} to switch to two-column mode. It
% should be issued immediately after such a change, and certainly before the first page with the new layout has been
% shipped out. There is no harm in using it unnecessarily.
% \end{function}
%
%
%
% \subsection{Access to page and column}
%
% Two counters available within the \meta{content} of \cs{marginalia} specify the actual page and column in which the
% call to \cs{marginalia} appears. These counters can be used to select different actions depending on the page on which
% the content appears or (in two-column mode) whether it pertains to the left or right column. It is best to use the
% variants of the \key{style} and \key{width} keys if marginal content should have different widths or styles depending
% on whether they appear on a recto/verso page or pertain to a particular column. These counters are made available for
% purposes not covered by the \key{style} and \key{width} variants.
%
% \begin{variable}{\marginaliapage}
% A counter register, available within the \meta{content} of \cs{marginalia}, that holds the actual page on which the
% marginal content appears. The value is based on the previous Lua\LaTeX\ run and will default to \(1\).
% \end{variable}
%
% \begin{variable}{\marginaliacolumn}
% A counter register, available within the \meta{content} of \cs{marginalia}, that holds the actual column to which
% the marginal content pertains. The value is \(1\) for the left column, \(2\) for the right column. In one-column
% mode, the value is always \(0\). (If the key \key{column} is used to manually specify the column to which the
% content pertains, the value of \cs{marginaliacolumn} will change accordingly.) The value is based on the previous
% Lua\LaTeX\ run and will default to \(0\).
% \end{variable}
%
%
%
% \section{Options}
% \label{sec:options}
%
% The description of keys in this section, which are summarized in \fullref{Table}{tbl:keys-summary}, should be read in
% conjunction with the discussion of how marginal content is placed in \fullref{Section}{sec:placement}. In particular,
% the variants of the keys \key{width} and \key{style} follow the terminology shown in
% \fullref{Figure}{fig:terminology}.
%
% \begin{table}[p]
% \centering
% \caption{Summary of keys that can be set using \cs{marginaliasetup} or passed in the optional argument to
% \cs{marginalia}.}
% \label{tbl:keys-summary}
% \begin{tabular}{lll}
% \toprule
% Key name & Value & Default \\
% \midrule
% \key{type} & \(\set{\val{normal},\val{fixed},\val{optfixed}}\) & \val{normal} \\
% \midrule
% \key{pos} & \parbox[t]{40mm}{\raggedright\hangindent=2em\(\set{\val{auto},\val{reverse},\val{left},\allowbreak
% \val{right},\val{nearest}}\)\strut} & \val{auto} \\
% \key{column} & \(\set{\val{auto},\val{one},\val{left},\val{right}}\) & \val{auto} \\
% \key{xsep} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep outer} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep inner} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep between} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep recto outer} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep recto inner} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep verso outer} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep verso inner} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep right between} & Dimension & \val{\cs{marginparwidth}} \\
% \key{xsep left between} & Dimension & \val{\cs{marginparwidth}} \\
% \midrule
% \key{valign} & \(\set{\val{t},\val{b}}\) & \val{t} \\
% \key{yshift} & Dimension & \qty{0}{\point} \\
% \key{ysep} & Dimension & \val{\cs{marginparpush}} \\
% \key{ysep above} & Dimension & \val{\cs{marginparpush}} \\
% \key{ysep below} & Dimension & \val{\cs{marginparpush}} \\
% \key{ysep page top} & Dimension & \val{\cs{marginparpush}} \\
% \key{ysep page top} & Dimension & \val{\cs{marginparpush}} \\
% \midrule
% \key{width} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width outer} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width inner} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width between} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width recto outer} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width recto inner} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width verso outer} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width verso inner} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width right between} & Dimension & \val{\cs{marginparwidth}} \\
% \key{width left between} & Dimension & \val{\cs{marginparwidth}} \\
% \key{style} & \LaTeX\ code & [Empty] \\
% \key{style recto outer} & \LaTeX\ code & [Empty] \\
% \key{style recto inner} & \LaTeX\ code & [Empty] \\
% \key{style verso outer} & \LaTeX\ code & [Empty] \\
% \key{style verso inner} & \LaTeX\ code & [Empty] \\
% \key{style right between} & \LaTeX\ code & [Empty] \\
% \key{style left between} & \LaTeX\ code & [Empty] \\
% \bottomrule
% \end{tabular}
% \end{table}
%
%
%
% \subsection{Type}
%
% \DescribeOption{type} The \key{type} of an item of marginal content can be set to one of the following three values:
% \begin{vallist}
% \item[\val{normal}] The vertical position of the item will be changed automatically if necessary to prevent a clash
% with another item of content.
% \item[\val{fixed}] The vertical position of the item will \emph{never} be changed automatically from the position
% specified by \key{yshift}, even if there is a clash with another item. (The type \val{fixed} was designed for
% setting float captions in the margin, since a caption should not move away from the float with which it is
% associated.)
% \item[\val{optfixed}] The vertical position of the item will \emph{never} be changed automatically from the position
% specified by \key{yshift}, even if there is a clash with another item. But an \val{optfixed} item will not appear in
% the document if it would clash with a \val{fixed} item. (The type \val{optfixed} was designed for setting running
% heads in the margin, which should not appear if they would clash with a figure caption set in the margin.)
% \end{vallist}
% \default{\val{normal}}
%
%
%
% \subsection{Horizontal placement}
%
% \DescribeOption{pos} The position in which an item of marginal content should be placed. It can be set to one of the
% the following four values:
% \begin{vallist}
% \item[\val{auto}] Place the item in the default position as described in \fullref{Section}{sec:placement}: the outer
% margin in single-column mode, and on the opposite side from the other column in two-column mode.
% \item[\val{reverse}] Place the item on the opposite side of the text block (in one-column mode) or column (in
% two-column mode) from \val{auto}.
% \item[\val{left}] The left side of the text block or column.
% \item[\val{right}] The right side of the text block of column.
% \item[\val{nearest}] The side of the text block or column nearest to which \cs{marginalia} was called.
% \end{vallist}%
% \default{\val{auto}}
%
%
% \medskip\goodbreak
%
%
% \DescribeOption{column} In two-column mode, \pkg{marginalia} tries to determine to which column an item of marginal
% content pertains using the position of the call to \cs{marginalia}. If the call is to the left of the mid-point
% between the columns, the item is assumed to pertain to the left column; otherwise, it is assumed to pertain to the
% right column. In certain situations, this might lead to undesired placement of the item. In particular, any call to
% \cs{marginalia} in a full-width float in two-column mode would be handled as if it were a call from one of the columns
% and might thus be set in the wrong place. Similarly, an overfull hbox or a piece of \cs{rlap}-ped text might carry a
% call to \cs{marginalia} from the left column text into the area of the page occupied by the right column.
%
% The key \key{column} can be used to specify which column \pkg{marginalia} should place the item in. It can be set to
% one of four values:
% \begin{vallist}
% \item[\val{auto}] Automatically determine which column an item of marginal content is placed in.
% \item[\val{one}] Treat the item as being called from one-column mode.
% \item[\val{left}] Treat the item as pertaining to the left column.
% \item[\val{right}] Treat the item as pertaining to the right column.
% \end{vallist}
% The value of \key{column} has no effect in one-column mode. \default{\val{auto}}
%
%
% \medskip\goodbreak
%
%
% \DescribeOption{xsep}
% \DescribeOption{xsep outer}
% \DescribeOption{xsep inner}
% \DescribeOption{xsep between}
% \DescribeOption{xsep recto outer}
% \DescribeOption{xsep recto inner}
% \DescribeOption{xsep verso outer}
% \DescribeOption{xsep verso inner}
% \DescribeOption{xsep right between}
% \DescribeOption{xsep left between}
% These keys specify the horizontal separation between an item of marginal content and the text block next
% to which it is placed. Which separation is used will depend on where the item is typeset. The terminology is as
% in \fullref{Figure}{fig:terminology}.
% \begin{vallist}
% \item[\key{xsep recto outer}] used for an item in the outer margin of a recto page.
% \item[\key{xsep recto inner}] used for an item in the inner margin of a recto page.
% \item[\key{xsep verso outer}] used for an item in the outer margin of a verso page.
% \item[\key{xsep verso inner}] used for an item in the inner margin of a verso page.
% \item[\key{xsep right between}] used for an item set from the right column between the columns.
% \item[\key{xsep left between}] used for an item set from the left column between the columns.
% \item[\key{xsep outer}] a shorthand for setting the keys \key{xsep recto outer} and \key{xsep verso outer}
% simultaneously to the same value.
% \item[\key{xsep inner}] a shorthand for setting the keys \key{xsep recto inner} and \key{xsep verso inner}
% simultaneously to the same value.
% \item[\key{xsep between}] a shorthand for setting the keys \key{xsep right between} and \key{xsep left between}
% simultaneously to the same value.
% \item[\key{xsep}] a shorthand for setting all of these keys simultaneously.
% \end{vallist}
% (The shorthands \key{xsep outer} and \key{xsep inner} exist because page geometry is usually symmetrical between recto
% and verso pages as regards outer and inner margins. The shorthand \key{xsep between} exists because the space between
% columns, if used at all for marginal content, will often be shared equally.) Each of these keys must be set to a valid
% dimension. \default{value of \cs{marginparsep} when the package is loaded}
%
%
%
% \subsection{Vertical placement}
%
% \DescribeOption{valign} The option \key{valign} can be either \val{t} or \val{b}. In the former case, the baseline of
% the marginal content item is the baseline of the topmost box in its contents; in the latter case, its baseline is the
% baseline of the bottommost box in its contents. (Essentially, \cs{vtop} and \cs{vbox} are used to set the two options)
% \default{\val{t}}
%
%
% \medskip\goodbreak
%
%
% \DescribeOption{yshift}
% The key \key{yshift} is used to shift the default position of the marginal content item up (positive) or
% down (negative) from its normal position, which is to have its baseline aligned with the baseline of the callout
% position. It must be set to a valid dimension. Note that if \keyvalue{type}{normal}, then the vertical
% position may be adjusted from that specified by \key{yshift}. If this is not desired, specify a different \key{type}.
% \default{0pt}.
%
%
% \medskip\goodbreak
%
%
% \DescribeOption{ysep}
% \DescribeOption{ysep above}
% \DescribeOption{ysep below}
% \DescribeOption{ysep page top}
% \DescribeOption{ysep page bottom}
% These keys specify the minimum vertical separation above and below an item of marginal content
% \begin{vallist}
% \item[\key{ysep above}] the minimum vertical separation between an item and the one above.
% \item[\key{ysep below}] the minimum vertical separation between an item and the one below.
% \item[\key{ysep page top}] the minimum vertical separation between an item and top of the page.
% \item[\key{ysep page bottom}] the minimum vertical separation between an item and bottom of the page.
% \item[\key{ysep}] is a shorthand for setting all of these keys simultaneously to the same value.
% \end{vallist}
% (See \fullref{Figure}{fig:ysep-explanation}.) Each of these keys must be set to a valid dimension. \default{value of
% \cs{marginparpush} when the package is loaded}.
%
% \begin{figure}[t]
% \centering
% \includegraphics{marginalia-doc-ysep-explanation.pdf}
% \caption{(Illustration of \key{ysep}) The length \examplelabel{1} is at least the value of \key{ysep below}
% specified (locally or globally) for marginal content item \examplelabel{A} and at least the value of \key{ysep
% above} specified for item \examplelabel{B}. In this example diagram, \examplelabel{B} has been automatically moved
% down from its natural position to maintain the required distance. Similarly, the length \examplelabel{2} is at least
% the value of \key{ysep below} specified for \examplelabel{C} and at least the value of \key{ysep above} specified
% for \examplelabel{D}, and the length \examplelabel{3} is at least the value of \key{ysep page bottom} specified for
% \examplelabel{D}. In this example, to maintain the required distances, \examplelabel{C} and \examplelabel{D} have
% been automatically moved (respectively) up and down from their natural positions.}
% \label{fig:ysep-explanation}
% \end{figure}
%
%
%
% \subsection{Appearance}
%
% An item of marginal content that appears in the inner margin might be narrower than one that appears in the outer
% margin, and an item appearing in the outer margin of a recto page might be set ragged right, while an item appearing
% in the outer margin of a verso page might be set ragged left. And since it is not known where an item will appear
% until the page is assembled, the keys in this subsection, dealing with the width and style of an item, have variants
% that apply depending on where the item appears on the page.
%
%
% \medskip\goodbreak
%
%
% \DescribeOption{width}
% \DescribeOption{width outer}
% \DescribeOption{width inner}
% \DescribeOption{width between}
% \DescribeOption{width recto outer}
% \DescribeOption{width recto inner}
% \DescribeOption{width verso outer}
% \DescribeOption{width verso inner}
% \DescribeOption{width right between}
% \DescribeOption{width left between}
% These keys specify the width of the an item of marginal content (or, more precisely, the \cs{hsize} of the box into
% which the item is typeset). Which width is chosen will depend on the where the item is typeset. The terminology is as
% in \fullref{Figure}{fig:terminology}.
% \begin{vallist}
% \item[\key{width recto outer}] used for an item in the outer margin of a recto page.
% \item[\key{width recto inner}] used for an item in the inner margin of a recto page.
% \item[\key{width verso outer}] used for an item in the outer margin of a verso page.
% \item[\key{width verso inner}] used for an item in the inner margin of a verso page.
% \item[\key{width right between}] used for an item set from the right column and placed between the columns.
% \item[\key{width left between}] used for an item set from the right column and placed between the columns.
% \item[\key{width outer}] a shorthand for setting the keys \key{width recto outer} and \key{width verso outer}
% simultaneously to the same value.
% \item[\key{width inner}] a shorthand for setting the keys \key{width recto inner} and \key{width verso inner}
% simultaneously to the same value.
% \item[\key{width between}] a shorthand for setting the keys \key{width right between} and \key{width left between}
% simultaneously to the same value.
% \item[\key{width}] a shorthand for setting all of these keys simultaneously.
% \end{vallist}
% (The shorthands \key{width outer} and \key{width inner} exist because page geometry is usually symmetrical between
% recto and verso pages as regards outer and inner margins. The shorthand \key{width between} exists because the space
% between columns, if used at all for marginal content, will often be shared equally.) Each of these keys must be set to
% a valid dimension. \default{value of \cs{marginparwidth} when the package is loaded}
%
%
% \medskip\goodbreak
%
%
% \DescribeOption{style}
% \DescribeOption{style recto outer}
% \DescribeOption{style recto inner}
% \DescribeOption{style verso outer}
% \DescribeOption{style verso inner}
% \DescribeOption{style right between}
% \DescribeOption{style left between}
% These keys specify the style with which an item of marginal content is typeset. Which style is chosen will depend on
% where the item is typeset. The terminology is as in \fullref{Figure}{fig:terminology}.
% \begin{vallist}
% \item[\key{style recto outer}] used for an item in the outer margin of a recto page.
% \item[\key{style recto inner}] used for an item in the inner margin of a recto page.
% \item[\key{style verso outer}] used for an item in the outer margin of a verso page.
% \item[\key{style verso inner}] used for an item in the inner margin of a verso page.
% \item[\key{style right between}] used for an item set from the right column between the columns.
% \item[\key{style left between}] used for an item set from the right column between the columns.
% \item[\key{style}] a shorthand for setting all of these keys simultaneously.
% \end{vallist}
% Each of these keys should be set to \LaTeX\ code that specifies the style. \default{[Empty]}
%
%
%
% \section{Placement}
% \label{sec:placement}
%
% The placement of an item of marginal content depends on where the call to \cs{marginalia} appears in the finished
% document. Both horizontal and vertical placement can be complicated.
%
%
%
% \subsection{Horizontal placement}
%
% To understand the horizontal placement, first recall some terminology: a recto page is an odd-numbered page in
% two-sided mode, or any page in one-sided mode; a verso page is an even-numbered page in two-sided mode. The
% description in the paragraphs that follow is summarized in \fullref{Figure}{fig:terminology}.
%
% \begin{figure}[t]
% \centering
% \begin{tikzpicture}[
% x={.45*\textwidth},
% y={sqrt(2)*.45*\textwidth},
% ]
%
% \begin{scope}[
% every node/.style ={
% node font=\footnotesize\scshape,
% align=center,
% }
% ]
% \begin{scope}
% \clip[decorate,decoration={snake,amplitude=1mm,segment length=5mm}] (-1,0) -- (1,0) -- (1,.5) -| cycle;
% \begin{scope}[fill=lightgray]
% \fill (-.7,-.35) rectangle (-.2,.35);
% \node at (-.45,.175) {one\\column};
% \fill (.7,-.35) rectangle (.2,.35);
% \node at (.45,.175) {one\\column};
% \end{scope}
% \end{scope}
%
% \begin{scope}
% \clip[decorate,decoration={snake,amplitude=1mm,segment length=5mm}] (-1,0) -- (1,0) -- (1,-.5) -| cycle;
% \begin{scope}[fill=lightgray]
% \fill (-.85,-.35) rectangle (-.65,.35);
% \node at (-.75,-.175) {left\\column};
% \fill (-.35,-.35) rectangle (-.15,.35);
% \node at (-.25,-.175) {right\\column};
% \fill (.35,-.35) rectangle (.15,.35);
% \node at (.25,-.175) {left\\column};
% \fill (.85,-.35) rectangle (.65,.35);
% \node at (.75,-.175) {right\\column};
% \end{scope}
% \end{scope}
%
% \end{scope}
%
% \pgfresetboundingbox
%
% \draw[white,line width=1pt,decorate,decoration={snake,amplitude=1mm,segment length=5mm}] (-1,0) -- (1,0);
%
% \draw (0,-.5) -- (0,.5);
% \draw (-1,-.5) rectangle (1,.5);
%
% \begin{scope}[
% every node/.style={
% node font=\footnotesize\ttfamily,
% inner xsep=3pt,
% }
% ]
% \node[anchor=north west,align=left] at (.7,.35) {auto\\right};
% \node[anchor=north east,align=right] at (.2,.35) {reverse\\left};
%
% \node[anchor=south east,align=right] at (.15,-.35) {auto\\left};
% \node[anchor=north,shift={(.03,0)},align=left] at (.35,-.35) {reverse\\right};
% \node[anchor=north,shift={(-.03,0)},align=right] at (.65,-.35) {reverse\\left};
% \node[anchor=south west,align=left] at (.85,-.35) {auto\\\strut\smash{right}};
%
% \node[anchor=north east,align=right] at (-.7,.35) {auto\\left};
% \node[anchor=north west,align=left] at (-.2,.35) {reverse\\right};
%
% \node[anchor=south east,align=right] at (-.85,-.35) {auto\\left};
% \node[anchor=north,shift={(.03,0)},align=left] at (-.65,-.35) {reverse\\right};
% \node[anchor=north,shift={(-.03,0)},align=right] at (-.35,-.35) {reverse\\left};
% \node[anchor=south west,align=left] at (-.15,-.35) {auto\\right};
%
% \end{scope}
%
% \begin{scope}[
% every node/.style={
% node font=\small\ttfamily,
% inner xsep=6pt,
% }
% ]
% \node[rotate=90,anchor=north] at (-1,0) {verso outer};
% \node[rotate=90,anchor=north east,align=right] at (-.65,0) {left\\[-1pt]between};
% \node[rotate=-90,anchor=north west,align=left] at (-.35,0) {right\\[-1pt]between};
% \node[rotate=-90,anchor=north] at (0,0) {verso inner};
% \node[rotate=90,anchor=north] at (0,0) {recto inner};
% \node[rotate=90,anchor=north east,align=right] at (.35,0) {left\\[-1pt]between};
% \node[rotate=-90,anchor=north west,align=left] at (.65,0) {right\\[-1pt]between};
% \node[rotate=-90,anchor=north] at (1,0) {recto outer};
% \end{scope}
%
% \end{tikzpicture}
% \caption{Summary of the positioning of marginal content using \key{pos}, and terminology used in \key{width} and
% \key{style} keys, on recto and verso pages, in both one-column and two-column mode.}
% \label{fig:terminology}
% \end{figure}
%
%
% In one-column mode, marginal content is placed by default in the outer margin: right on recto pages, left on verso
% pages. If \keyvalue{pos}{reverse} is applied, it is placed in the inner margin: left on recto pages, right on verso
% pages.
%
% In two-column mode, the default placement is next to the column in which the call to \cs{marginalia} appears, on the
% side opposite to the other column. Thus, if the call to \cs{marginalia} was in the left column, the marginal content
% item is placed by default on the left: on a recto page, the inner margin, on a verso page, the outer margin. If
% \keyvalue{pos}{reverse} is applied, it is placed between the two columns, adjacent to the left column. If the call to
% \cs{marginalia} was in the right column, the item is placed by default on the right: on a recto page, the
% outer margin, on a verso page, the inner margin. If \keyvalue{pos}{reverse} is applied, it is placed between the two
% columns, adjacent to the right column.
%
% \keyvalue{pos}{left} specifies that the item is to be placed on the left of the text block or column
% containing the call to \cs{marginalia}.
%
% \keyvalue{pos}{right} similarly specifies that the item is to be placed on the right of the text block or column
% containing the call to \cs{marginalia}.
%
% \pkg{marginalia} determines in which column the call to \cs{marginalia} was made using its horizontal position. As
% discussed in the description of key \key{column}, there are situations where this can go wrong and which
% necessitate a manual specification of a particular column.
%
%
%
% \subsection{Vertical placement}
% \label{subsec:vertical-placement}
%
% \pkg{marginalia} tries by default to place the each item of marginal content with its baseline shifted by the value of
% \key{yshift} (by default, \qty{0}{\point}) from the baseline where \cs{marginalia} was called. The actual vertical
% placement is calculated by the procedure described below, carried out for the items appearing in a particular
% horizontal location. (As shown in \fullref{Figure}{fig:terminology}, in one-column mode the possible locations are in
% outer and inner margins; in two-column mode the possible locationd are the outer and inner margins and on the left and
% right sides of the space between the columns.) A \emph{clash} exists when two items are closer than specified by
% \key{ysep below} for the upper item or \key{ysep above} for the lower item, whichever is greater.
%
% For the items in each horizontal location, the procedure is as follows:
% \begin{enumerate}
% \item Place the items appearing in a given horizontal location on the page into a list.
% \item Set the vertical shift of each item to the one specified by \key{yshift}.
% \item For each \keyvalue{type}{optfixed} item, if it clashes with any \keyvalue{type}{fixed} item, delete it from
% the list of items that appear on the page.
% \item Sort the list by the position of the call to \cs{marginalia}, top-to-bottom, left-to-right, breaking ties
% by the order of calls. (Because of floats, footnotes, etc., the sorted order of the list is not necessarily
% the same as the order of appearance of \cs{marginalia} commands in the source code.)
% \item Pass through the list of items in sorted order. For each \keyvalue{type}{normal} item, if necessary shift it
% in a negative (downward) direction so that it
% \begin{enumerate*}[label={(\arabic*)}]
% \item does not reach closer to the top of the page than specified by \texttt{ysep page top}, and
% \item does not clash with the previous (above) item.
% \end{enumerate*}
% (After this stage, it is possible for an assigned vertical shift to push a \keyvalue{type}{normal} item off
% the bottom of the page.)
% \item Pass through the list of items in the reverse of the sorted order. For each \keyvalue{type}{normal} item, if
% necessary shift it in a positive (upward) direction so that it
% \begin{enumerate*}[label={(\arabic*)}]
% \item does not reach closer to the bottom of the page than specified by \texttt{ysep page bottom}, and
% \item does not clash with the next (below) item.
% \end{enumerate*}
% \end{enumerate}
% During this process, it may be found that it is impossible to prevent clashes or items reaching beyong the limits
% (e.g. fixed items clash with each other; a fixed item conflicts with \texttt{ysep page top} or \texttt{ysep page
% bottom}, or there are simply too many items of marginal content to fit (in which case, the top of some of them will be
% above the limit specified by \texttt{ysep page top} or will clash with fixed items)). In these cases, warnings are
% issued at the end of the Lua\LaTeX\ run.
%
%
%
% \section{Usage notes}
% \label{sec:usage}
%
% \pkg{marginalia} requires a minimum of two Lua\LaTeX\ runs, and often more, to place items of marginal content
% correctly. On the first pass, information about items, including their vertical size, is written to the \file{.aux}
% file, and this information is used to position them correctly on the next run. However, because \key{width} and
% \key{style} have variants dependent on the margin in which the item is placed, an item may only be typeset at the
% correct size on this second run. Thus the vertical size of the item may have changed and so the information written to
% the \file{.aux} file on the previous run may be out of date. In this case a third run may be needed for correct
% placement.
%
% More runs may be needed if the position of the call to \cs{marginalia} changes between runs. Provided the main text
% stabilizes, the placement of items using \cs{marginalia} should be correct two runs later.
%
% At the end of the Lua\LaTeX\ run, \pkg{marginalia} reports any problems encountered in the vertical placement of items
% (as decribed at the end of \fullref{Subsection}{subsec:vertical-placement}). These problems are based on calculations
% made on the basis of information from the previous written to the \file{.aux} file on the previous run, and may not
% arise if item positions or sizes (i.e. height or depth) have changed. \pkg{marginalia} also reports any changes in
% positions or sizes compared to the previous run.
%
% In these reports, a page number refers to a visible page number if it is prefixed with `\texttt{p}'; it otherwise
% refers to the absolute page number of the output.
%
%
%
% \section{Incompatibilities}
%
% Using \pkg{marginalia} alongside \cs{marginpar} or packages like \pkg{mparhak}, \pkg{marginnote}, \pkg{marginfix}, or
% \pkg{marginfit} should not produce any errors, but \pkg{marginalia} will ignore marginal content not created using
% \cs{marginalia}; for example, an item of marginal content created using \cs{marginalia} might overlap with one created
% using \cs{marginpar}.
%
%
%
% \section{Limitations}
% \label{sec:limitations}
%
% As noted in the introduction, \pkg{marginalia} was originally written to typeset a particular kind of book. It thus
% has several limitations. Three of these are:
% \begin{description}
% \item[Lua\LaTeX only] Most of the code for deciding the placement of items of marginal content is written in Lua.
% In principle, the it could be replaced with a pure \LaTeX\ solution.
% \item[No support for `moving past' fixed items] The adjustment of vertical positions will never cause a
% \keyvalue{type}{normal} item to be shifted past a \keyvalue{type}{fixed} one, even when there is space on
% the other side. It may be desirable to have this available as an option.
% \item[No support for nested content items] Nesting might be desirable for typesetting editions of manuscripts
% which sometimes contain marginal glosses, and then glosses upon those glosses.
% \end{description}
%
% The lack of any built-in facility for producing (for example) numbered sidenotes is a conscious design choice. This is
% properly the concern of a command that merely uses \cs{marginalia} to place the notes correctly.
%
%
%
% ^^A\bibliography{\jobname}
% ^^A\bibliographystyle{alphaabbrv}
%
% \begin{thebibliography}{Cai24}
%
% \bibitem[Bri04]{bringhurst_elements}
% R.~Bringhurst.
% \newblock {\em {T}he {E}lements of {T}ypographic {S}tyle}.
% \newblock Hartley {\&} Marks, version 3.0, 2004.
%
% \bibitem[Cai24]{cain_formandnumber_ebook_large}
% A.~J. Cain.
% \newblock {\em {F}orm {\&} {N}umber: {A} {H}istory of {M}athematical {B}eauty}.
% \newblock Lisbon, 2024.
% \newblock {\sc url:}
% \href{https://archive.org/details/cain_formandnumber_ebook_large}{\nolinkurl{https://archive.org/details/cain_formandnumber_ebook_large}}.
%
% \end{thebibliography}
%
%
%
% \end{documentation}
%
%
%
% \iffalse
%<*example>
\documentclass[11pt]{article}
\usepackage{marginalia}
\begin{document}
Here is some body text.\marginalia{Here is a marginal note.} Some more
body text.\marginalia[style=\footnotesize\itshape\raggedright]{Here is another
marginal note, set in smaller text and italics, whose position has been been
adjusted automatically.}
Some final body text.\marginalia[pos=left, valign=b, style=\sffamily\raggedleft,
width=35mm]{This note is placed on the left side of the page, wider, in sans
serif, ragged left, and bottom-aligned.}
\end{document}
%</example>
% \fi
%
%
%
% \clearpage
% \begin{implementation}
%
%
%
% \section{Implementation (\LaTeX\ package)}
%
% \begin{macrocode}
%<*package>
%<@@=marginalia>
% \end{macrocode}
%
%
%
% \subsection{Initial set-up}
%
% Package identification/version information.
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[2020-02-02]
\ProvidesExplPackage{marginalia}{2025-02-18}{0.80.2}
{Non-floating marginal content for LuaLaTeX}
% \end{macrocode}
% Check that Lua\TeX\ is in use.
% \begin{macrocode}
\sys_if_engine_luatex:F
{
\msg_new:nnn{marginalia}{lualatex_required}
{LuaLaTeX~required.~Package~loading~will~abort.}
\msg_critical:nn{marginalia}{lualatex_required}
}
% \end{macrocode}
%
%
%
% \subsection{Options}
%
% Set up the key--value options and the variables in which the settings will be stored.
%
%
%
% \subsubsection{Type}
%
% \begin{macro}{
% \l_@@_type_int,
% }
% A key to store the type of the marginal content item. The setting is held in an integer variable:
% \(1 = \key{normal}\), \(2 = \key{fixed}\), \(3 = \key{optfixed}\).
% \begin{macrocode}
\int_new:N\l_@@_type_int
\keys_define:nn { marginalia }
{
type .choices:nn = {normal,fixed,optfixed}{
\int_set:Nn\l_@@_type_int{\l_keys_choice_int}
},
type .initial:n = normal,
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Horizontal placement}
%
% \begin{macro}{
% \l_@@_pos_int,
% }
% A key to store the specified position of the marginal content item. The setting is held in an integer variable:
% \(1 = \key{auto}\), (the outer margin in one-column mode; left margin in left column, right margin in right column
% in two-column mode) \(2 = \key{reverse}\) (inner margin in one-column mode; between the columns in two-column mode),
% \(3 = \key{left}\), \(4 = \key{right}\), \(5 = \key{nearest}\).
% \begin{macrocode}
\int_new:N\l_@@_pos_int
\keys_define:nn { marginalia }
{
pos .choices:nn = {auto,reverse,left,right,nearest}{
\int_set:Nn\l_@@_pos_int{\l_keys_choice_int}
},
pos .initial:n = auto
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \l_@@_column_int,
% }
% A key to force the marginal content item to be treated in one-column mode or as being set from the left or right
% column. The setting is held in an integer variable: \(-1 = \key{auto}\) (automatic), \(0 = \key{one}\) (one-column
% mode), \(1 = \key{left}\) (left column) \(2 = \key{right}\) (right column).
% \begin{macrocode}
\int_new:N\l_@@_column_int
\keys_define:nn { marginalia }
{
column .choices:nn = {auto,one,left,right}{
\int_set:Nn\l_@@_column_int{\l_keys_choice_int-2}
},
column .initial:n = auto,
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \l_@@_xsep_recto_outer_dim,
% \l_@@_xsep_recto_inner_dim,
% \l_@@_xsep_verso_outer_dim,
% \l_@@_xsep_verso_inner_dim,
% \l_@@_xsep_right_between_dim,
% \l_@@_xsep_left_between_dim,
% }
% Dimension keys to hold the separation between the marginal content item and the main text, which can be dependent on
% where it appears on the page.
% \begin{macrocode}
\keys_define:nn { marginalia }
{
xsep~recto~outer .dim_set:N = \l_@@_xsep_recto_outer_dim,
xsep~recto~inner .dim_set:N = \l_@@_xsep_recto_inner_dim,
xsep~verso~outer .dim_set:N = \l_@@_xsep_verso_outer_dim,
xsep~verso~inner .dim_set:N = \l_@@_xsep_verso_inner_dim,
xsep~right~between .dim_set:N = \l_@@_xsep_right_between_dim,
xsep~left~between .dim_set:N = \l_@@_xsep_left_between_dim,
xsep .code:n = {
\keys_set:nn{ marginalia }{
xsep~recto~outer=#1,
xsep~recto~inner=#1,
xsep~verso~outer=#1,
xsep~verso~inner=#1,
xsep~right~between=#1,
xsep~left~between=#1,
}
},
xsep~outer .code:n = {
\keys_set:nn{ marginalia }{
xsep~recto~outer=#1,
xsep~verso~outer=#1,
}
},
xsep~inner .code:n = {
\keys_set:nn{ marginalia }{
xsep~recto~inner=#1,
xsep~verso~inner=#1,
}
},
xsep~between .code:n = {
\keys_set:nn{ marginalia }{
xsep~right~between=#1,
xsep~left~between=#1,
}
},
xsep .initial:n = \marginparsep,
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Vertical placement}
%
% \begin{macro}{
% \l_@@_valign_int,
% }
% A key to store the vertical alignment of the marginal content item. The setting is held in a integer variable:
% \(1 = \key{t}\) (aligned at the baseline of the topmost line of the item), \(2 = \key{b}\) (aligned at the baseline
% of the bottommost line of the item).
% \begin{macrocode}
\int_new:N\l_@@_valign_int
\keys_define:nn { marginalia }
{
valign .choices:nn = {t,b}{
\int_set_eq:NN\l_@@_valign_int\l_keys_choice_int
},
valign .initial:n = t,
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \l_@@_default_yshift_dim,
% }
% Dimension key to hold the default vertical shift of the marginal content item from its natural position.
% \begin{macrocode}
\keys_define:nn { marginalia }
{
yshift .dim_set:N = \l_@@_default_yshift_dim,
yshift .initial:n = 0pt,
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \l_@@_ysep_above_dim,
% \l_@@_ysep_below_dim,
% \l_@@_ysep_page_top_dim,
% \l_@@_ysep_page_bottom_dim
% }
% Dimension keys to hold the the minimum vertical spacing between a marginal content item and (respectively) the item
% above, the item below, the page top, and the page bottom.
% \begin{macrocode}
\keys_define:nn { marginalia }
{
ysep~above .dim_set:N = \l_@@_ysep_above_dim,
ysep~below .dim_set:N = \l_@@_ysep_below_dim,
ysep~page~top .dim_set:N = \l_@@_ysep_page_top_dim,
ysep~page~bottom .dim_set:N = \l_@@_ysep_page_bottom_dim,
ysep .code:n = {
\keys_set:nn{ marginalia }{
ysep~below=#1,
ysep~above=#1,
ysep~page~top=#1,
ysep~page~bottom=#1,
}
},
ysep .initial:n = \marginparpush,
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Appearance}
%
% \begin{macro}{
% \l_@@_width_recto_outer_dim,
% \l_@@_width_recto_inner_dim,
% \l_@@_width_verso_outer_dim,
% \l_@@_width_verso_inner_dim,
% \l_@@_width_right_between_dim,
% \l_@@_width_left_between_dim,
% }
% Dimension keys to hold the width of the marginal content item, which can be dependent on where it appears on the
% page.
% \begin{macrocode}
\keys_define:nn { marginalia }
{
width~recto~outer .dim_set:N = \l_@@_width_recto_outer_dim,
width~recto~inner .dim_set:N = \l_@@_width_recto_inner_dim,
width~verso~outer .dim_set:N = \l_@@_width_verso_outer_dim,
width~verso~inner .dim_set:N = \l_@@_width_verso_inner_dim,
width~right~between .dim_set:N = \l_@@_width_right_between_dim,
width~left~between .dim_set:N = \l_@@_width_left_between_dim,
width .code:n = {
\keys_set:nn{ marginalia }{
width~recto~outer=#1,
width~recto~inner=#1,
width~verso~outer=#1,
width~verso~inner=#1,
width~right~between=#1,
width~left~between=#1,
}
},
width~outer .code:n = {
\keys_set:nn{ marginalia }{
width~recto~outer=#1,
width~verso~outer=#1,
}
},
width~inner .code:n = {
\keys_set:nn{ marginalia }{
width~recto~inner=#1,
width~verso~inner=#1,
}
},
width~between .code:n = {
\keys_set:nn{ marginalia }{
width~right~between=#1,
width~left~between=#1,
}
},
width .initial:n = \marginparwidth,
}
% \end{macrocode}
% \end{macro}
%
%% \begin{macro}{
% \l_@@_style_recto_outer_tl,
% \l_@@_style_recto_inner_tl,
% \l_@@_style_verso_outer_tl,
% \l_@@_style_verso_inner_tl,
% \l_@@_style_right_between_tl,
% \l_@@_style_left_between_tl,
% }
% Token list keys to hold the style with which a marginal content item is typeset, which can be dependent on where it
% appears on the page.
% \begin{macrocode}
\keys_define:nn { marginalia }
{
style~recto~outer .tl_set:N = \l_@@_style_recto_outer_tl,
style~recto~inner .tl_set:N = \l_@@_style_recto_inner_tl,
style~verso~outer .tl_set:N = \l_@@_style_verso_outer_tl,
style~verso~inner .tl_set:N = \l_@@_style_verso_inner_tl,
style~right~between .tl_set:N = \l_@@_style_right_between_tl,
style~left~between .tl_set:N = \l_@@_style_left_between_tl,
style .code:n = {
\keys_set:nn{ marginalia }{
style~recto~outer=#1,
style~recto~inner=#1,
style~verso~outer=#1,
style~verso~inner=#1,
style~right~between=#1,
style~left~between=#1,
}
},
style .initial:n = {},
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Lua backend and interface}
%
% Load the Lua backend.
% \begin{macrocode}
\lua_now:n{
marginalia = require('marginalia')
}
% \end{macrocode}
%
% The following 9 macros interface between \LaTeX\ and Lua code. Each control sequence \cs[no-index]{@@_lua_XYZ}
% simply calls the corresponding Lua function \luafunc{marginalia.XYZ}.
% \begin{macro}{
% \@@_lua_store_default_page_data:,
% \@@_lua_store_page_data:n,
% \@@_lua_check_page_data:n,
% \@@_lua_store_item_data:n,
% \@@_lua_check_item_data:n,
% \@@_lua_compute_items:,
% \@@_lua_write_problem_report:,
% \@@_lua_write_item_change_report:,
% }
% The first 8 macros do not require expansion of parameters: they either have none, or process data not containing
% control sequences (read from the \file{.aux} file); hence \cs{lua_now:n} is used.
% \begin{macrocode}
\cs_new:Npn\@@_lua_store_default_page_data:
{
\lua_now:n{ marginalia.store_default_page_data() }
}
\cs_new:Npn\@@_lua_store_page_data:n #1
{
\lua_now:n{ marginalia.store_page_data('#1') }
}
\cs_new:Npn\@@_lua_check_page_data:n #1
{
\lua_now:n{ marginalia.check_page_data('#1') }
}
\cs_new:Npn\@@_lua_write_page_change_report:
{
\lua_now:n{ marginalia.write_page_change_report() }
}
\cs_new:Npn\@@_lua_store_item_data:n #1
{
\lua_now:n{ marginalia.store_item_data('#1') }
}
\cs_new:Npn\@@_lua_check_item_data:n #1
{
\lua_now:n{ marginalia.check_item_data('#1') }
}
\cs_new:Npn\@@_lua_compute_items:
{
\lua_now:n{ marginalia.compute_items() }
}
\cs_new:Npn\@@_lua_write_problem_report:
{
\lua_now:n{ marginalia.write_problem_report() }
}
\cs_new:Npn\@@_lua_write_item_change_report:
{
\lua_now:n{ marginalia.write_item_change_report() }
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \@@_lua_load_item_data:n,
% }
% The last macro will receive a control sequence parameter and so requires expansion; hence
% \cs{lua_now:e} is used.
% \begin{macrocode}
\cs_new:Npn\@@_lua_load_item_data:n #1
{
\lua_now:e{ marginalia.load_item_data('#1') }
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Processing data from the \texorpdfstring{\file{.aux}}{.aux} file}
%
% \begin{macro}[int]{
% \marginalia@pagedata,
% }
% This command is used to store page data in the \file{.aux} file.
% \begin{macrocode}
\NewDocumentCommand{\marginalia@pagedata}{ m }{
\@@_process_page_data:n{#1}
}
% \end{macrocode}
% Initially \cs{@@_process_page_data:n} is set to \cs{@@_lua_store_page_data:n}. Thus, when the \file{.aux} file is
% read, \cs{marginalia@pagedata} will pass the page data to the Lua backend to be stored.
% \begin{macrocode}
\cs_set_eq:NN
\@@_process_page_data:n
\@@_lua_store_page_data:n
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{
% \marginalia@itemdata,
% }
% This command is used to store data for each marginal content item in the \file{.aux} file.
% \begin{macrocode}
\DeclareDocumentCommand{\marginalia@itemdata}{ m }{
\@@_process_item_data:n{#1}
}
% \end{macrocode}
% \end{macro}
% Initially \cs{@@_process_item_data:n} is set to \cs{@@_lua_store_item_data:n}. Thus, when the \file{.aux} file is
% read, \cs{marginalia@itemdata} will pass the item data to the Lua backend to be stored.
% \begin{macrocode}
\cs_set_eq:NN
\@@_process_item_data:n
\@@_lua_store_item_data:n
% \end{macrocode}
% At the \texttt{begindocument} hook, the \file{.aux} file has been read and closed. The Lua backend now stores the
% geometry and computes the vertical shift for each item. Then the handle for the main \file{.aux} file is stored for
% use in this package.
% \begin{macrocode}
\AddToHook{begindocument}{
\@@_lua_store_default_page_data:
\@@_lua_compute_items:
\cs_set_eq:NN\l_@@_aux_iow\@mainaux
}
% \end{macrocode}
% The \texttt{enddocument/afterlastpage} hook is before the \file{.aux} file is read back, so this is where
% \cs{@@_process_page_data:n} and \cs{@@_process_item_data:n} are set, respectively, to \cs{@@_lua_check_page_data:n}
% and \cs{@@_lua_check_item_data:n}. Thus, when the \file{.aux} file is read back, \cs{marginalia@pagedata} and
% \cs{marginalia@itemdata} will pass data to the Lua backend to be checked for changes.
% \begin{macrocode}
\AddToHook{enddocument/afterlastpage}{
\cs_set_eq:NN
\@@_process_page_data:n
\@@_lua_check_page_data:n
\cs_set_eq:NN
\@@_process_item_data:n
\@@_lua_check_item_data:n
}
% \end{macrocode}
% \begin{macro}{\@@_write_reports:}
% All the reports of changes and/or problems are assembled in the Lua backend. This macro will write the reports as
% package warnings, using the following three messages, to which the Lua-assembled reports are passed as parameters:
% \begin{macrocode}
\msg_new:nnn{marginalia}{placement_problem}
{ Problems~in~placement.~#1 }
\msg_new:nnn{marginalia}{item_change}
{ Changes~in~item~data.~#1 }
\msg_new:nnn{marginalia}{page_change}
{ Changes~in~page~data.~#1 }
\cs_new:Npn\@@_write_reports:
{
\group_begin:
\tl_set:Ne\l_tmpa_tl{\@@_lua_write_problem_report:}
\tl_if_blank:VF\l_tmpa_tl
{
\msg_warning:nne{marginalia}{placement_problem}{\tl_use:N\l_tmpa_tl}
}
\tl_set:Ne\l_tmpa_tl{\@@_lua_write_item_change_report:}
\tl_if_blank:VF\l_tmpa_tl
{
\msg_warning:nne{marginalia}{item_change}{\tl_use:N\l_tmpa_tl}
}
\tl_set:Ne\l_tmpa_tl{\@@_lua_write_page_change_report:}
\tl_if_blank:VF\l_tmpa_tl
{
\msg_warning:nne{marginalia}{page_change}{\tl_use:N\l_tmpa_tl}
}
\group_end:
}
% \end{macrocode}
% \end{macro}
% Use the \texttt{enddocument/info} hook to write the reports of changes and/or problems.
% \begin{macrocode}
\AddToHook{enddocument/info}{
\@@_write_reports:
}
% \end{macrocode}
%
%
%
% \subsection{Writing page data to the \texorpdfstring{\file{.aux}}{.aux} file}
%
% To compute the positions of marginal content items, certain page layout data is required. And since all the
% computation takes place at the beginning of the document, it is necessary to write this information to the \file{.aux}
% file.
%
% \begin{macro}{\g_@@_pagedatano_int}
% Global integer variable to index page data items written to the \file{.aux} file.
% \begin{macrocode}
\int_new:N\g_@@_pagedatano_int
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_write_page_data}
% This command will be used to write the current page data to the \file{.aux} file. It is initially defined to do
% nothing, so that the use of \cs{marginalianewgeometry} in the preamble does not cause errors (because the
% \file{.aux} file is not available for writing until \texttt{begindocument/end}).
% \begin{macrocode}
\cs_set_eq:NN\@@_write_page_data:\prg_do_nothing:
\cs_new:Npn\@@_write_page_data_real:
{
\int_gincr:N\g_@@_pagedatano_int
\iow_now:Ne\l_@@_aux_iow{
\token_to_str:N\marginalia@pagedata{
pagedatano=\int_value:w\g_@@_pagedatano_int,
abspageno=\int_eval:n{\g_shipout_readonly_int+1},
hoffset=\int_value:w\hoffset,
voffset=\int_value:w\voffset,
paperheight=\int_value:w\paperheight,
oddsidemargin=\int_value:w\oddsidemargin,
evensidemargin=\int_value:w\evensidemargin,
textwidth=\int_value:w\textwidth,
columncount=\int_value:w\col@number,
columnwidth=\int_value:w\columnwidth,
columnsep=\int_value:w\columnsep,
twoside=\bool_to_str:n{\legacy_if_p:n{@twoside}},
}
}
}
% \end{macrocode}
% At the \texttt{begindocument/end} hook, the \file{.aux} file has been opened for writing, and so the macro
% \cs{@@_write_page_data:} is enabled and the initial page data is written out.
% \begin{macrocode}
\AddToHook{begindocument/end}
{
\cs_set_eq:NN
\@@_write_page_data:
\@@_write_page_data_real:
\@@_write_page_data:
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Marginal content item processing}
%
% \subsubsection{Variables}
%
% \paragraph{Variables set by \LaTeX.}
%
% \begin{macro}{\g_@@_itemno_int}
% Global integer variable to index marginal content items.
% \begin{macrocode}
\int_new:N\g_@@_itemno_int
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\l_@@_item_box}
% Box variable to hold the typeset marginal content item.
% \begin{macrocode}
\box_new:N\l_@@_item_box
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \l_@@_item_height_dim,
% \l_@@_item_depth_dim,
% }
% Dimension variables to hold the height and depth of the typeset margin content item.
% \begin{macrocode}
\dim_new:N\l_@@_item_height_dim
\dim_new:N\l_@@_item_depth_dim
% \end{macrocode}
% \end{macro}
%
%
%
% \paragraph{Variables set by Lua.}
%
% The following variables will be set by the Lua backend via \texttt{tex.count} and \texttt{tex.dimen} when
% \cs{@@_lua_load_item_data:n} is called.
%
% \begin{macro}{\l_@@_page_int}
% Integer variable for the page on which the marginal content item appears. This variable will be
% made available via \cs{marginaliapage} within the \meta{content} of \cs{marginalia}.
% \begin{macrocode}
\int_new:N\l_@@_page_int
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\l_@@_column_computed_int}
% Integer variable for the column next to which the marginal content item appears. This variable will be
% will be made available via \cs{marginaliacolumn} within the \meta{content} of \cs{marginalia}.
% \begin{macrocode}
\int_new:N\l_@@_column_computed_int
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{
% \l_@@_xshift_computed_dim,
% \l_@@_yshift_computed_dim,
% }
% Dimension variables to hold the differences in \(x\) and \(y\) coordinates between the call to \cs{marginalia} and
% the position where the marginal content item should appear.
% \begin{macrocode}
\dim_new:N\l_@@_xshift_computed_dim
\dim_new:N\l_@@_yshift_computed_dim
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\l_@@_side_computed_int}
% Integer variable to indicate the side of the text block or column on which the marginal content item should be
% placed: \(0 = \textrm{right}\) and \(1 = \textrm{left}\).
% \begin{macrocode}
\int_new:N\l_@@_side_computed_int
% \end{macrocode}
% (This variable could be a boolean, but an integer is used because there is no canonical access to booleans from
% Lua.)
% \end{macro}
%
% \begin{macro}{\l_@@_marginno_computed_int}
% Integer variable to indicate in which margin the content will be be placed, to enable quick selection of width and
% style: \(0 = \textrm{recto outer}\), \(1 = \textrm{recto inner}\), \(2 = \textrm{verso outer}\), \(3 = \textrm{verso
% inner}\), \(4 = \textrm{right between}\), \(5 = \textrm{left between}\).
% \begin{macrocode}
\int_new:N\l_@@_marginno_computed_int
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\l_@@_enabled_computed_int}
% Integer variable to indicate whether the marginal content item is enabled: \(0 = \textrm{disabled}\),
% \(1 = \textrm{enabled}\).
% \begin{macrocode}
\int_new:N\l_@@_enabled_computed_int
% \end{macrocode}
% (This variable could be a boolean, but an integer is used because there is no canonical access to booleans from
% Lua.)
% \end{macro}
%
%
%
% \subsubsection{Core macro}
%
% \begin{macro}{\@@_process_item:nn}
% This macro does most of the work in setting the marginal content item. The first parameter is \meta{options}, the
% second is \meta{content}.
% \begin{macrocode}
\cs_new:Npn\@@_process_item:nn #1#2
{
% \end{macrocode}
% First, increment the index, then enter a group where all the action will happen.
% \begin{macrocode}
\int_gincr:N\g_@@_itemno_int
\group_begin:
% \end{macrocode}
% Process \meta{options}. These settings apply locally inside the group.
% \begin{macrocode}
\keys_set:nn{marginalia}{ #1 }
% \end{macrocode}
% Get item data from the Lua backend: the integer variables \cs{l_@@_page_int}, \cs{l_@@_column_computed_int},
% \cs{l_@@_side_computed_int}, \cs{l_@@_enabled_computed_int}, and the dimension variables
% \cs{l_@@_xshift_computed_dim}, and \cs{l_@@_yshift_computed_dim} are set by Lua via \texttt{tex.count} and
% \texttt{tex.dimen}. If no data is available (if, for instance, no data has been stored from a previous run), default
% values will be set by Lua. On later runs, the Lua backend will supply the values computed from the data written to
% the \file{.aux} file on the previous run.
% \begin{macrocode}
\@@_lua_load_item_data:n
{ \int_value:w\g_@@_itemno_int }
% \end{macrocode}
% Choose the correct auxiliary function for typesetting, depending on which mode \TeX\ is in.
% \begin{macrocode}
\mode_if_math:TF
{
\cs_set_eq:NN
\@@_typeset:n
\@@_typeset_mmode:n
}
{
\legacy_if:nT{@inlabel}
{ \leavevmode }
\mode_if_horizontal:TF
{
\cs_set_eq:NN
\@@_typeset:n
\@@_typeset_hmode:n
}
{
\cs_set_eq:NN
\@@_typeset:n
\@@_typeset_vmode:n
}
}
% \end{macrocode}
% Choose the correct box in which to typeset the item. \cs{l_@@_valign_int} can only be \(1\) or \(2\), so take \(2\)
% to signify bottom-aligned, anything else signifies top-aligned.
% \begin{macrocode}
\int_compare:nNnTF{\l_@@_valign_int}={2}
{
\cs_set_eq:NN\@@_item_box_set:Nn\vbox_set:Nn
}
{
\cs_set_eq:NN\@@_item_box_set:Nn\vbox_set_top:Nn
}
% \end{macrocode}
% Choose the correct horizontal separation, width, and style for the item.
% \begin{macrocode}
\@@_set_xsep_width_style:
% \end{macrocode}
% Typeset the \meta{content} into \cs{l_@@_item_box}. Use \cs{@parboxrestore} for brevity, even though \cs{hsize} and
% \cs{linewidth} are subsequently set to \cs{l_@@_width_dim}. Make available \cs{marginaliapage} and
% \cs{marginaliacolumn}.
% \begin{macrocode}
\@@_item_box_set:Nn\l_@@_item_box{
\@parboxrestore
\normalfont\normalsize
\tl_use:N\l_@@_style_tl
\dim_set_eq:NN\hsize\l_@@_width_dim
\dim_set_eq:NN\linewidth\hsize
\cs_set_eq:NN\marginaliapage\l_@@_page_int
\cs_set_eq:NN\marginaliacolumn\l_@@_column_computed_int
\group_begin:
\ignorespaces
#2
\par
\group_end:
}
% \end{macrocode}
% Measure \cs{l_@@_item_box}.
% \begin{macrocode}
\dim_set:Nn\l_@@_item_height_dim
{\box_ht:N\l_@@_item_box}
\dim_set:Nn\l_@@_item_depth_dim
{\box_dp:N\l_@@_item_box}
% \end{macrocode}
% Everything is now ready to place the item on the page and write the necessary data to the \file{.aux} file. Use the
% chosen auxiliary function for typesetting, and immediately use \cs{savepos} to store the callout position.
% \begin{macrocode}
\@@_typeset:n{
\savepos
% \end{macrocode}
% Write the item data to the \file{.aux} file. All tokens that will change for future items, and which are currently
% meaningful, are expanded now; the remainder will be expanded at shipout time, when \emph{they} are meaningful.
% \begin{macrocode}
\iow_shipout_e:Ne\l_@@_aux_iow{
\token_to_str:N\marginalia@itemdata{
itemno=\int_value:w\g_@@_itemno_int,
abspageno=\exp_not:N\int_eval:n{\g_shipout_readonly_int},
pageno=\exp_not:N\int_value:w\c@page,
type=\str_use:N\int_value:w\l_@@_type_int,
xpos=\exp_not:N\int_value:w\lastxpos,
ypos=\exp_not:N\int_value:w\lastypos,
height=\int_value:w\l_@@_item_height_dim,
depth=\int_value:w\l_@@_item_depth_dim,
pos=\int_value:w\l_@@_pos_int,
column=\int_value:w\l_@@_column_int,
yshift=\int_value:w\l_@@_default_yshift_dim,
ysep~above=\int_value:w\l_@@_ysep_above_dim,
ysep~below=\int_value:w\l_@@_ysep_below_dim,
ysep~page~top=\int_value:w\l_@@_ysep_page_top_dim,
ysep~page~bottom=\int_value:w\l_@@_ysep_page_bottom_dim,
}
}
% \end{macrocode}
% Finally, if the item is enabled, typeset it onto the page: shift the item by
% \[
% \abs[\big]{\cs{l_@@_xshift_computed_dim}} + \abs[\big]{\cs{l_@@_xsep_dim}}
% \]
% to the right in an \cs{rlap} or to the left in an \cs{llap}, depending on \cs{l_@@_side_computed_int}, then use
% \cs{@@_place_item_box} for the vertical placement.
% \begin{macrocode}
\int_if_zero:nF{\l_@@_enabled_computed_int}
{
\int_if_zero:nTF{\l_@@_side_computed_int}
{
\rlap{
\kern\l_@@_xshift_computed_dim
\kern\l_@@_xsep_dim
\@@_place_item_box:
}
}
{
\llap{
\@@_place_item_box:
\kern\l_@@_xsep_dim
\kern-\l_@@_xshift_computed_dim
}
}
}
}
% \end{macrocode}
% Close the group started near the beginning of \cs{@@_process_item:nn}.
% \begin{macrocode}
\group_end:
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Width and style selection}
%
% \begin{macro}{\@@_set_xsep_width_style}
% Set \cs{l_@@_xsep_dim}, \cs{l_@@_width_dim}, and \cs{l_@@_style_tl}, based on \cs{l_@@_marginno_computed_int}.
% \begin{macrocode}
\cs_new:Npn\@@_set_xsep_width_style:
{
\int_case:nn{\l_@@_marginno_computed_int}
{
{0}
{
\cs_set_eq:NN\l_@@_xsep_dim
\l_@@_xsep_recto_outer_dim
\cs_set_eq:NN\l_@@_width_dim
\l_@@_width_recto_outer_dim
\cs_set_eq:NN\l_@@_style_tl
\l_@@_style_recto_outer_tl
}
{1}
{
\cs_set_eq:NN\l_@@_xsep_dim
\l_@@_xsep_recto_inner_dim
\cs_set_eq:NN\l_@@_width_dim
\l_@@_width_recto_inner_dim
\cs_set_eq:NN\l_@@_style_tl
\l_@@_style_recto_inner_tl
}
{2}
{
\cs_set_eq:NN\l_@@_xsep_dim
\l_@@_xsep_verso_outer_dim
\cs_set_eq:NN\l_@@_width_dim
\l_@@_width_verso_outer_dim
\cs_set_eq:NN\l_@@_style_tl
\l_@@_style_verso_outer_tl
}
{3}
{
\cs_set_eq:NN\l_@@_xsep_dim
\l_@@_xsep_verso_inner_dim
\cs_set_eq:NN\l_@@_width_dim
\l_@@_width_verso_inner_dim
\cs_set_eq:NN\l_@@_style_tl
\l_@@_style_verso_inner_tl
}
{4}
{
\cs_set_eq:NN\l_@@_xsep_dim
\l_@@_xsep_right_between_dim
\cs_set_eq:NN\l_@@_width_dim
\l_@@_width_right_between_dim
\cs_set_eq:NN\l_@@_style_tl
\l_@@_style_right_between_tl
}
{5}
{
\cs_set_eq:NN\l_@@_xsep_dim
\l_@@_xsep_left_between_dim
\cs_set_eq:NN\l_@@_width_dim
\l_@@_width_left_between_dim
\cs_set_eq:NN\l_@@_style_tl
\l_@@_style_left_between_tl
}
}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Auxiliary placement macros}
%
% \begin{macro}{\@@_place_item_box:}
% Place the item that has been set in \cs{l_@@_item_box}, vertically shifted by \cs{l_@@_yshift_computed_dim} and
% \cs{smash}ed to avoid altering vertical spacing in the main text.
% \begin{macrocode}
\cs_new:Npn\@@_place_item_box:
{
\smash
{
\box_move_up:nn{\l_@@_yshift_computed_dim}
{
\box_use:N\l_@@_item_box
}
}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{
% \@@_typeset_mmode:n,
% \@@_typeset_hmmode:n,
% \@@_typeset_vmode:n,
% }
% These three macros handle typsetting in math mode, horizontal mode, and vertical mode. Nothing special needs to be
% done in math mode. In horizontal mode, \cs{@bsphack}\ldots\cs{@bsphack} avoids double spacing. In vertical mode, a
% new paragraph containing only a \cs{strut} is started, the item is typeset, the paragraph is ended, and then a
% vertical skip of \(-\cs{baselineskip}\) should `hide' that invisible paragraph.
% \begin{macrocode}
\cs_new:Npn\@@_typeset_mmode:n #1
{
#1
}
\cs_new:Npn\@@_typeset_hmode:n #1
{
\@bsphack
#1
\@esphack
}
\cs_new:Npn\@@_typeset_vmode:n #1
{
\nobreak\noindent\strut #1\par
\skip_vertical:n{-\baselineskip}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{User commands}
%
% Finally, set up the commands for the user.
%
% \begin{macro}{\marginalia}
% This is the main user command for creating a marginal content item. This macro does nothing but hand off to
% \cs{@@_process_item:nn}.
% \begin{macrocode}
\NewDocumentCommand{\marginalia}{ O{} +m }
{
\@@_process_item:nn{#1}{#2}
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\marginaliasetup}
% The user command to set the configuration.
% \begin{macrocode}
\NewDocumentCommand{\marginaliasetup}{ m }
{
\keys_set:nn{marginalia}{ #1 }
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{\marginalianewgeometry}
% The user command to signal that the page geometry has been changed.
% \begin{macrocode}
\NewDocumentCommand{\marginalianewgeometry}{}
{
\@@_write_page_data:
}
% \end{macrocode}
% \end{macro}
%
%
%
% \begin{macrocode}
%</package>
% \end{macrocode}
%
%
%
% \section{Implementation (Lua backend)}
%
% \begin{macrocode}
%<*lua>
% \end{macrocode}
%
%
%
% \subsection{Global variables}
%
% Global tables for page_data and item_data.
% \begin{macrocode}
local PAGE_DATA_MAIN_TABLE = {}
local ITEM_DATA_MAIN_TABLE = {}
% \end{macrocode}
% Global tables for compiling reports.
% \begin{macrocode}
local PROBLEM_REPORT_TABLE = {}
local PAGE_CHANGE_REPORT_TABLE = {}
local ITEM_CHANGE_REPORT_TABLE = {}
% \end{macrocode}
% Global configuration for reports.
% \begin{macrocode}
local PROBLEM_REPORT_MAX_LENGTH = 40
local PAGE_CHANGE_REPORT_MAX_LENGTH = 10
local ITEM_CHANGE_REPORT_MAX_LENGTH = 10
% \end{macrocode}
%
%
%
% \subsection{Constants}
%
% Type constants. These match the possible values for the type key.
% \begin{macrocode}
local TYPE_NORMAL = 1
local TYPE_FIXED = 2
local TYPE_OPTFIXED = 3
% \end{macrocode}
% Position constants. These match the possible values for the pos key.
% \begin{macrocode}
local POS_AUTO = 1
local POS_REVERSE = 2
local POS_LEFT = 3
local POS_RIGHT = 4
local POS_NEAREST = 5
% \end{macrocode}
%
%
%
% \subsection{Keys for tables}
%
% The strings listed in this subsection are constants used to index the tables. Also listed are the types of
% values that are indexed by each key. Note that values listed below as "dimensions" are actually integers, giving the
% dimension in TeX scaled points (sp)
%
%
%
% \subsubsection{Keys for both page and item data tables}
%
% Integer: Absolute page number in output file (not on-page number), used in both page_data and item_data tables
% \begin{macrocode}
local KEY_ABSPAGENO = 'abspageno'
% \end{macrocode}
% Boolean: Used to mark page_data or item_data as checked when the .aux file is read back at the end of the document
% \begin{macrocode}
local KEY_CHECKED = 'checked'
% \end{macrocode}
%
%
%
% \subsubsection{Keys for page data tables, layout etc.}
%
% Integer: Used only to distinguish instances of data written to .aux file
% \begin{macrocode}
local KEY_PAGEDATANO = 'pagedatano'
% \end{macrocode}
% Dimensions: Value of next two will always be equivalent of \qty{1}{\inch}, but it is simpler to keep all geometry
% data together.
% \begin{macrocode}
local KEY_HOFFSETORIGIN = 'hoffsetorigin'
local KEY_VOFFSETORIGIN = 'voffsetorigin'
% \end{macrocode}
% Dimensions: corresponding to obvious LaTeX dimensions
% \begin{macrocode}
local KEY_HOFFSET = 'hoffset'
local KEY_VOFFSET = 'voffset'
local KEY_PAPERHEIGHT = 'paperheight'
local KEY_ODDSIDEMARGIN = 'oddsidemargin'
local KEY_EVENSIDEMARGIN = 'evensidemargin'
local KEY_TEXTWIDTH = 'textwidth'
local KEY_COLUMNWIDTH = 'columnwidth'
local KEY_COLUMNSEP = 'columnsep'
% \end{macrocode}
% Integer: either \(1\) or \(2\), depending on whether LaTeX was in one- or two-column mode
% \begin{macrocode}
local KEY_COLUMNCOUNT = 'columncount'
% \end{macrocode}
% Boolean: true iff LaTeX is in twoside mode
% \begin{macrocode}
local KEY_TWOSIDE = 'twoside'
% \end{macrocode}
%
%
%
% \subsubsection{Keys for item data tables}
%
% Integer: Used to identify data with item
% \begin{macrocode}
local KEY_ITEMNO = 'itemno'
% \end{macrocode}
% Integer: On-page number
% \begin{macrocode}
local KEY_PAGENO = 'pageno'
% \end{macrocode}
% Dimensions: \(x\) and \(y\) positions of call to \cs{marginalia}
% \begin{macrocode}
local KEY_XPOS = 'xpos'
local KEY_YPOS = 'ypos'
% \end{macrocode}
% Dimensions: Height and depth of typeset item
% \begin{macrocode}
local KEY_HEIGHT = 'height'
local KEY_DEPTH = 'depth'
% \end{macrocode}
% Integer: Specified type, following \luavar{TYPE_*}
% \begin{macrocode}
local KEY_TYPE = 'type'
% \end{macrocode}
% Integer: corresponds to value of \key{pos} key: \(0 = \texttt{auto}\), \(1 = \texttt{reverse}\), \(2 = \texttt{left}\),
% \(3 = \texttt{right}\), \(4 = \texttt{nearest}\)
% \begin{macrocode}
local KEY_POS = 'pos'
% \end{macrocode}
% Integer: corresponds to value of \key{column} key: \(-1 = \texttt{auto}\), \(0 = \texttt{one}\), \(1 = \texttt{left}\),
% \(2 = \texttt{right}\)
% \begin{macrocode}
local KEY_COLUMN = 'column'
% \end{macrocode}
% Dimension: specified vertical shift
% \begin{macrocode}
local KEY_YSHIFT = 'yshift'
% \end{macrocode}
% Dimensions: specified vertical separations
% \begin{macrocode}
local KEY_YSEP_ABOVE = 'ysep above'
local KEY_YSEP_BELOW = 'ysep below'
local KEY_YSEP_PAGE_TOP = 'ysep page top'
local KEY_YSEP_PAGE_BOTTOM = 'ysep page bottom'
% \end{macrocode}
%
% \medskip\noindent
% The preceding keys refer to values that will be supplied from \LaTeX. The remaining values will be computed in Lua
% and passed back to \LaTeX.
%
% \medskip\noindent
% Integer: column in which the call to \cs{marginalia} was located: \(0 = \textrm{one-column}\),
% \(1 = \textrm{left}\), \(2 = \textrm{right}\)
% \begin{macrocode}
local KEY_COLNO_COMPUTED = 'colno computed'
% \end{macrocode}
% Dimension: Horizontal shift between the call to \cs{marginalia} and the margin in which the item should be located
% \begin{macrocode}
local KEY_XSHIFT_COMPUTED = 'xshift computed'
% \end{macrocode}
% Dimension: Computed vertical shift
% \begin{macrocode}
local KEY_YSHIFT_COMPUTED = 'yshift computed'
% \end{macrocode}
% Integer: Side of text on which the item will appear: \(0 = \textrm{right}\), \(1 = \textrm{left}\)
% \begin{macrocode}
local KEY_SIDE_COMPUTED = 'side computed'
% \end{macrocode}
% Integer: Number of margin in which the item will appear, \(0 = \textrm{recto outer}\), \(1 = \textrm{recto inner}\),
% \(2 = \textrm{verso outer}\), \(3 = \textrm{verso inner}\), \(4 = \textrm{ right between}\),
% \(5 = \textrm{left between}\)
% \begin{macrocode}
local KEY_MARGINNO_COMPUTED = 'marginno computed'
% \end{macrocode}
% Boolean: Whether the item will actually appear on the page
% \begin{macrocode}
local KEY_ENABLED_COMPUTED = 'enabled computed'
% \end{macrocode}
%
%
%
% \subsection{Utility functions}
%
% \begin{macro}[int]{list_filter}
% Take a list \luavar{t} and remove from it any elements for which the function
% \luavar{f} does not return true. (The index \luavar{j} is always the destination index to which a `keep' element
% is moved.)\sidenote{Code adapted from \url{https://stackoverflow.com/a/53038524/8990243}.}
% \begin{macrocode}
local function list_filter(t, f)
local j = 1
local n = #t
for i=1,n do
if (f(t[i])) then
if (i ~= j) then
t[j] = t[i]
t[i] = nil
end
j = j + 1
else
t[i] = nil
end
end
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{list_filter}
% Return boolean true iff \luavar{s} is exactly the string `\luavar{true}'.
% \begin{macrocode}
local function toboolean(s)
return s == "true"
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{get_data_page_number}
% Take a item or page data and return a human-readable string indicating the page to which the data pertains.
% \begin{macrocode}
local function get_data_page_number(data)
local pageno = data[KEY_PAGENO]
if pageno ~= nil then
return 'p' .. pageno .. ' (' .. data[KEY_ABSPAGENO] .. ')'
else
return data[KEY_ABSPAGENO]
end
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Generic page/item data functions}
%
% \begin{macro}[int]{parse_data}
% Parse \luavar{keyvalue_string} and return the corresponding data as a table. The \luavar{keyvalue_string} is
% expected to be of precisely the kind written to the \file{.aux} file as the parameter of \cs{marginalia@pagedata} or
% \cs{marginalia@notedata}.
%
% Ignore any keys in \luavar{keyvalue_string} that are not listed in \luavar{conversion_table}. Fill in any missing
% value with values from \luavar{defaults_table}.
%
% \luavar{conversion_table} is indexed by possible keys, with values equal to functions to convert the corresponding
% value string to the value that should appear in the returned table.
%
% \luavar{defaults_table} is indexed by keys that \emph{will} appear in the returned table, using the corresponding
% value unless it was given in \luavar{keyvalue_string} and the key appeared in \luavar{conversion_table}.
% \begin{macrocode}
local function parse_data(keyvalue_string,conversion_table,defaults_table)
local key
local value
local result = {}
for s in string.gmatch(keyvalue_string,'([^,]+)') do
key,value = string.match(s,'^(.+)=(.+)$')
local conv = conversion_table[key]
if conv ~= nil then
result[key] = conv(value)
end
end
for key,value in pairs(defaults_table) do
if not(result[key] ~= nil) then
result[key] = value
end
end
return result
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{check_data}
% Check \luavar{keyvalue_string} against stored data. If it is new or has changed, append a report to
% \luavar{report_table}. Set the \luavar{KEY_CHECKED} of the data item to true.
%
% The \luavar{keyvalue_string} is processed using \luavar{conversion_table} and \luavar{defaults_table} as per the
% \luavar{parse_data} function. The resulting table is compared to the table in \luavar{data_table} with the same value
% whose key is \luavar{data_table_key}. The tables are compared using the fields indexed by keys in
% \luavar{conversion_table}.
% \begin{macrocode}
local function check_data(keyvalue_string,conversion_table,defaults_table,
data_table,data_table_key_field,report_table)
local new_data = parse_data(keyvalue_string,
conversion_table,defaults_table)
local data_table_key = new_data[data_table_key_field]
local stored_data = data_table[data_table_key]
if stored_data == nil then
table.insert(
report_table,
get_data_page_number(new_data) .. ' New'
)
else
local change_report = ''
for k,_ in pairs(conversion_table) do
if stored_data[k] ~= new_data[k] then
change_report = change_report
.. ' ' .. k .. ':' ..
tostring(stored_data[k]) .. '->' .. tostring(new_data[k])
end
end
if change_report ~= '' then
table.insert(
report_table,
get_data_page_number(new_data) .. ' ' .. change_report
)
end
stored_data[KEY_CHECKED] = true
end
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{check_removed_data}
% Check whether data have been removed from \luavar{data_table}, which corresponds to some entry having the value
% of \luavar{KEY_CHECKED} being false. In this case, append a report to \luavar{report_table}.
% \begin{macrocode}
local function check_removed_data(data_table,report_table)
for _,data in pairs(data_table) do
if not data[KEY_CHECKED] then
table.insert(
report_table,
' Removed'
)
break
end
end
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Processing of page data from \texorpdfstring{\file{.aux}}{.aux} file}
%
% Conversion and default tables.
% \begin{macrocode}
local PAGE_DATA_CONVERSION_TABLE = {
[KEY_PAGEDATANO] = tonumber,
[KEY_ABSPAGENO] = tonumber,
[KEY_HOFFSETORIGIN] = tonumber,
[KEY_VOFFSETORIGIN] = tonumber,
[KEY_HOFFSET] = tonumber,
[KEY_VOFFSET] = tonumber,
[KEY_PAPERHEIGHT] = tonumber,
[KEY_ODDSIDEMARGIN] = tonumber,
[KEY_EVENSIDEMARGIN] = tonumber,
[KEY_COLUMNCOUNT] = tonumber,
[KEY_COLUMNWIDTH] = tonumber,
[KEY_COLUMNSEP] = tonumber,
[KEY_TEXTWIDTH] = tonumber,
[KEY_TWOSIDE] = toboolean,
}
local PAGE_DATA_DEFAULT_TABLE = {
[KEY_PAGEDATANO] = 0,
[KEY_ABSPAGENO] = 0,
[KEY_HOFFSETORIGIN] = tex.sp('1in'),
[KEY_VOFFSETORIGIN] = tex.sp('1in'),
[KEY_HOFFSET] = tex.dimen['hoffset'],
[KEY_VOFFSET] = tex.dimen['voffset'],
[KEY_PAPERHEIGHT] = tex.dimen['paperheight'],
[KEY_ODDSIDEMARGIN] = tex.dimen['oddsidemargin'],
[KEY_EVENSIDEMARGIN] = tex.dimen['evensidemargin'],
[KEY_TEXTWIDTH] = tex.dimen['textwidth'],
[KEY_COLUMNWIDTH] = tex.dimen['columnwidth'],
[KEY_COLUMNSEP] = tex.dimen['columnsep'],
[KEY_COLUMNCOUNT] = 1,
[KEY_TWOSIDE] = false,
[KEY_CHECKED] = false,
}
% \end{macrocode}
%
% \begin{macro}[int]{store_page_data}
% Store page data supplied by \luavar{keyvalue_string} in \luavar{PAGE_DATA_MAIN_TABLE}.
% \begin{macrocode}
local function store_page_data(keyvalue_string)
local page_data = parse_data(keyvalue_string,
PAGE_DATA_CONVERSION_TABLE,
PAGE_DATA_DEFAULT_TABLE)
PAGE_DATA_MAIN_TABLE[page_data[KEY_PAGEDATANO]] = page_data
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{store_default_page_data}
% Store default page data in \luavar{PAGE_DATA_MAIN_TABLE}, so that there is some data to work with when
% computing item positions, even on a first run, when no page data has been written to the \file{.aux} file.
% \begin{macrocode}
local function store_default_page_data()
default_page_data = parse_data('',
PAGE_DATA_CONVERSION_TABLE,
PAGE_DATA_DEFAULT_TABLE)
default_page_data[KEY_ABSPAGENO] = 1
default_page_data[KEY_CHECKED] = true
PAGE_DATA_MAIN_TABLE[0] = default_page_data
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{check_page_data}
% Check whether page_data supplied by keyvalue_string differs from that in \luavar{PAGE_DATA_MAIN_TABLE}, appending
% reports to \luavar{PAGE_CHANGE_REPORT_TABLE} if so.
% \begin{macrocode}
local function check_page_data(keyvalue_string)
check_data(keyvalue_string,
PAGE_DATA_CONVERSION_TABLE,PAGE_DATA_DEFAULT_TABLE,
PAGE_DATA_MAIN_TABLE,KEY_PAGEDATANO,
PAGE_CHANGE_REPORT_TABLE)
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Processing of item data from \texorpdfstring{\file{.aux}}{.aux} file}
%
% Conversion and default tables.
% \begin{macrocode}
local ITEM_DATA_CONVERSIONS = {
[KEY_ITEMNO] = tonumber,
[KEY_ABSPAGENO] = tonumber,
[KEY_PAGENO] = tonumber,
[KEY_XPOS] = tonumber,
[KEY_YPOS] = tonumber,
[KEY_HEIGHT] = tonumber,
[KEY_DEPTH] = tonumber,
[KEY_TYPE] = tonumber,
[KEY_POS] = tonumber,
[KEY_COLUMN] = tonumber,
[KEY_YSHIFT] = tonumber,
[KEY_YSEP_ABOVE] = tonumber,
[KEY_YSEP_BELOW] = tonumber,
[KEY_YSEP_PAGE_TOP] = tonumber,
[KEY_YSEP_PAGE_BOTTOM] = tonumber,
[KEY_CHECKED] = toboolean,
}
local ITEM_DATA_DEFAULTS = {
[KEY_ITEMNO] = 0,
[KEY_ABSPAGENO] = 1,
[KEY_PAGENO] = 1,
[KEY_XPOS] = 0,
[KEY_YPOS] = 0,
[KEY_HEIGHT] = 0,
[KEY_DEPTH] = 0,
[KEY_TYPE] = 0,
[KEY_POS] = 0,
[KEY_COLUMN] = -1,
[KEY_YSHIFT] = 0,
[KEY_YSEP_ABOVE] = tex.dimen['marginparpush'],
[KEY_YSEP_BELOW] = tex.dimen['marginparpush'],
[KEY_YSEP_PAGE_TOP] = tex.dimen['marginparpush'],
[KEY_YSEP_PAGE_BOTTOM] = tex.dimen['marginparpush'],
[KEY_COLNO_COMPUTED] = 0,
[KEY_XSHIFT_COMPUTED] = 0,
[KEY_YSHIFT_COMPUTED] = 0,
[KEY_SIDE_COMPUTED] = 0,
[KEY_MARGINNO_COMPUTED] = 0,
[KEY_ENABLED_COMPUTED] = true,
[KEY_CHECKED] = false,
}
% \end{macrocode}
% \luavar{ITEM_DATA_DEFAULTS} is also used by \luafunc{load_item_data} when no stored item data is found in
% \luavar{ITEM_DATA_MAIN_TABLE}.
% \begin{macro}[int]{store_item_data}
% Store item_data supplied by \luavar{keyvalue_string} in \luavar{ITEM_DATA_MAIN_TABLE}.
% \begin{macrocode}
local function store_item_data(keyvalue_string)
local item = parse_data(keyvalue_string,
ITEM_DATA_CONVERSIONS,
ITEM_DATA_DEFAULTS)
ITEM_DATA_MAIN_TABLE[item[KEY_ITEMNO]] = item
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{check_item_data}
% Check whether item_data supplied by \luavar{keyvalue_string} differs from that in \luavar{ITEM_DATA_MAIN_TABLE},
% appending reports to \luavar{ITEM_CHANGE_REPORT_TABLE} if so.
% \begin{macrocode}
local function check_item_data(keyvalue_string)
check_data(keyvalue_string,
ITEM_DATA_CONVERSIONS,ITEM_DATA_DEFAULTS,
ITEM_DATA_MAIN_TABLE,KEY_ITEMNO,
ITEM_CHANGE_REPORT_TABLE)
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Writing reports}
%
% \begin{macro}[int]{write_report}
% Write the data contained in \luavar{report_table} to \TeX\ in a format suitable for a package warning. The written
% text will contain at most \luavar{max_length} items.
% \begin{macrocode}
local function write_report(report_table,max_length)
if #report_table > 0 then
local report_text
local report_length
if #report_table <= max_length then
report_length = #report_table
report_text = ' Here they are:\n'
else
report_length = max_length
report_text = ' Here are the first ' .. report_length .. ':\n'
end
for i=1,report_length do
report_text = report_text .. report_table[i]
if i < report_length then
report_text = report_text .. '\n'
end
end
tex.print(report_text)
end
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{write_problem_report}
% Write a report about placement problems to \TeX\ in a format suitable for a package warning.
% \begin{macrocode}
local function write_problem_report()
write_report(PROBLEM_REPORT_TABLE,PROBLEM_REPORT_MAX_LENGTH)
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{write_item_change_report}
% Write a report about changes in item data to \TeX\ in a format suitable for a package warning.
% \begin{macrocode}
local function write_item_change_report()
check_removed_data(ITEM_DATA_MAIN_TABLE,ITEM_CHANGE_REPORT_TABLE)
write_report(ITEM_CHANGE_REPORT_TABLE,ITEM_CHANGE_REPORT_MAX_LENGTH)
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{write_page_change_report}
% Write a report about changes in page data to \TeX\ in a format suitable for a package warning.
% \begin{macrocode}
local function write_page_change_report()
check_removed_data(PAGE_DATA_MAIN_TABLE,PAGE_CHANGE_REPORT_TABLE)
write_report(PAGE_CHANGE_REPORT_TABLE,PAGE_CHANGE_REPORT_MAX_LENGTH)
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Computing horizontal positions}
%
% It is necessary to determine whether an item should be placed on the right or left of the text block, and in which
% column it lies. The following lookup tables are used.
%
% The value found in \luavar{RIGHTSIDE_LOOKUP_TABLE} is either \luavar{true} (right) or \luavar{false} (left). It is
% indexed by whether the item is on a recto page (\luavar{true}/\luavar{false}), whether it pertains to single-column
% text, the left column, or the right colum (\luavar{0}/\luavar{1}/\luavar{2}), and the value of \key{pos} being
% either \val{auto} or \val{reverse}.
% \begin{macrocode}
local RIGHTSIDE_LOOKUP_TABLE = {
[true] = {
[0] = {
[POS_AUTO] = true,
[POS_REVERSE] = false,
},
[1] = {
[POS_AUTO] = false,
[POS_REVERSE] = true,
},
[2] = {
[POS_AUTO] = true,
[POS_REVERSE] = false,
},
},
[false] = {
[0] = {
[POS_AUTO] = false,
[POS_REVERSE] = true,
},
[1] = {
[POS_AUTO] = true,
[POS_REVERSE] = false,
},
[2] = {
[POS_AUTO] = false,
[POS_REVERSE] = true,
},
},
}
% \end{macrocode}
% The value found in \luavar{MARGINNO_LOOKUP_TABLE} ranges from \luavar{0} to \luavar{5} (see
% \luavar{KEY_MARGINNO_COMPUTED} for the meaning of these values). It is indexed by whether the item is on a recto
% page (\luavar{true}/\luavar{false}), whether it pertains to single-column text, the left column, or the right colum
% (\luavar{0}/\luavar{1}/\luavar{2}), and whether it is to be placed on the right of the text block
% (\luavar{true}/\luavar{false}).
% \begin{macrocode}
local MARGINNO_LOOKUP_TABLE = {
[true] = {
[0] = {
[false] = 1,
[true] = 0,
},
[1] = {
[false] = 1,
[true] = 5,
},
[2] = {
[false] = 4,
[true] = 0,
},
},
[false] = {
[0] = {
[false] = 2,
[true] = 3,
},
[1] = {
[false] = 2,
[true] = 5,
},
[2] = {
[false] = 4,
[true] = 3,
},
},
}
% \end{macrocode}
%
% \begin{macro}[int]{compute_items_horizontal}
% For every \luavar{item_data} in \luavar{item_data_list}, compute the fields relevant to horizontal positioning,
% namely \luavar{KEY_COLNO_COMPUTED}, \luavar{KEY_XSHIFT_COMPUTED}, \luavar{KEY_SIDE_COMPUTED}, based on the layout
% information in page_data. Every item described in \luavar{item_data_list} is assumed to be on the same page.
% \begin{macrocode}
local function compute_items_horizontal(item_data_list,page_data)
% \end{macrocode}
% Immediately return if \luavar{item_data_list} is empty, to avoid edge cases.
% \begin{macrocode}
if #item_data_list == 0 then
return
end
% \end{macrocode}
% Information used frequently and which is the same for every item.
% \begin{macrocode}
local pageno = item_data_list[1][KEY_PAGENO]
local twoside = page_data[KEY_TWOSIDE]
local recto = ((pageno % 2) == 1) or (not twoside)
local columncount = page_data[KEY_COLUMNCOUNT]
% \end{macrocode}
% Tables to contain the \(x\)-coordinates of left edge, right edge, and middle of the current text, whether a single
% column (index 0), the left column (index 1), or the right column (index 2).
% \begin{macrocode}
local x_textleft = {}
local x_textright = {}
local x_textmiddle = {}
% \end{macrocode}
% First, compute necessary dimensions for single-column text, since most of these calculations would be used anyway
% for two-column text. The terms used in calculating \luavar{x_textleft[0]} respectively take one to the origin of
% \cs{hoffset}, to the origin of \cs{oddsidemargin} and \cs{evensidemargin}, and to the left-hand side of the text
% block.
% \begin{macrocode}
if recto then
x_textleft[0] = (
page_data[KEY_HOFFSETORIGIN]
+ page_data[KEY_HOFFSET]
+ page_data[KEY_ODDSIDEMARGIN]
)
x_textright[0] = (
x_textleft[0]
+ page_data[KEY_TEXTWIDTH]
)
else
x_textleft[0] = (
page_data[KEY_HOFFSETORIGIN]
+ page_data[KEY_HOFFSET]
+ page_data[KEY_EVENSIDEMARGIN]
)
x_textright[0] = (
x_textleft[0]
+ page_data[KEY_TEXTWIDTH]
)
end
x_textmiddle[0] = (x_textleft[0] + x_textright[0])/2
if columncount == 1 then
% \end{macrocode}
% If the page is one-column, the field \luavar{KEY_COLNO_COMPUTED} can be set immediately for every item_data.
% \begin{macrocode}
for i=1,#item_data_list do
item_data_list[i][KEY_COLNO_COMPUTED] = 0
end
else
% \end{macrocode}
% If the page is two-column, calculate the \(x\)-coordinates of the left and right edges and the mid-point of each
% column.
% \begin{macrocode}
x_textleft[1] = x_textleft[0]
x_textright[1] = (
x_textleft[1]
+ page_data[KEY_COLUMNWIDTH]
)
x_textmiddle[1] = (x_textleft[1] + x_textright[1])/2
x_textleft[2] = (
x_textright[1]
+ page_data[KEY_COLUMNSEP]
)
x_textright[2] = (
x_textleft[2]
+ page_data[KEY_COLUMNWIDTH]
)
x_textmiddle[2] = (x_textleft[2] + x_textright[2])/2
% \end{macrocode}
% Calculate the cut-off (mid-way between the columns) that distinguishes items from left and right columns.
% \begin{macrocode}
local left_column_x_limit = (
x_textright[1]
+ .5*page_data[KEY_COLUMNSEP]
)
% \end{macrocode}
% Now set the field \luavar{KEY_COLNO_COMPUTED} for each item.
% \begin{macrocode}
for i=1,#item_data_list do
local item_data = item_data_list[i]
if item_data[KEY_COLUMN] >= 0 then
item_data[KEY_COLNO_COMPUTED] = item_data[KEY_COLUMN]
else
if item_data[KEY_XPOS] <= left_column_x_limit then
item_data[KEY_COLNO_COMPUTED] = 1
else
item_data[KEY_COLNO_COMPUTED] = 2
end
end
end
end
% \end{macrocode}
% For every item_data in item_data_list, compute and set the fields \luavar{KEY_SIDE_COMPUTED},
% \luavar{KEY_XSHIFT_COMPUTED}, and \luavar{KEY_MARGINNO_COMPUTED}.
% \begin{macrocode}
for i=1,#item_data_list do
local item = item_data_list[i]
local pos = item[KEY_POS]
local colnocomputed = item[KEY_COLNO_COMPUTED]
if pos == POS_LEFT then
rightside = false
elseif pos == POS_RIGHT then
rightside = true
elseif pos == POS_NEAREST then
rightside = (item[KEY_XPOS] >= x_textmiddle[colnocomputed])
else
% \end{macrocode}
% \luavar{pos} must be POS_AUTO or POS_REVERSE
% \begin{macrocode}
rightside = RIGHTSIDE_LOOKUP_TABLE[recto][colnocomputed][pos]
end
local marginno = MARGINNO_LOOKUP_TABLE[recto][colnocomputed][rightside]
if rightside then
item[KEY_SIDE_COMPUTED] = 0
item[KEY_XSHIFT_COMPUTED] = -item[KEY_XPOS]
+ x_textright[colnocomputed]
else
item[KEY_SIDE_COMPUTED] = 1
item[KEY_XSHIFT_COMPUTED] = -item[KEY_XPOS]
+ x_textleft[colnocomputed]
end
item[KEY_MARGINNO_COMPUTED] = marginno
end
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{get_y_item_top}
% Return the \(y\)-coordinate of the top of the item described by \luavar{item_data}.
% \begin{macrocode}
local function get_y_item_top(item_data)
return item_data[KEY_YPOS]
+ item_data[KEY_YSHIFT_COMPUTED]
+ item_data[KEY_HEIGHT]
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{get_y_item_bottom}
% Return the \(y\)-coordinate of the bottom of the item described by \luavar{item_data}.
% \begin{macrocode}
local function get_y_item_bottom(item_data)
return item_data[KEY_YPOS]
- item_data[KEY_DEPTH]
+ item_data[KEY_YSHIFT_COMPUTED]
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{get_ysep_list}
% Calculate the separation to be used between adjacent marginal content items as described in
% \luavar{item_data_list}. The list is assumed to be sorted so that items are in the order they should appear on the
% page, top to bottom.
%
% The idea is that we have the following arrangement for \(i = 1,\ldots,\luavar{\#item_data_list}\):
% {
% \null~~~~~~\(\vdots\)\\
% \null~~~~\luavar{item_data_list[i]}\\
% \null~~~~~~\luavar{ysep_list[i]}\\
% \null~~~~\luavar{item_data_list[i+1]}\\
% \null~~~~~~\(\vdots\)\\
% }
% Also set \luavar{ysep_list[0]} and \luavar{ysep_list[\#item_data_list]} to 0, to avoid checking when these values
% are accessed (although they are not used).
% \begin{macrocode}
local function get_ysep_list(item_data_list)
local ysep_list = {}
ysep_list[0] = 0
for i=1,#item_data_list-1 do
ysep_list[i] = math.max(
item_data_list[i][KEY_YSEP_BELOW],
item_data_list[i+1][KEY_YSEP_ABOVE]
)
end
ysep_list[#item_data_list] = 0
return ysep_list
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Computing vertical positions}
%
%
%
% \subsubsection{Computing \val{optfixed} enabled}
%
% \begin{macro}[int]{compute_items_vertical_optfixed_enabled}
% For every \luavar{item_data} in \luavar{item_data_list} describing an item of type \luavar{TYPE_OPTFIXED}, check
% for a clash with an item of type \luavar{TYPE_FIXED}. If so, set \luavar{item_data[KEY_ENABLED_COMPUTED]} to
% \luavar{false}. Every item described in \luavar{item_data_list} is assumed to be on the same page and to have
% \luavar{KEY_YSHIFT} set to the default.
% \begin{macrocode}
local function compute_items_vertical_optfixed_enabled(item_data_list)
local optfixed_item_data_list = {}
local fixed_item_data_list = {}
for _,item_data in pairs(item_data_list) do
if item_data[KEY_TYPE] == TYPE_OPTFIXED then
optfixed_item_data_list[#optfixed_item_data_list+1] = item_data
elseif item_data[KEY_TYPE] == TYPE_FIXED then
fixed_item_data_list[#fixed_item_data_list+1] = item_data
end
end
for _,optfixed_item_data in pairs(optfixed_item_data_list) do
local optfixed_y_item_top = get_y_item_top(optfixed_item_data)
local optfixed_y_item_bottom = get_y_item_bottom(optfixed_item_data)
for _,fixed_item_data in pairs(fixed_item_data_list) do
local fixed_y_item_top = get_y_item_top(fixed_item_data)
local fixed_y_item_bottom = get_y_item_bottom(fixed_item_data)
if (
(
(fixed_y_item_bottom - optfixed_y_item_top)
<
math.max(
fixed_item_data[KEY_YSEP_BELOW],
optfixed_item_data[KEY_YSEP_ABOVE]
)
)
and
(
(optfixed_y_item_bottom - fixed_y_item_top)
<
math.max(
optfixed_item_data[KEY_YSEP_BELOW],
fixed_item_data[KEY_YSEP_ABOVE]
)
)
) then
optfixed_item_data[KEY_ENABLED_COMPUTED] = false
break
end
end
end
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Computing vertical adjustment}
%
% \begin{macro}[int]{compute_items_vertical_adjustment}
% For every \luavar{item_data} in \luavar{item_data_list}, compute the field relevant to vertical positioning,
% namely \luavar{KEY_YSHIFT_COMPUTED}, based on the layout information in \luavar{page_data}. Every item described
% in \luavar{item_data_list} is assumed to be on the same page and to have \luavar{KEY_YSHIFT} set to the default,
% and the list is assumed to be sorted so that items are in the order they should appear on the page, top to bottom.
% \begin{macrocode}
local function compute_items_vertical_adjustment(item_data_list,page_data)
% \end{macrocode}
% Immediately return if \luavar{item_data_list} is empty, to avoid edge cases
% \begin{macrocode}
if #item_data_list == 0 then
return
end
local ysep_list = get_ysep_list(item_data_list)
% \end{macrocode}
% \textit{First pass of computation (downward).} \luavar{y_limit_above} will always be the highest \(y\)-coordinate
% at which the top of next item below can appear.
% \begin{macrocode}
local y_limit_above = (
page_data[KEY_VOFFSET]
+ page_data[KEY_PAPERHEIGHT]
- item_data_list[1][KEY_YSEP_PAGE_TOP]
)
for i=1,#item_data_list do
local item_data = item_data_list[i]
local y_item_top = get_y_item_top(item_data)
if y_item_top > y_limit_above then
if item_data[KEY_TYPE] == TYPE_NORMAL then
item_data[KEY_YSHIFT_COMPUTED] = item_data[KEY_YSHIFT_COMPUTED]
+ (y_limit_above - y_item_top)
end
end
y_limit_above = get_y_item_bottom(item_data) - ysep_list[i]
end
% \end{macrocode}
% \textit{Second pass of computation (upward)}. \luavar{y_limit_below} will always be the lowest \(y\)-coordinate at
% which the bottom of next item above can appear.
% \begin{macrocode}
local y_limit_below = (
page_data[KEY_VOFFSET]
+ item_data_list[#item_data_list][KEY_YSEP_PAGE_BOTTOM]
)
for i=#item_data_list,1,-1 do
local item_data = item_data_list[i]
local y_item_bottom = get_y_item_bottom(item_data)
if y_item_bottom < y_limit_below then
if item_data[KEY_TYPE] == TYPE_NORMAL then
item_data[KEY_YSHIFT_COMPUTED] = item_data[KEY_YSHIFT_COMPUTED]
+ (y_limit_below - y_item_bottom)
end
end
y_limit_below = get_y_item_top(item_data) + ysep_list[i-1]
end
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Checking vertical adjustment}
%
% Messages to use when checking results of vertical adjustment.
% \begin{macrocode}
local ITEM_PASSED_YSEP_PAGE_TOP_MESSAGES = {
[TYPE_NORMAL] = 'Moveable item > ysep page top',
[TYPE_FIXED] = 'Topmost fixed item > ysep page top',
[TYPE_OPTFIXED] = 'Topmost optfixed item > ysep page top',
}
local ITEM_CLASH_MESSAGES = {
[TYPE_NORMAL] = {
[TYPE_NORMAL] = 'moveable items'
.. ' (this shouldn\'t happen)',
[TYPE_FIXED] = 'moveable item above fixed item',
[TYPE_OPTFIXED] = 'moveable item above optfixed item',
},
[TYPE_FIXED] = {
[TYPE_NORMAL] = 'moveable item below fixed item',
[TYPE_FIXED] = 'fixed items',
[TYPE_OPTFIXED] = 'fixed item above optfixed item '
.. '(this shouldn\'t happen)',
},
[TYPE_OPTFIXED] = {
[TYPE_NORMAL] = 'moveable items below optfixed item',
[TYPE_FIXED] = 'fixed item below optfixed item '
.. '(this shouldn\'t happen)',
[TYPE_OPTFIXED] = 'optfixed items '
.. '(this shouldn\'t happen)',
},
}
local ITEM_PASSED_YSEP_PAGE_BOTTOM_MESSAGE = {
[TYPE_NORMAL] = 'Moveable item < ysep page bottom',
[TYPE_FIXED] = 'Bottommost fixed item < ysep page bottom',
[TYPE_OPTFIXED] = 'Bottommost optfixed item < ysep page bottom',
}
% \end{macrocode}
%
% \begin{macro}[int]{check_items_vertical}
% For the items described by the item_data in \luavar{item_data_list}, check whether any clash or fail to obey
% \key{ysep page top} or \key{ysep page bottom}. If so, write messages to \luavar{PROBLEM_REPORT_TABLE}.
% \begin{macrocode}
local function check_items_vertical(item_data_list,page_data)
% \end{macrocode}
% Immediately return if item_data_list is empty, to avoid edge cases
% \begin{macrocode}
if (#item_data_list) == 0 then
return
end
local ysep_list = get_ysep_list(item_data_list)
local item_data
% \end{macrocode}
% If any item fails to obey \key{ysep page top}, the first one in the list does.
% \begin{macrocode}
item_data = item_data_list[1]
if (
get_y_item_top(item_data) > page_data[KEY_VOFFSET]
+ page_data[KEY_PAPERHEIGHT]
- item_data[KEY_YSEP_PAGE_TOP]
) then
table.insert(
PROBLEM_REPORT_TABLE,
get_data_page_number(item_data)
.. ' ' .. ITEM_PASSED_YSEP_PAGE_TOP_MESSAGES[item_data[KEY_TYPE]]
)
end
for i=2,#item_data_list do
local item_data = item_data_list[i]
local prev_item_data = item_data_list[i-1]
if (
get_y_item_top(item_data) > get_y_item_bottom(prev_item_data)
- ysep_list[i-1]
) then
table.insert(
PROBLEM_REPORT_TABLE,
get_data_page_number(item_data)
.. ' Clash: ' ..
ITEM_CLASH_MESSAGES[prev_item_data[KEY_TYPE]][item_data[KEY_TYPE]]
)
end
end
% \end{macrocode}
% If any item fails to obey \key{ysep page bottom}, the last one in the list does.
% \begin{macrocode}
item_data = item_data_list[#item_data_list]
if (
get_y_item_bottom(item_data) < page_data[KEY_VOFFSET]
+ item_data[KEY_YSEP_PAGE_BOTTOM]
) then
table.insert(
PROBLEM_REPORT_TABLE,
get_data_page_number(item_data)
.. ' ' .. ITEM_PASSED_YSEP_PAGE_BOTTOM_MESSAGE[item_data[KEY_TYPE]]
)
end
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsubsection{Core vertical position computation}
%
% \begin{macro}[int]{compute_items_vertical}
% For every \luavar{item_data} in \luavar{item_data_list}, compute the field relevant to vertical positioning,
% namely \luavar{KEY_YSHIFT_COMPUTED}, based on the layout information in \luavar{page_data}. This may involve
% setting the field \luavar{KEY_ENABLED_COMPUTED} to false. In such a case, the relevant item_data is removed from
% \luavar{item_data_list}.
% \begin{macrocode}
local function compute_items_vertical(item_data_list,page_data)
% \end{macrocode}
% Set \luavar{KEY_YSHIFT_COMPUTED} of each \luavar{item_data} to the user-supplied value.
% \begin{macrocode}
for i=1,#item_data_list do
local item_data = item_data_list[i]
item_data[KEY_YSHIFT_COMPUTED] = item_data[KEY_YSHIFT]
end
% \end{macrocode}
% Decide which items of type \luavar{ITEM_DATA_OPTFIXED} are to be disabled.
% \begin{macrocode}
compute_items_vertical_optfixed_enabled(item_data_list)
% \end{macrocode}
% Strip any \luavar{item_data} with \luavar{KEY_ENABLED_COMPUTED} set to false from \luavar{item_data_list}.
% \begin{macrocode}
list_filter(item_data_list,function(item_data)
return item_data[KEY_ENABLED_COMPUTED]
end)
% \end{macrocode}
% Sort \luavar{item_data_list} according to the stored position from top to bottom and left to right on the page,
% resolving ties using \luavar{KEY_ITEMNO}.
% \begin{macrocode}
table.sort(
item_data_list,
function(left,right)
local y_diff = left[KEY_YPOS] - right[KEY_YPOS]
if y_diff > 0 then
return true
elseif y_diff < 0 then
return false
end
local x_diff = left[KEY_XPOS] - right[KEY_XPOS]
if x_diff < 0 then
return true
elseif x_diff > 0 then
return false
end
return (left[KEY_ITEMNO] < right[KEY_ITEMNO])
end
)
compute_items_vertical_adjustment(item_data_list,page_data)
check_items_vertical(item_data_list,page_data)
end
% \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{compute_items}
% For every item represented in \luavar{ITEM_DATA_MAIN_TABLE}, use the \luavar{page_data} stored in
% \luavar{PAGE_DATA_MAIN_TABLE} to compute the item_data values necessary to place the item correctly on the page,
% namely those indexed by: \luavar{KEY_COLNO_COMPUTED}, \luavar{KEY_XSHIFT_COMPUTED}, \luavar{KEY_YSHIFT_COMPUTED},
% \luavar{KEY_SIDE_COMPUTED}, \luavar{KEY_ENABLED_COMPUTED}.
% \begin{macrocode}
local function compute_items()
% \end{macrocode}
% Compute the maximum abspageno, which will be the last page of the document on which a item appears.
% \begin{macrocode}
local max_abspageno = 0
for k,v in pairs(ITEM_DATA_MAIN_TABLE) do
max_abspageno = math.max(v[KEY_ABSPAGENO],max_abspageno)
end
% \end{macrocode}
% \luavar{list per_abspage_item_data_list} will be a list indexed by absolute page numbers. Each entry will be a
% list (possibly empty) of \luavar{item_data} describing the items that appear on the corresponding page.
% \begin{macrocode}
local per_abspage_item_data_list = {}
% \end{macrocode}
% Prepare \luavar{per_abspage_item_data_list} by making each entry an empty list, then fill it from
% \luavar{ITEM_DATA_MAIN_TABLE}.
% \begin{macrocode}
for i=1,max_abspageno do
per_abspage_item_data_list[i] = {}
end
for _,item_data in pairs(ITEM_DATA_MAIN_TABLE) do
local temp_table = per_abspage_item_data_list[item_data[KEY_ABSPAGENO]]
temp_table[#temp_table+1] = item_data
end
% \end{macrocode}
% \luavar{per_abspage_item_data_list} will be a list indexed by abssolute page numbers. Each entry will be a
% \luavar{page_data} describing the corresponding page. Usually multiple entries will be the same
% \luavar{page_data}: in the loop, \luavar{pagedatano} will be the index of the last entry in
% \luavar{PAGE_DATA_MAIN_TABLE} with \luavar{KEY_ABSPAGENO} value less than or equal to \luavar{abspageno}. (There
% may be several such entries in \luavar{PAGE_DATA_MAIN_TABLE} because \cs{marginalianewgeometry} may have been
% called multiple times on the same page.) Note that \luavar{PAGE_DATA_MAIN_TABLE[0]} is available even if there was
% no data in the \file{.aux} file, because the defaults were stored by \luafunc{store_default_page_data}.
% \begin{macrocode}
local per_abspage_page_data_list = {}
% \end{macrocode}
% \begin{macrocode}
local pagedatano = 0
for abspageno = 1,max_abspageno do
% \end{macrocode}
% \begin{macrocode}
while (
PAGE_DATA_MAIN_TABLE[pagedatano+1] ~= nil
and
PAGE_DATA_MAIN_TABLE[pagedatano+1][KEY_ABSPAGENO] == abspageno
) do
pagedatano = pagedatano+1
end
per_abspage_page_data_list[abspageno] = PAGE_DATA_MAIN_TABLE[pagedatano]
end
% \end{macrocode}
% Iterate through all pages and perform the necessary computations.
% \begin{macrocode}
for abspageno=1,#per_abspage_item_data_list do
local current_page_data = per_abspage_page_data_list[abspageno]
local current_page_item_data_list = per_abspage_item_data_list[abspageno]
% \end{macrocode}
% First, compute the horizontal positions, which includes sorting items into columns in two-column mode.
% \begin{macrocode}
compute_items_horizontal(current_page_item_data_list,current_page_data)
% \end{macrocode}
% Sort the items into sublists corresponding to the margins in which they are located.
% \begin{macrocode}
local current_page_item_data_sublists = {}
for i=0,5 do
current_page_item_data_sublists[i] = {}
end
for _,item_data in pairs(current_page_item_data_list) do
table.insert(
current_page_item_data_sublists[item_data[KEY_MARGINNO_COMPUTED]],
item_data
)
end
% \end{macrocode}
% Compute vertical positons for each sublist.
% \begin{macrocode}
for i=0,5 do
compute_items_vertical(
current_page_item_data_sublists[i],
current_page_data
)
end
end
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Passing item_data back to \LaTeX}
%
% \begin{macro}[int]{load_item_data}
% Set the relevant \LaTeX\ counter and dimension variables to the values computed for \luavar{itemno}.
% \begin{macrocode}
local function load_item_data(itemno)
item = ITEM_DATA_MAIN_TABLE[tonumber(itemno)]
if item == nil then
item = ITEM_DATA_DEFAULTS
end
tex.count['l__marginalia_page_int'] = item[KEY_PAGENO]
tex.count['l__marginalia_column_computed_int'] = item[KEY_COLNO_COMPUTED]
tex.dimen['l__marginalia_xshift_computed_dim'] = item[KEY_XSHIFT_COMPUTED]
tex.dimen['l__marginalia_yshift_computed_dim'] = item[KEY_YSHIFT_COMPUTED]
tex.count['l__marginalia_side_computed_int'] = item[KEY_SIDE_COMPUTED]
tex.count['l__marginalia_marginno_computed_int']
= item[KEY_MARGINNO_COMPUTED]
if item[KEY_ENABLED_COMPUTED] then
tex.count['l__marginalia_enabled_computed_int'] = 1
else
tex.count['l__marginalia_enabled_computed_int'] = 0
end
end
% \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Export public functions}
%
% Finally, make available the functions that will be called from \LaTeX\ using \cs{lua_now:n} and \cs{lua_now:e}.
% \begin{macrocode}
return {
store_default_page_data = store_default_page_data,
store_page_data = store_page_data,
check_page_data = check_page_data,
store_item_data = store_item_data,
check_item_data = check_item_data,
compute_items = compute_items,
load_item_data = load_item_data,
write_problem_report = write_problem_report,
write_page_change_report = write_page_change_report,
write_item_change_report = write_item_change_report,
}
% \end{macrocode}
%
%
%
% \begin{macrocode}
%</lua>
% \end{macrocode}
%
%
%
% \clearpage
% \end{implementation}