| 1 |
\documentclass{article} |
| 2 |
\usepackage{graphicx,listings,booktabs,lmodern} |
| 3 |
|
| 4 |
\newcommand*\pgsmall{\fontsize{8.5}{8.7}\selectfont\ttfamily} |
| 5 |
\lstset{basicstyle=\pgsmall, |
| 6 |
basewidth=0.55em, |
| 7 |
columns=fullflexible, |
| 8 |
breakautoindent=true, |
| 9 |
breaklines=true, |
| 10 |
prebreak=, |
| 11 |
postbreak=\mbox{$\hookrightarrow$}, |
| 12 |
} |
| 13 |
|
| 14 |
\begin{document} |
| 15 |
\title{The lua-visual-debug package (V1.1)} |
| 16 |
\author{Patrick Gundlach, Udi Fogiel} |
| 17 |
% \address{[email protected]} |
| 18 |
\maketitle |
| 19 |
|
| 20 |
\tableofcontents |
| 21 |
\section{About} |
| 22 |
|
| 23 |
This package aids debugging your \TeX\ and \LaTeX\ document by drawing |
| 24 |
rectangles around boxes and rules where glue is inserted. |
| 25 |
Other items are marked as well: kerns, hyphenation points and penalties. |
| 26 |
|
| 27 |
\section{How to use} |
| 28 |
|
| 29 |
When you load the package \texttt{lua-visual-debug} in your Lua\LaTeX\ document |
| 30 |
(or use \verb|\input lua-visual-debug.sty| in plain \TeX, or \verb|\load[lua-visual-debug]| in OP\TeX), |
| 31 |
Lua\TeX\ will highlight boxes, penalties, glues and kerns in the PDF. |
| 32 |
This package requires you to process the document with Lua\TeX\ (plain, \LaTeX\ or OP\TeX\ formats). |
| 33 |
|
| 34 |
\section{A \LaTeX\ example} |
| 35 |
\lstinputlisting[language=tex]{sample.tex} |
| 36 |
|
| 37 |
\noindent yields \vspace{5mm} |
| 38 |
|
| 39 |
\noindent \includegraphics[width=\textwidth]{sample.pdf} |
| 40 |
|
| 41 |
\section{A plain \TeX\ example} |
| 42 |
|
| 43 |
\lstinputlisting[language=tex]{sample-plain.tex} |
| 44 |
|
| 45 |
\noindent yields \vspace{5mm} |
| 46 |
|
| 47 |
\noindent \includegraphics[width=\textwidth]{sample-plain.pdf} |
| 48 |
|
| 49 |
\section{How to interpret the markers} % (fold) |
| 50 |
\label{sec:how_to_interpret_the_markers} |
| 51 |
|
| 52 |
\noindent\includegraphics[width=.9\textwidth]{lvdebugdetail1-num} |
| 53 |
\begin{enumerate} |
| 54 |
\item A vertical glue. Beginning and end are marked with a small tick. At the mark 1, two vertical glues are connected. |
| 55 |
\item A horizontal glue. Blue dashed lines represent stretched glues, magenta lines represent shrunk glues, gray at their natural width. |
| 56 |
\item A negative kern. Positive kerns are yellow. |
| 57 |
\item A possible hyphenation point. |
| 58 |
\item Horizontal and vertical boxes are drawn with a border. |
| 59 |
\item Penalties are marked with a square. A penalty of 10,000 is marked with a blank square, a penalty less than 10,000 is filled with a gray square (that will improve in the future, currently it is grayness of penalty / 10000). |
| 60 |
\end{enumerate} |
| 61 |
|
| 62 |
A strut box (zero width box) is marked with a red rule: |
| 63 |
|
| 64 |
\noindent\includegraphics[scale=0.8]{strut} |
| 65 |
|
| 66 |
% section how_to_interpret_the_ (end) |
| 67 |
|
| 68 |
\newpage |
| 69 |
|
| 70 |
\section{Configuration} |
| 71 |
If the \texttt{luakeyval} package is installed, then you can use the |
| 72 |
\verb|\lvdset| macro modifies the markers described in Section~\ref{sec:how_to_interpret_the_markers}. |
| 73 |
It accepts a list of space-separated \texttt{key/val} pairs. Most keys accept nested \texttt{key/val} pairs |
| 74 |
enclosed in curly braces. PDF operators (for \texttt{color}, \texttt{negative\_color}, and \texttt{opacity}) |
| 75 |
must be enclosed in curly braces, e.g., \verb|\lvdset{glyph={color={1 0 0 RG}}}|. |
| 76 |
|
| 77 |
\medskip |
| 78 |
\noindent |
| 79 |
\begin{tabular}{@{}lllp{6cm}@{}} |
| 80 |
\toprule |
| 81 |
\textbf{Key} & \textbf{Sub-key} & \textbf{Default} & \textbf{Description} \\ |
| 82 |
\midrule |
| 83 |
\texttt{hlist} & \texttt{show} & \texttt{true} & Whether to mark hlists \\ |
| 84 |
& \texttt{color} & \texttt{0.5 G} & PDF stroking color operator \\ |
| 85 |
& \texttt{width} & \texttt{0.1} & Line width in bp units \\ |
| 86 |
\midrule |
| 87 |
\texttt{vlist} & \texttt{show} & \texttt{true} & Whether to mark vlists \\ |
| 88 |
& \texttt{color} & \texttt{0.1 G} & PDF stroking color operator \\ |
| 89 |
& \texttt{width} & \texttt{0.1} & Line width in bp units \\ |
| 90 |
\midrule |
| 91 |
\texttt{rule} & \texttt{show} & \texttt{true} & Whether to mark rules \\ |
| 92 |
& \texttt{color} & \texttt{1 0 0 RG} & PDF stroking color operator \\ |
| 93 |
& \texttt{width} & \texttt{0.4} & Line width in bp units \\ |
| 94 |
\midrule |
| 95 |
\texttt{disc} & \texttt{show} & \texttt{true} & Whether to mark discretionaries \\ |
| 96 |
& \texttt{color} & \texttt{0 0 1 RG} & PDF stroking color operator \\ |
| 97 |
& \texttt{width} & \texttt{0.3} & Line width in bp units \\ |
| 98 |
\midrule |
| 99 |
\texttt{glue} & \texttt{show} & \texttt{true} & Whether to mark glue \\ |
| 100 |
\midrule |
| 101 |
\texttt{kern} & \texttt{show} & \texttt{true} & Whether to mark kerns \\ |
| 102 |
& \texttt{color} & \texttt{1 1 0 rg} & PDF color for positive kerns (stroke and fill) \\ |
| 103 |
& \texttt{negative\_color} & \texttt{1 0 0 rg} & PDF color for negative kerns (stroke and fill) \\ |
| 104 |
& \texttt{width} & \texttt{1} & Line width in bp units \\ |
| 105 |
\midrule |
| 106 |
\texttt{penalty} & \texttt{show} & \texttt{true} & Whether to mark penalties \\ |
| 107 |
& \texttt{colorfunc} & (see below) & Lua function that accepts the penalty value and returns a PDF color string \\ |
| 108 |
\midrule |
| 109 |
\texttt{glyph} & \texttt{show} & \texttt{false} & Whether to mark glyphs \\ |
| 110 |
& \texttt{color} & \texttt{1 0 0 RG} & PDF stroking color operator \\ |
| 111 |
& \texttt{width} & \texttt{0.1} & Line width in bp units \\ |
| 112 |
& \texttt{baseline} & \texttt{true} & Whether to mark the baseline \\ |
| 113 |
\midrule |
| 114 |
\texttt{onlyglyphs} & — & — & Shortcut to disable all markers except glyphs \\ |
| 115 |
\midrule |
| 116 |
\texttt{opacity} & — & (empty) & PDF graphics state operator for transparency \\ |
| 117 |
\bottomrule |
| 118 |
\end{tabular} |
| 119 |
|
| 120 |
\medskip |
| 121 |
\noindent |
| 122 |
\textit{Notes:} |
| 123 |
\begin{itemize} |
| 124 |
\item The \texttt{kern} key uses both stroke and fill colors, unlike other keys which only use stroking color. |
| 125 |
\item The \texttt{onlyglyphs} key is a boolean flag (no value needed) that sets all \texttt{show} keys to \texttt{false} except \texttt{glyph/show}, which is set to \texttt{true}. |
| 126 |
\item The \texttt{opacity} key applies to all node types. For fine-tuned opacity control per node type, the \texttt{color} keys can be (ab)used to include graphics state operators. |
| 127 |
\end{itemize} |
| 128 |
|
| 129 |
\medskip |
| 130 |
\noindent |
| 131 |
The default \texttt{colorfunc} for penalties is: |
| 132 |
\begin{verbatim} |
| 133 |
function(p) |
| 134 |
local color = "1 g" |
| 135 |
if p < 10000 then |
| 136 |
color = string.format("%g g", 1 - math.floor(p / 10000)) |
| 137 |
end |
| 138 |
return color |
| 139 |
end |
| 140 |
\end{verbatim} |
| 141 |
|
| 142 |
An example of the usage of the keys is |
| 143 |
\lstinputlisting[language=tex]{sample-keys.tex} |
| 144 |
|
| 145 |
\noindent which yields \vspace{5mm} |
| 146 |
|
| 147 |
\noindent \includegraphics[width=\textwidth]{sample-keys.pdf} |
| 148 |
|
| 149 |
You can also access and assign the parameters from lua with the \texttt{params} table. |
| 150 |
For example |
| 151 |
\begin{verbatim} |
| 152 |
local params = require('lua-visual-debug').params |
| 153 |
params.hlist.color = "1 0 0 RG" |
| 154 |
\end{verbatim} |
| 155 |
|
| 156 |
|
| 157 |
\section{Copying} |
| 158 |
|
| 159 |
Copyright 2012–2025 Patrick Gundlach ([email protected]) and other authors (see Git for information), |
| 160 |
licensed under the MIT license. See the \verb|lua-visual-debug.lua| file for details. |
| 161 |
|
| 162 |
|
| 163 |
\end{document} |