1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
% -*- coding: utf-8 -*-
\documentclass[oneside,12pt]{article}
\usepackage[a4paper,margin=2cm]{geometry}
\newcommand*{\myversion}{2024B}
\newcommand*{\mydate}{Version \myversion\ (\the\year-\mylpad\month-\mylpad\day)}
\newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
\setlength{\parindent}{0pt}
\setlength{\parskip}{4pt plus 1pt minus 1pt}
\usepackage{codehigh}
\usepackage{hyperref}
\hypersetup{
colorlinks=true,
urlcolor=blue3,
linkcolor=green3,
}
\NewDocumentCommand\mypkg{m}{\textcolor{blue3}{\mbox{\ttfamily#1}}}
\NewDocumentCommand\myopt{m}{\textcolor{brown3}{\mbox{#1}}}
\NewDocumentCommand\mycmd{m}{\textcolor{green3}{\ttfamily\fakeverb{#1}}}
\NewDocumentCommand\myfile{m}{\textcolor{purple3}{\mbox{#1}}}
\NewDocumentCommand\myprg{m}{\textcolor{cyan3}{\mbox{#1}}}
\begin{document}
\title{\sffamily
\textcolor{green3}{The \texttt{ppmcheckpdf} tool}\\
{\large Convert PDF to PNG and compare PNG files after \texttt{l3build}}%
}
\author{%
Jianrui Lyu (tolvjr@163.com)%
%\\\url{https://github.com/lvjr/ppmcheckpdf}
}
\date{\mydate}
\maketitle
The \mypkg{l3build} system is a useful and powerful tool for regression testing.
With \mypkg{l3build} you normally print the contents of some boxes from \myfile{.lvt} files
to corresponding \myfile{.tlg} files. Sometimes \LaTeX{} kernel or some package your package
depends on adds a whatisit or \mycmd{\kern0pt}, and your test files will fail even if
the PDF files look the same as before and are still correct.
This \mypkg{ppmcheckpdf} tool provides an alternative way for regression testing:
Instead of printing box contents in \myfile{.lvt} files, you could just convert PDF files
to PNG files and compare PNG files after \mypkg{l3build} finishes its job.
\section{Installation}
Normally your TeX distribution will copy \myfile{ppmcheckpdf.lua} file to the correct folder
when you install this tool. If a manual installation is needed, you could download
\href{https://ctan.org/pkg/ppmcheckpdf}{\myfile{ppmcheckpdf.lua}}
from CTAN and install it to \myfile{TEXMF/scripts/ppmcheckpdf/ppmcheckpdf.lua}.
The \mypkg{ppmcheckpdf} tool uses \myprg{pdftoppm} program for image converting.
This program is installed by default on MiKTeX. For TeX Live, you can install it by running
\begin{codehigh}
tlmgr install wintools.windows
\end{codehigh}
on Windows, or running
\begin{codehigh}
sudo apt-get install poppler-utils
\end{codehigh}
on Ubuntu/Debian Linux.
\section{Usages}
First create a \myfile{buildend.lua} file with the following lines in the folder of your package
(next to \myfile{build.lua} file for \mypkg{l3build}):
\begin{codehigh}
kpse.set_program_name("kpsewhich")
dofile(kpse.lookup("ppmcheckpdf.lua"))
\end{codehigh}
Then you could run the folllowing commands
\begin{codehigh}
l3build check
texlua buildend.lua
\end{codehigh}
The first run of \mypkg{ppmcheckpdf} will save image and md5 files to \myfile{testfiles} folder,
and the subsequent runs of it will compare new md5 values with existing md5 values.
You could force \mypkg{ppmcheckpdf} to save new image and md5 files to \myfile{testfiles} folder
by passing \myopt{save} option to it:
\begin{codehigh}
l3build check
texlua buildend.lua save
\end{codehigh}
\section{Customizations}
The \myprg{pdftoppm} program supports several types of image files.
By default the \mypkg{ppmcheckpdf} tool will use \myfile{.png} file,
and you could change it in \myfile{build.lua} file like this:
\begin{codehigh}
imgext = ".ppm"
\end{codehigh}
\begin{codehigh}
imgext = ".pgm"
\end{codehigh}
\begin{codehigh}
imgext = ".pbm"
\end{codehigh}
\end{document}
|
