diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /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.md | 1 | ||||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/README.md | 37 | ||||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.pdf | bin | 0 -> 209760 bytes | |||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.tex | 70 | ||||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/lvdebugdetail1-num.png | bin | 0 -> 73328 bytes | |||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/sample-plain.pdf | bin | 0 -> 49093 bytes | |||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/sample-plain.tex | 16 | ||||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/sample.pdf | bin | 0 -> 45257 bytes | |||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/sample.tex | 32 | ||||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/doc/strut.png | bin | 0 -> 11445 bytes | |||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/lua-visual-debug.lua | 160 | ||||
-rw-r--r-- | macros/luatex/generic/lua-visual-debug/lua-visual-debug.sty | 37 |
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 Binary files differnew file mode 100644 index 0000000000..71b2936a29 --- /dev/null +++ b/macros/luatex/generic/lua-visual-debug/doc/lvdebug-doc.pdf 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 Binary files differnew file mode 100644 index 0000000000..4c5fa553f8 --- /dev/null +++ b/macros/luatex/generic/lua-visual-debug/doc/lvdebugdetail1-num.png diff --git a/macros/luatex/generic/lua-visual-debug/doc/sample-plain.pdf b/macros/luatex/generic/lua-visual-debug/doc/sample-plain.pdf Binary files differnew file mode 100644 index 0000000000..2aaafad75f --- /dev/null +++ b/macros/luatex/generic/lua-visual-debug/doc/sample-plain.pdf 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 Binary files differnew file mode 100644 index 0000000000..81cf4fc223 --- /dev/null +++ b/macros/luatex/generic/lua-visual-debug/doc/sample.pdf 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 Binary files differnew file mode 100644 index 0000000000..c7cd0176af --- /dev/null +++ b/macros/luatex/generic/lua-visual-debug/doc/strut.png 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 + + + |