Bug#1141224: pdfjam should complain about a wrong command-line option immediately

Package: texlive-extra-utils
Version: 2024.20250309-2


Take a PDF file on your system, say, /usr/share/doc/debian-reference-de/docs/debian-reference.de.pdf, and issue

pdfjam --landscape --nup 2x1 --output 2-on-1.pdf /usr/share/doc/debian-reference-de/docs/debian-reference.de.pdf

Observe this printout:

           ----
   pdfjam: This is pdfjam version 4.1.
   pdfjam: Reading any site-wide or user-specific defaults...
           (none found)
   pdfjam: Effective call for this run of pdfjam:
           /usr/bin/pdfjam --landscape --nup 2x1 --output 2-on-1.pdf -- /usr/share/doc/debian-reference-de/docs/debian-reference.de.pdf -
   pdfjam: Calling /usr/bin/pdflatex...
   pdfjam: FAILED.
           The call to /usr/bin/pdflatex resulted in an error.
           Rerun with '--no-tidy' or '--builddir PATH' to diagnose the problem.
   pdfjam ERROR: Run 1: Output file not written

Alright, I thought, let's go with --no-tidy:

$ pdfjam --landscape --nup 2x1 --output 2-on-1.pdf --no-tidy /usr/share/doc/debian-reference-de/docs/debian-reference.de.pdf
           ----
   pdfjam: This is pdfjam version 4.1.
   pdfjam: Reading any site-wide or user-specific defaults...
           (none found)
   pdfjam: Temporary directory for this job is
                   /tmp/pdfjam-uZGvhO
   pdfjam: Effective call for this run of pdfjam:
           /usr/bin/pdfjam --landscape --nup 2x1 --output 2-on-1.pdf --no-tidy -- /usr/share/doc/debian-reference-de/docs/debian-reference.de.pdf -
   pdfjam: Calling /usr/bin/pdflatex...
   pdfjam: FAILED.
           The call to /usr/bin/pdflatex resulted in an error.
           You can examine the build directory at
                   /tmp/pdfjam-uZGvhO
           to try to diagnose the problem.
   pdfjam ERROR: Run 1: Output file not written

So let's peek into the directory:
$ ls /tmp/pdfjam-uZGvhO
a.aux  a.log  a.msgs  a.pdf  a.tex  call.txt  debian-reference.de.pdf  messages.txt
$ tail /tmp/pdfjam-uZGvhO/a.log
  72i,17n,79p,253b,434s stack positions out of 10000i,1000n,20000p,200000b,200000s
</usr/share/texlive/texmf-dist/fonts/type1/public/amsfonts/cm/cmmi9.pfb></usr
/share/texlive/texmf-dist/fonts/type1/public/amsfonts/cm/cmsy9.pfb>
Output written on a.pdf (149 pages, 1304534 bytes).
PDF statistics:
  915 PDF objects out of 1000 (max. 8388607)
  366 compressed objects within 4 object streams
  0 named destinations out of 1000 (max. 500000)
  1496 words of extra memory for PDF output out of 10000 (max. 10000000)

This looks good so far, and /tmp/pdfjam-uZGvhO/a.pdf indeed contains a 2-on-1 version. So the call to pdflatex didn't result in an error, did it?

Now I thought to myself: How to debug it next?

It took me a night and a day and more tests from here to understand that the command line option “--output” was the culprit: it should read “--outfile”.

In retrospect,

$ egrep -i "error|warn|fail|miss|unknown|not found" /tmp/pdfjam-uZGvhO/a.log
/tmp/pdfjam-uZGvhO/a.log:! Package keyval Error: output undefined.

would have helped, but yesterday it didn't occur to me to run this command.

My kind request would be that the pdfjam command-line options are parsed and complained about immediately so that the user wouldn't need LaTeX knowledge (here: search a.log for complaints and understand what “keyval” actually does) if the only thing the user needs is to convert a PDF file 2 on 1.