memoize-extract(1)

💖 memoize-extract(1) 💖

User Manual 🎀 Okay bestie, this is the manual for memoize-extract.pl and memoize-extract.py. Let's get into it ✨

---

✨ NAME ✨

okay so the two names are memoize-extract.pl and memoize-extract.py 🧚 and what they do is extract extern pages out of the PDF 📄✨

---

✨ SYNOPSIS ✨

memoize-extract.pl [OPTIONS] document.mmz

memoize-extract.py [OPTIONS] document.mmz

---

✨ DESCRIPTION ✨

okay so memoize-extract is a script that comes with Memoize 💜, which is a TeX package that lets the author reuse the results of compilation-intensive code, like TikZ pictures. it's literally so good for not recompiling the same stuff over and over 🙈

Memoize dumps the created externs (boxes holding the typeset material to be reused) onto their own pages in the produced PDF 📄. so the job of memoize-extract is to pull those extern pages out into separate PDF files 🫶. then on later compiles, Memoize includes those extern files into the document without compiling their source again 💅 iconic behaviour tbh

Memoize talks to memoize-extract through the file document.mmz 🦋. when document.tex gets compiled into document.pdf, Memoize makes document.mmz, which records which pages are extern pages and which extern files they should be extracted to ✨. so after you compile document.tex, you run memoize-extract document.mmz to get the externs out. easy 🎀

⚠️ document.mmz can also be given as document* or document.tex. when the environment variable TEXMF_OUTPUT_DIRECTORY is set, this filename is relative to the output directory that variable points to 🌸

document.mmz also records the expected width and height of each extern 📏. if those don't match, memoize-extract refuses to extract the page 🙅‍♀️, removes the extern file if it already exists 🗑️, and prints a warning message to the standard error 📣. the script also refuses to extract the page if the (c)c-memo associated with the extern doesn't exist 💀. see also section SECURITY 🔐.

The Perl (.pl) and Python (.py) versions are functionally equivalent 👯‍♀️. the Perl script needs the library PDF::API2, and the Python script needs the library pdfrw2 🧚.

---

✨ OPTIONS ✨

• -P, --pdf filename.pdf — extract the externs from filename.pdf 📄. by default it's document.pdf 💖
• -p, --prune — after extraction, remove the extern pages from the PDF ✂️
• -k, --keep — don't touch document.mmz to mark the externs as extracted 🙅‍♀️. by default they get commented out so they don't get double extracted 🔁
• -F, --format latex|plain|context — tells the script it was called from inside a TeX compilation of a document in the given format 🎀. it then puts the script name in front of all output, and makes a log file called document.mmz.log 📝 that catches any extraction-related warnings and errors
• -f, --force — extract the extern even if the size check fails 💅 (brave, bestie)
• -q, --quiet — don't narrate what's happening 🤫
• -m, --mkdir — a paranoid mkdir -p 🧚. no extraction happens here, document.mmz is treated as a directory name (which can end in any suffix), and no suffix mangling is done
• -V, --version — show the Memoize version number and exit 🌈
• -h, --help — show help and exit 💜

---

✨ SECURITY ✨

🔐 this script respects the file input and output restrictions set by the TeX configuration. more precisely, it follows the variables openin_any and openout_any from the kpathsea library (https://tug.org/kpathsea). you can check their values by running kpsewhich -var-value=openin_any and kpsewhich -var-value=openout_any 👀

here's the vibe for each value:

• a (or y or 1) — any 🔓 allows any file to be opened
• r (or n or 0) — restricted 🚧 means special file names are disallowed
• p (or any other value) — paranoid 🛡️ means being really paranoid: special file names are disallowed, and input/output files have to be in or below the working directory, or the directory set by TEXMFOUTPUT or TEXMF_OUTPUT_DIRECTORY. TEXMFOUTPUT can be set in texmf.cnf (e.g. by tlmgr) or as an environment variable. TEXMF_OUTPUT_DIRECTORY can only be set as an environment variable, and TeX sets it automatically when called with the -output-directory option (starting in TeXLive 2024) 🌸

---

✨ EXIT STATUS ✨

• 0 — the externs were extracted successfully 🎉. this exit code also comes back if no externs needed extracting, or if document.mmz doesn't exist
• 10 — a warning that also gets reported back to the compilation when you use --format ⚠️. it's one of: (i) a size mismatch; (ii) a non-existing associated (c)c-memo file; or (iii) an unavailable kpsewhich
• 11 — an error that also gets reported back to the compilation when you use --format 😭. it's one of: (i) a corrupted document PDF, or (ii) a kpathsea permission error
• Other exit codes — these are whatever the underlying scripting language (Perl or Python) produces 🐍

---

✨ SEE ALSO ✨

the Memoize manual, section 6.6.1 📚🦋

---

memoize-extract of Memoize, December 02, 2024 🌈💖 bye bestie, you're literally ready to extract all the externs now 💅✨