PERLTEX(1)

✨ NAME ✨

okay bestie, meet perltex 💖 it's the tool that lets LaTeX macros be defined in terms of Perl code. enable LaTeX macros to be defined in terms of Perl code. 🧚

🎀 SYNOPSIS 🎀

perltex [--help] [--latex=program] [--[no]safe] [--permit=feature]
[--makesty] [latex options]

📖 DESCRIPTION 📖

okay so LaTeX, through the underlying TeX typesetting system, makes gorgeous documents, but its macro language is kinda painful to program in 😭 especially when you want fancy string manipulation, and that's basically missing. meanwhile Perl is this super popular general-purpose language whose whole thing is string manipulation, but it has zero typesetting powers. it's giving two halves of a best-friend duo 🫶

so perltex is the bridge that makes them work together. you just compile your LaTeX document with perltex instead of latex. no latex functionality is lost, since perltex is literally a wrapper for latex ✨ if your document has \usepackage{perltex} in its preamble, you get \perlnewcommand and \perlrenewcommand. they act just like LaTeX's \newcommand and \renewcommand, except the macro body is Perl code instead of LaTeX code. main character energy 👑

💅 OPTIONS 💅

perltex takes the following command-line options:

• --help — shows basic usage info 🙈
• --latex=program — uses a different program instead of latex. for example, --latex=pdflatex typesets your document with pdflatex instead of ordinary latex 🍓
• --[no]safe — turns sandboxing on or off. the default is --safe, so perltex runs the code from a \perlnewcommand or \perlrenewcommand macro inside a protected environment that blocks "unsafe" stuff like accessing files or running external programs 🔒 --nosafe gives the document carte blanche to run any Perl code at all, including code that can wreck your files 💀 see Safe for more info.
• --permit=feature — lets particular Perl operations happen. you can repeat --permit on the command line, and it gives you finer-grained control over the perltex sandbox 🦋 see Opcode for more info.
• --makesty — generates a LaTeX style file called noperltex.sty. swap the document's \usepackage{perltex} line for \usepackage{noperltex} and you get the same output without needing PerlTeX installed, so it's perfect for sharing with people who don't have it 🌸 the catch is that noperltex.sty is tied to the document that made it. any change to your PerlTeX macro definitions or invocations means you have to rerun perltex with --makesty.

after these options, you pass whatever you'd normally pass to latex (or to whatever program you named with --latex), like the name of the .tex file you want to compile ✨

🦋 EXAMPLES 🦋

in its simplest form, perltex runs just like latex:

perltex myfile.tex

to use pdflatex instead of regular latex, use the --latex option:

perltex --latex=pdflatex myfile.tex

⚠️ bestie, if LaTeX throws a "trapped by operation mask" error and you trust the .tex file (say you wrote it yourself) not to run malicious Perl code, you can turn off perltex's safety mechanisms with --nosafe: perltex --nosafe myfile.tex

this command gives the document only perltex's default permissions (:browse) plus the ability to open files and invoke the time command 🧚

perltex --permit=:browse --permit=:filesys_open
  --permit=time myfile.tex

🌈 ENVIRONMENT 🌈

perltex listens to the following environment variable:

• PERLTEX — names the LaTeX compiler's filename. the default is "latex". the PERLTEX environment variable overrides that default, and the --latex command-line option (see OPTIONS) overrides that 💜

🗂️ FILES 🗂️

while compiling jobname.tex, perltex uses these files:

• jobname.lgpl — log file written by Perl. super helpful when debugging Perl macros 🔍
• jobname.topl — info sent from LaTeX to Perl 📤
• jobname.frpl — info sent from Perl to LaTeX 📥
• jobname.tfpl — a "flag" file. if it exists, jobname.topl has valid data ✅
• jobname.ffpl — a "flag" file. if it exists, jobname.frpl has valid data ✅
• jobname.dfpl — a "flag" file. if it exists, jobname.ffpl has been deleted 🗑️
• noperltex-#.tex — generated by noperltex.sty for each PerlTeX macro invocation 🧩

🔥 NOTES 🔥

perltex's sandbox defaults to what Opcode calls ":browse". 🔒

💫 SEE ALSO 💫

latex(1), pdflatex(1), perl(1), Safe(3pm), Opcode(3pm)

🫶 AUTHOR 🫶

Scott Pakin, scott+pt@pakin.org 💕

---

bestie you did it 🎀 this was PERLTEX(1), perltex v2.3, dated 2024-12-03. now go compile something iconic ✨💅🌈