Debian Codegraph @

texmf-dist/doc/support/ppmcheckpdf/ppmcheckpdf.tex

raw
1 % -*- coding: utf-8 -*-
2 \documentclass[oneside,12pt]{article}
3 \usepackage[a4paper,margin=2cm]{geometry}
4
5 \newcommand*{\myversion}{2025A}
6 \newcommand*{\mydate}{Version \myversion\ (\the\year-\mylpad\month-\mylpad\day)}
7 \newcommand*{\mylpad}[1]{\ifnum#1<10 0\the#1\else\the#1\fi}
8
9 \setlength{\parindent}{0pt}
10 \setlength{\parskip}{4pt plus 1pt minus 1pt}
11
12 \usepackage{codehigh}
13 \usepackage{tabularray}
14 \UseTblrLibrary{booktabs}
15 \usepackage{hyperref}
16 \hypersetup{
17 colorlinks=true,
18 urlcolor=blue3,
19 linkcolor=green3,
20 }
21
22 \NewDocumentCommand\mypkg{m}{\textcolor{blue3}{\mbox{\ttfamily#1}}}
23 \NewDocumentCommand\myopt{m}{\textcolor{brown3}{\mbox{#1}}}
24 \NewDocumentCommand\mycmd{m}{\textcolor{green3}{\ttfamily\fakeverb{#1}}}
25 \NewDocumentCommand\myfile{m}{\textcolor{purple3}{\mbox{#1}}}
26 \NewDocumentCommand\myprg{m}{\textcolor{cyan3}{\mbox{#1}}}
27
28 \begin{document}
29
30 \title{\sffamily
31 \textcolor{green3}{The \texttt{ppmcheckpdf} tool}\\
32 {\large Image-based regression testing for LaTeX packages}%
33 }
34 \author{%
35 Jianrui Lyu ([email protected])%
36 %\\\url{https://github.com/lvjr/ppmcheckpdf}
37 }
38 \date{\mydate}
39 \maketitle
40
41 The \mypkg{l3build} system is a useful and powerful tool for regression testing.
42 With \mypkg{l3build} you normally print the contents of some boxes from \myfile{.lvt} files
43 to corresponding \myfile{.tlg} files. Sometimes \LaTeX{} kernel or some package your package
44 depends on adds a whatisit or \mycmd{\kern0pt}, and your test files will fail even if
45 the PDF files look the same as before and are still correct.
46
47 This \mypkg{ppmcheckpdf} tool provides an alternative way for regression testing:
48 Instead of printing box contents in \myfile{.lvt} files, you could just convert PDF files
49 to PNG files and compare PNG files after \mypkg{l3build} finishes its job.
50
51 \section{Installation}
52
53 Normally your TeX distribution will copy \mypkg{ppmcheckpdf} files and
54 create a binary file \myfile{ppmcheckpdf} when you install this package.
55
56 If a manual installation is needed, you could copy \mypkg{ppmcheckpdf} files to TEXMF tree as follows:
57
58 \noindent\begin{tblr}{X[font=\ttfamily]X[2,font=\ttfamily]}
59 \toprule
60 Package file & Where to install it \\
61 \midrule
62 ppmcheckpdf.1 & TEXMF/doc/man/man1/ppmcheckpdf.1 \\
63 README.txt & TEXMF/doc/support/ppmcheckpdf/README.txt \\
64 ppmcheckpdf.lua & TEXMF/scripts/ppmcheckpdf/ppmcheckpdf.lua \\
65 \bottomrule
66 \end{tblr}
67
68 Then create a symbolic link from \myfile{/usr/local/bin/ppmcheckpdf} to \myfile{path/to/ppmcheckpdf.lua} on Linux or MacOS,
69 or create a batch file \myfile{ppmcheckpdf.bat} in binary folder of the TeX distribution with these lines on Windows:
70
71 \begin{codehigh}
72 @echo off
73 texlua path\to\ppmcheckpdf.lua %*
74 \end{codehigh}
75
76 The \mypkg{ppmcheckpdf} tool uses \myprg{pdftoppm} program for image converting.
77 This program is installed by default on MiKTeX. For TeX Live, you can install it by running
78 \begin{codehigh}
79 tlmgr install wintools.windows
80 \end{codehigh}
81 on Windows, or running
82 \begin{codehigh}
83 sudo apt-get install poppler-utils
84 \end{codehigh}
85 on Ubuntu/Debian Linux.
86
87 \section{Usages}
88
89 You could call \myopt{check} action of \mypkg{ppmcheckpdf} with the folllowing commands
90 \begin{codehigh}
91 l3build check
92 ppmcheckpdf check
93 \end{codehigh}
94
95 The first run of \mypkg{ppmcheckpdf} will save image and md5 files to \myfile{testfiles} folder,
96 and the subsequent runs of it will compare new md5 values with existing md5 values.
97
98 You could force \mypkg{ppmcheckpdf} to save new image and md5 files of failed tests to
99 \myfile{testfiles} folder by calling \myopt{save} option of it:
100 \begin{codehigh}
101 l3build check
102 ppmcheckpdf save
103 \end{codehigh}
104
105 Both \myopt{check} and \myopt{save} actions accept \myopt{-c} option, which sets the config to used.
106
107 \section{Customizations}
108
109 The \myprg{pdftoppm} program supports several types of image files.
110 By default the \mypkg{ppmcheckpdf} tool will use \myfile{.png} file,
111 and you could change it in \myfile{build.lua} file like this:
112 \begin{codehigh}
113 imgext = ".ppm"
114 \end{codehigh}
115 \begin{codehigh}
116 imgext = ".pgm"
117 \end{codehigh}
118 \begin{codehigh}
119 imgext = ".pbm"
120 \end{codehigh}
121
122 \end{document}