summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/lua-visual-debug
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/luatex/generic/lua-visual-debug
Initial commit
Diffstat (limited to 'macros/luatex/generic/lua-visual-debug')
l---------macros/luatex/generic/lua-visual-debug/README.md1
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/README.md37
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.pdfbin0 -> 209760 bytes
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.tex70
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/lvdebugdetail1-num.pngbin0 -> 73328 bytes
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/sample-plain.pdfbin0 -> 49093 bytes
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/sample-plain.tex16
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/sample.pdfbin0 -> 45257 bytes
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/sample.tex32
-rw-r--r--macros/luatex/generic/lua-visual-debug/doc/strut.pngbin0 -> 11445 bytes
-rw-r--r--macros/luatex/generic/lua-visual-debug/lua-visual-debug.lua160
-rw-r--r--macros/luatex/generic/lua-visual-debug/lua-visual-debug.sty37
12 files changed, 353 insertions, 0 deletions
diff --git a/macros/luatex/generic/lua-visual-debug/README.md b/macros/luatex/generic/lua-visual-debug/README.md
new file mode 120000
index 0000000000..fd42db32e3
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/README.md
@@ -0,0 +1 @@
+doc/README.md \ No newline at end of file
diff --git a/macros/luatex/generic/lua-visual-debug/doc/README.md b/macros/luatex/generic/lua-visual-debug/doc/README.md
new file mode 100644
index 0000000000..a45bbcb16e
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/README.md
@@ -0,0 +1,37 @@
+Visual debugging for LuaTeX
+===========================
+
+The LuaTeX package `lua-visual-debug` shows boxes, glues, kerns and penalties in the PDF output.
+
+Usage:
+
+LaTeX:
+
+ \usepackage{lua-visual-debug}
+
+or (plain)
+
+ \input lua-visual-debug.sty
+
+
+
+Requirements: The package has only been tested with LuaTeX and
+ the formats plain and LaTeX. Other formats might work as well,
+ but other engines only show a warning message.
+
+
+Copyright 2012–2019 Patrick Gundlach (<patrick@gundla.ch>) and others (see Git information)
+
+Package version: 0.7
+
+Public repository: <https://github.com/pgundlach/lvdebug>
+
+Licensed under the MIT license. See the Lua file for details.
+
+The idea is heavily inspired by Hans Hagen's <http://pragma-ade.com/articles/art-visi.pdf>
+
+
+Example output
+--------------
+
+<p align="center"><img width="300px" src="https://i.imgur.com/S78jTxb.png"></p>
diff --git a/macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.pdf b/macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.pdf
new file mode 100644
index 0000000000..71b2936a29
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.pdf
Binary files differ
diff --git a/macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.tex b/macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.tex
new file mode 100644
index 0000000000..c87c2b49a4
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.tex
@@ -0,0 +1,70 @@
+\documentclass{article}
+\usepackage{graphicx,listings,lmodern,luatextra}
+\newcommand\pkgversion{0.7}
+
+\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 (V\pkgversion)}
+\author{Patrick Gundlach}
+% \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 \LuaLaTeX\ document (or use \verb|\input lua-visual-debug.sty| in plain \TeX), \LuaTeX\ will highlight boxes, penalties, glues and kerns in the PDF. This package requires you to process the document with \LuaTeX\ (plain and \LaTeX formats).
+
+\section{A \LaTeX\ example}
+\lstinputlisting[language=tex]{sample.tex}
+
+\noindent yields \vspace{5mm}
+
+\noindent \includegraphics[width=\textwidth]{sample-crop.pdf}
+
+\section{A plain \TeX\ example}
+
+\lstinputlisting[language=tex]{sample-plain.tex}
+
+\noindent yields \vspace{5mm}
+
+\noindent \includegraphics{sample-plain-crop.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.
+\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)
+
+
+\section{Copying}
+
+Copyright 2012–2019 Patrick Gundlach (patrick@gundla.ch) and other authors (see Git for information), licensed under the MIT license. See the Lua file for details.
+
+
+\end{document}
diff --git a/macros/luatex/generic/lua-visual-debug/doc/lvdebugdetail1-num.png b/macros/luatex/generic/lua-visual-debug/doc/lvdebugdetail1-num.png
new file mode 100644
index 0000000000..4c5fa553f8
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/lvdebugdetail1-num.png
Binary files differ
diff --git a/macros/luatex/generic/lua-visual-debug/doc/sample-plain.pdf b/macros/luatex/generic/lua-visual-debug/doc/sample-plain.pdf
new file mode 100644
index 0000000000..2aaafad75f
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/sample-plain.pdf
Binary files differ
diff --git a/macros/luatex/generic/lua-visual-debug/doc/sample-plain.tex b/macros/luatex/generic/lua-visual-debug/doc/sample-plain.tex
new file mode 100644
index 0000000000..da1e423238
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/sample-plain.tex
@@ -0,0 +1,16 @@
+\input lua-visual-debug.sty
+
+\hsize 3in \vsize 3in
+\centerline{A centered line with \TeX}
+
+\vskip .5in
+
+A wonderful serenity has taken possession of my entire soul, like these sweet
+mornings of spring which I enjoy with my whole heart. I am alone, and feel
+the charm of existence in this spot, which was created for the bliss of souls
+like mine. I am so happy, my dear friend, so absorbed in the exquisite sense
+of mere tranquil existence, that I neglect my talents.
+
+$$\int_e^x=mc^2$$
+
+\bye
diff --git a/macros/luatex/generic/lua-visual-debug/doc/sample.pdf b/macros/luatex/generic/lua-visual-debug/doc/sample.pdf
new file mode 100644
index 0000000000..81cf4fc223
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/sample.pdf
Binary files differ
diff --git a/macros/luatex/generic/lua-visual-debug/doc/sample.tex b/macros/luatex/generic/lua-visual-debug/doc/sample.tex
new file mode 100644
index 0000000000..aa9fbf1412
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/sample.tex
@@ -0,0 +1,32 @@
+\documentclass{article}
+\usepackage{lua-visual-debug}
+
+\usepackage{lmodern}
+\setlength\textwidth{300pt}
+\setlength\textheight{10cm}
+
+\begin{document}
+
+\section{A short story}
+
+A wonderful serenity has taken possession of my entire soul, like these sweet
+mornings of spring which I enjoy with my whole heart. I am alone, and feel
+the charm of existence in this spot, which was created for the bliss of souls
+like mine. I am so happy, my dear friend, so absorbed in the exquisite sense
+of mere tranquil existence, that I neglect my talents\footnote{A very special note for you}.
+
+\begin{itemize}
+ \item one
+ \item two
+ \item three
+\end{itemize}
+
+\bgroup\fontsize{30}{34}\selectfont
+\centerline{\TeX}
+\egroup
+
+\vbox{\strut Hello}\kern .5cm\vbox{\strut World}
+
+\[ \int_e^x=mc^2 \]
+
+\end{document}
diff --git a/macros/luatex/generic/lua-visual-debug/doc/strut.png b/macros/luatex/generic/lua-visual-debug/doc/strut.png
new file mode 100644
index 0000000000..c7cd0176af
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/doc/strut.png
Binary files differ
diff --git a/macros/luatex/generic/lua-visual-debug/lua-visual-debug.lua b/macros/luatex/generic/lua-visual-debug/lua-visual-debug.lua
new file mode 100644
index 0000000000..b6fb5907c9
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/lua-visual-debug.lua
@@ -0,0 +1,160 @@
+-- Copyright 2012-2019 Patrick Gundlach, patrick@gundla.ch
+-- Public repository: https://github.com/pgundlach/lvdebug (issues/pull requests,...)
+-- Version: 0.7
+
+-- Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the
+-- "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge,
+-- publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do
+-- so, subject to the following conditions:
+--
+-- The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+--
+-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+-- FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+-- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+module(...,package.seeall)
+
+-- There are 65782 scaled points in a PDF point
+-- Therefore we need to divide all TeX lengths by
+-- this amount to get the PDF points.
+local number_sp_in_a_pdf_point = 65782
+
+
+-- The idea is the following: at page shipout, all elements on a page are fixed.
+-- TeX creates an intermediate data structure before putting that into the PDF
+-- We can "intercept" that data structure and add pdf_literal (whatist) nodes,
+-- that makes glues, kerns and other items visible by drawing a rule, rectangle or
+-- other visual aids.
+-- This has no influence on typeset material, because these pdf_literal instructions
+-- are only visible to the PDF file (PDF renderer) and have no size themselves.
+
+-- We recursively loop through the contents of boxes and look at the (linear) list of
+-- items in that box. We start at the "shipout box".
+
+-- The "algorithm" goes like this:
+--
+-- head = pointer_to_beginning_of_box_material
+-- while head is not nil
+-- if this_item_is_a_box
+-- recurse_into_contents
+-- draw a rectangle around the contents
+-- elseif this_item_is_a_glue
+-- draw a rule that has the length of that glue
+-- elseif this_item_is_a_kern
+-- draw a rectangle with width of that kern
+-- ...
+-- end
+-- move pointer to the next item in the list
+-- -- the pointer is "nil" if there is no next item
+-- end
+
+local HLIST = node.id("hlist")
+local VLIST = node.id("vlist")
+local RULE = node.id("rule")
+local DISC = node.id("disc")
+local GLUE = node.id("glue")
+local KERN = node.id("kern")
+local PENALTY = node.id("penalty")
+
+function math.round(num, idp)
+ if idp and idp>0 then
+ local mult = 10^idp
+ return math.floor(num * mult + 0.5) / mult
+ end
+ return math.floor(num + 0.5)
+end
+
+
+function show_page_elements(parent)
+ local head = parent.list
+ while head do
+ if head.id == HLIST or head.id == VLIST then
+
+ local rule_width = 0.1
+ local wd = math.round(head.width / number_sp_in_a_pdf_point - rule_width ,2)
+ local ht = math.round((head.height + head.depth) / number_sp_in_a_pdf_point - rule_width ,2)
+ local dp = math.round(head.depth / number_sp_in_a_pdf_point - rule_width / 2 ,2)
+
+ -- recurse into the contents of the box
+ show_page_elements(head)
+ local rectangle = node.new("whatsit","pdf_literal")
+ if head.id == HLIST then -- hbox
+ rectangle.data = string.format("q 0.5 G %g w %g %g %g %g re s Q", rule_width, -rule_width / 2, -dp, wd, ht)
+ else
+ rectangle.data = string.format("q 0.1 G %g w %g %g %g %g re s Q", rule_width, -rule_width / 2, 0, wd, -ht)
+ end
+ head.list = node.insert_before(head.list,head.list,rectangle)
+
+
+ elseif head.id == RULE then
+ local show_rule = node.new("whatsit","pdf_literal")
+ if head.width == -1073741824 or head.height == -1073741824 or head.depth == -1073741824 then
+ -- ignore for now -- these rules are stretchable
+ else
+ local dp = math.round( head.depth / number_sp_in_a_pdf_point ,2)
+ local ht = math.round( head.height / number_sp_in_a_pdf_point ,2)
+ show_rule.data = string.format("q 1 0 0 RG 1 0 0 rg 0.4 w 0 %g m 0 %g l S Q",-dp,ht)
+ end
+ parent.list = node.insert_before(parent.list,head,show_rule)
+
+
+ elseif head.id == DISC then
+ local hyphen_marker = node.new("whatsit","pdf_literal")
+ hyphen_marker.data = "q 0 0 1 RG 0.3 w 0 -1 m 0 0 l S Q"
+ parent.list = node.insert_before(parent.list,head,hyphen_marker)
+
+
+ elseif head.id == GLUE then
+ local head_spec = head.spec
+ if not head_spec then
+ head_spec = head
+ end
+ local wd = head_spec.width
+ local color = "0.5 G"
+ if parent.glue_sign == 1 and parent.glue_order == head_spec.stretch_order then
+ wd = wd + parent.glue_set * head_spec.stretch
+ color = "0 0 1 RG"
+ elseif parent.glue_sign == 2 and parent.glue_order == head_spec.shrink_order then
+ wd = wd - parent.glue_set * head_spec.shrink
+ color = "1 0 1 RG"
+ end
+ local pdfstring = node.new("whatsit","pdf_literal")
+ local wd_bp = math.round(wd / number_sp_in_a_pdf_point,2)
+ if parent.id == HLIST then
+ pdfstring.data = string.format("q %s [0.2] 0 d 0.5 w 0 0 m %g 0 l s Q",color,wd_bp)
+ else -- vlist
+ pdfstring.data = string.format("q 0.1 G 0.1 w -0.5 0 m 0.5 0 l -0.5 %g m 0.5 %g l s [0.2] 0 d 0.5 w 0.25 0 m 0.25 %g l s Q",-wd_bp,-wd_bp,-wd_bp)
+ end
+ parent.list = node.insert_before(parent.list,head,pdfstring)
+
+
+ elseif head.id == KERN then
+ local rectangle = node.new("whatsit","pdf_literal")
+ local color = "1 1 0 rg"
+ if head.kern < 0 then color = "1 0 0 rg" end
+ local k = math.round(head.kern / number_sp_in_a_pdf_point,2)
+ if parent.id == HLIST then
+ rectangle.data = string.format("q %s 0 w 0 0 %g 1 re B Q",color, k )
+ else
+ rectangle.data = string.format("q %s 0 w 0 0 1 %g re B Q",color, -k )
+ end
+ parent.list = node.insert_before(parent.list,head,rectangle)
+
+
+ elseif head.id == PENALTY then
+ local color = "1 g"
+ local rectangle = node.new("whatsit","pdf_literal")
+ if head.penalty < 10000 then
+ color = string.format("%d g", 1 - math.floor(head.penalty / 10000))
+ end
+ rectangle.data = string.format("q %s 0 w 0 0 1 1 re B Q",color)
+ parent.list = node.insert_before(parent.list,head,rectangle)
+ end
+ head = head.next
+ end
+ return true
+end
diff --git a/macros/luatex/generic/lua-visual-debug/lua-visual-debug.sty b/macros/luatex/generic/lua-visual-debug/lua-visual-debug.sty
new file mode 100644
index 0000000000..9d5b22337a
--- /dev/null
+++ b/macros/luatex/generic/lua-visual-debug/lua-visual-debug.sty
@@ -0,0 +1,37 @@
+% see lua file for copyright information (MIT License)
+
+\def\lvdebugpkgdate{2019/01/07}
+\def\lvdebugpkgversion{0.7}
+
+\ifx\ProvidesPackage\undefined
+ \input ifluatex.sty\relax
+\else
+ \NeedsTeXFormat{LaTeX2e}
+ \ProvidesPackage{lua-visual-debug}[\lvdebugpkgdate\space v\lvdebugpkgversion\space Visual debugging in LuaLaTeX (PGU)]
+ \RequirePackage{ifluatex}
+\fi
+
+\def\luavisualdebug@dothings{%
+ \directlua{ lvd = require("lua-visual-debug")}%
+ \AtBeginShipout {\directlua{lvd.show_page_elements(tex.box["AtBeginShipoutBox"])}}%
+}
+
+\ifx\ProvidesPackage\undefined
+ \ifluatex
+ \input atbegshi.sty\relax
+ \luavisualdebug@dothings
+ \AtBeginShipoutInit
+ \else
+ \message{Warning: lua-visual-debug only works with LuaTeX (plain and LaTeX format)}
+ \fi
+\else
+ \ifluatex
+ \RequirePackage{atbegshi}
+ \luavisualdebug@dothings
+ \else
+ \PackageWarning{lua-visual-debug}{You are using this package without LuaTeX. This is not supported, so you don't get any visual debugging.}
+ \fi
+\fi
+
+
+