Debian Codegraph @

texmf-dist/doc/luatex/lua-visual-debug/lvdebug-doc.tex

raw
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}