\documentclass{article}
\usepackage{graphicx,listings,booktabs,lmodern}

\newcommand*\pgsmall{\fontsize{8.5}{8.7}\selectfont\ttfamily}
\lstset{basicstyle=\pgsmall,
  basewidth=0.55em,
  columns=fullflexible,
  breakautoindent=true,
  breaklines=true,
  prebreak=,
  postbreak=\mbox{$\hookrightarrow$},
}

\begin{document}
\title{The lua-visual-debug package (V1.0)}
\author{Patrick Gundlach, Udi Fogiel}
% \address{patrick@gundla.ch}
\maketitle

\tableofcontents
\section{About}

This package aids debugging your \TeX\ and \LaTeX\ document by drawing 
rectangles around boxes and rules where glue is inserted.
Other items are marked as well: kerns, hyphenation points and penalties.

\section{How to use}

When you load the package \texttt{lua-visual-debug} in your Lua\LaTeX\ document 
(or use \verb|\input lua-visual-debug.sty| in plain \TeX, or \verb|\load[lua-visual-debug]| in OP\TeX),
Lua\TeX\ will highlight boxes, penalties, glues and kerns in the PDF.
This package requires you to process the document with Lua\TeX\ (plain, \LaTeX or OP\TeX formats).

\section{A \LaTeX\ example}
\lstinputlisting[language=tex]{sample.tex}

\noindent yields \vspace{5mm}

\noindent \includegraphics[width=\textwidth]{sample.pdf}

\section{A plain \TeX\ example}

\lstinputlisting[language=tex]{sample-plain.tex}

\noindent yields \vspace{5mm}

\noindent \includegraphics[width=\textwidth]{sample-plain.pdf}

\section{How to interpret the markers} % (fold)
\label{sec:how_to_interpret_the_markers}

\noindent\includegraphics[width=.9\textwidth]{lvdebugdetail1-num}
\begin{enumerate}
\item A vertical glue. Beginning and end are marked with a small tick. At the mark 1, two vertical glues are connected.
\item A horizontal glue. Blue dashed lines represent stretched glues, magenta lines represent shrunk glues, gray at their natural width.
\item A negative kern. Positive kerns are yellow.
\item A possible hyphenation point.
\item Horizontal and vertical boxes are drawn with a border.
\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).
\end{enumerate}

A strut box (zero width box) is marked with a red rule:

\noindent\includegraphics[scale=0.8]{strut}

% section how_to_interpret_the_ (end)

\newpage

\section{Configuration}
The \verb|\lvdset| macro modifies the markers described in Section~\ref{sec:how_to_interpret_the_markers}.
It accepts a list of space-separated \texttt{key/val} pairs. Most keys accept nested \texttt{key/val} pairs 
enclosed in curly braces. PDF operators (for \texttt{color}, \texttt{negative\_color}, and \texttt{opacity}) 
must be enclosed in curly braces, e.g., \verb|\lvdset{glyph={color={1 0 0 RG}}}|.

\medskip
\noindent
\begin{tabular}{@{}lllp{6cm}@{}}
\toprule
\textbf{Key} & \textbf{Sub-key} & \textbf{Default} & \textbf{Description} \\
\midrule
\texttt{hlist} & \texttt{show} & \texttt{true} & Whether to mark hlists \\
               & \texttt{color} & \texttt{0.5 G} & PDF stroking color operator \\
               & \texttt{width} & \texttt{0.1} & Line width in bp units \\
\midrule
\texttt{vlist} & \texttt{show} & \texttt{true} & Whether to mark vlists \\
               & \texttt{color} & \texttt{0.1 G} & PDF stroking color operator \\
               & \texttt{width} & \texttt{0.1} & Line width in bp units \\
\midrule
\texttt{rule} & \texttt{show} & \texttt{true} & Whether to mark rules \\
              & \texttt{color} & \texttt{1 0 0 RG} & PDF stroking color operator \\
              & \texttt{width} & \texttt{0.4} & Line width in bp units \\
\midrule
\texttt{disc} & \texttt{show} & \texttt{true} & Whether to mark discretionaries \\
              & \texttt{color} & \texttt{0 0 1 RG} & PDF stroking color operator \\
              & \texttt{width} & \texttt{0.3} & Line width in bp units \\
\midrule
\texttt{glue} & \texttt{show} & \texttt{true} & Whether to mark glue \\
\midrule
\texttt{kern} & \texttt{show} & \texttt{true} & Whether to mark kerns \\
              & \texttt{color} & \texttt{1 1 0 rg} & PDF color for positive kerns (stroke and fill) \\
              & \texttt{negative\_color} & \texttt{1 0 0 rg} & PDF color for negative kerns (stroke and fill) \\
              & \texttt{width} & \texttt{1} & Line width in bp units \\
\midrule
\texttt{penalty} & \texttt{show} & \texttt{true} & Whether to mark penalties \\
                 & \texttt{colorfunc} & (see below) & Lua function that accepts the penalty value and returns a PDF color string \\
\midrule
\texttt{glyph} & \texttt{show} & \texttt{false} & Whether to mark glyphs \\
               & \texttt{color} & \texttt{1 0 0 RG} & PDF stroking color operator \\
               & \texttt{width} & \texttt{0.1} & Line width in bp units \\
               & \texttt{baseline} & \texttt{true} & Whether to mark the baseline \\
\midrule
\texttt{onlyglyphs} & — & — & Shortcut to disable all markers except glyphs \\
\midrule
\texttt{opacity} & — & (empty) & PDF graphics state operator for transparency \\
\bottomrule
\end{tabular}

\medskip
\noindent
\textit{Notes:} 
\begin{itemize}
\item The \texttt{kern} key uses both stroke and fill colors, unlike other keys which only use stroking color.
\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}.
\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.
\end{itemize}

\medskip
\noindent
The default \texttt{colorfunc} for penalties is:
\begin{verbatim}
function(p) 
  local color = "1 g" 
  if p < 10000 then
    color = string.format("%g g", 1 - math.floor(p / 10000))
  end
  return color
end
\end{verbatim}

An example of the usage of the keys is
\lstinputlisting[language=tex]{sample-keys.tex}

\noindent which yields \vspace{5mm}

\noindent \includegraphics[width=\textwidth]{sample-keys.pdf}


\section{Copying}

Copyright 2012–2025 Patrick Gundlach (patrick@gundla.ch) and other authors (see Git for information),
licensed under the MIT license. See the \verb|lua-visual-debug.lua| file for details.


\end{document}