%  -*- coding: utf-8 -*-
\documentclass[oneside,12pt]{article}
\usepackage[a4paper,margin=2cm]{geometry}

\newcommand*{\myversion}{2024C}
\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{tabularray}
\UseTblrLibrary{booktabs}
\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 Image-based regression testing for LaTeX packages}%
}
\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 \mypkg{ppmcheckpdf} files and
create a binary file \myfile{ppmcheckpdf} when you install this package.

If a manual installation is needed, you could copy \mypkg{ppmcheckpdf} files to TEXMF tree as follows:

\noindent\begin{tblr}{X[font=\ttfamily]X[2,font=\ttfamily]}
\toprule
  Package file    & Where to install it \\
\midrule
  ppmcheckpdf.1   & TEXMF/doc/man/man1/ppmcheckpdf.1 \\
  README.txt      & TEXMF/doc/support/ppmcheckpdf/README.txt \\
  ppmcheckpdf.lua & TEXMF/scripts/ppmcheckpdf/ppmcheckpdf.lua \\
\bottomrule
\end{tblr}

Then create a symbolic link from \myfile{/usr/local/bin/ppmcheckpdf} to \myfile{path/to/ppmcheckpdf.lua} on Linux or MacOS,
or create a batch file \myfile{ppmcheckpdf.bat} in binary folder of the TeX distribution with these lines on Windows:

\begin{codehigh}
@echo off
texlua path\to\ppmcheckpdf.lua %*
\end{codehigh}

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}

You could call \myopt{check} action of \mypkg{ppmcheckpdf} with the folllowing commands
\begin{codehigh}
l3build check
ppmcheckpdf check
\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 of failed tests to
\myfile{testfiles} folder by calling \myopt{save} option of it:
\begin{codehigh}
l3build check
ppmcheckpdf save
\end{codehigh}

Both \myopt{check} and \myopt{save} actions accept \myopt{-c} option, which sets the config to used.

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