TYPOG-GREP(1)

📦 version 2026.0, in alpine 3.24

💅 TYPOG-GREP(1) — like grep but make it LaTeX-log couture 🎀

okay so bestie, welcome to typog-grep, part of the User Contributed Perl Documentation family ✨ It's a specialized grep for typog-inspect elements in LaTeX log files, and honestly? it ate. Let me walk you through it 🫶

✨ NAME ✨

typog-grep — a specialized grep for typog-inspect elements in LaTeX log files. yeah. that's the whole job. and it does it gorgeously 💅

🌸 SYNOPSIS 🌸

typog-grep -a|--all|--any [OPTION...] LOG-FILE...
typog-grep [OPTION...] REGEXP LOG-FILE...

The first form, which we're calling "discovery mode" (iconic name, no notes), shows all the IDs of

<typog-inspect id="ID" ...>

elements sitting inside LOG-FILE 👑

The second form shows the contents, LOG-DATA, of the elements

<typog-inspect id="ID" ...>
LOG-DATA
</typog-inspect>

whose IDs match REGEXP in LOG-FILE 🔥

If you don't hand it a LOG-FILE at all, it just reads from stdin, nbd. And the filename - is literally synonymous with stdin, so use whichever feels more main-character 🦋

💖 DESCRIPTION 💖

typog-grep is a tailored post-processor for LaTeX log files and the typoginspect environment that the LaTeX package typog provides 🌈 Lowkey it has way more in common with the venerable sgrep (https://www.cs.helsinki.fi/u/jjaakkol/sgrep.html) than with POSIX grep (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/grep.html). different species entirely, fr fr.

So in your LaTeX source file, the user brackets her text or code in a typoginspect environment, like this:

\begin{typoginspect}{ID}
TEXT-OR-CODE-TO-INVESTIGATE
\end{typoginspect}

where ID identifies one or more bracketed snippets. And no, ID does not have to be unique — it can absolutely serve multiple looks 💅 The REGEXP mechanism makes it super easy to select groups of related IDs, as long as you named them accordingly. plan ahead bestie, it's giving strategy.

In the log file, the result of the environment shows up — packed with tracing information — as:

<typog-inspect id="ID" job="JOB-NAME" line="LINE-NUMBER" page="PAGE-NUMBER">
LOG-DATA
</typog-inspect>

where all those capital-letter sequences are meta-variables 🌟 and in particular:

  • JOB-NAME is the expansion of \jobname
  • LINE-NUMBER is the LaTeX source file line number of the beginning of the typoginspect environment
  • PAGE-NUMBER is the page where the output of TEXT-OR-CODE-TO-INVESTIGATE occurs

typog-grep reveals the contents of LOG-FILE between <typog-inspect id="ID" ...> and </typog-inspect>, and it excludes the XML-tags themselves — we're not showing you the scaffolding, we're showing you the content 🎀

To get at the JOB-NAME, LINE-NUMBER, and PAGE-NUMBER, hit up the commandline options --job-name, --line-number, and --page-number. And use --id to show the name of the IDs that matched REGEXP 👑

Real talk: typoginspect environments can be nested, and typog-grep respects the nesting. So if the ID of the nested environment doesn't match REGEXP, it will not be included in the program's output. boundaries, bestie. we respect them 😌

🦋 OPTIONS 🦋

Just so you know, this list is sorted by the names of the long options ✨ (alphabetical queens only)

  • -a, --all, --any — ID-discovery mode 💫 Discover all typog-inspect elements, independent of any matching patterns, and print their IDs. Results come out in their order of occurrence in the *LOG-FILE*s. Want them alphabetically ordered? Pipe the output into sort, easy. You can also augment with the options --job-name, --line-number, --log-line-number, or --page-number for more information 👑
  • --color, --colour WHEN — Colorize specific log contents for the matching IDs 🌈 The WHEN argument decides when to apply color: always, never, or auto. The auto setting checks whether standard output has been redirected — and heads up, auto is the default 👀
  • -C, --config KEY=VALUE[:KEY=VALUE[:...]] — Set one or more configuration KEY to VALUE pairs 🎀 Peep the CONFIGURATION section for a description of all the available configuration items, and use --show-config to display the default configuration.
  • --debug — Turn on debug output on stderr 🐛 (she's chatty)
  • -E, --encoding ENCODING — Set the ENCODING of LOG-FILE for the translation to UTF-8 🌸 The default is unset.

Use this option to get rid of those pesky <HEX-DIGITS> escapes on UTF-8 terminals 😭 See --show-encodings for the known encodings, and Encode::Supported for a summary of all encodings. Also check out the Some Common Encodings section.

Alternatively, apply iconv (POSIX) (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/iconv.html) or recode (GNU) (https://github.com/rrthomas/recode/) on LOG-FILE before this tool, so you don't have to use --encoding at all 💅

  • -h, --help — Display brief help, then exit 🫶
  • -i, --[no-]id — Print the actual ID-name that matched REGEXP ⭐ Control how the matching ID appears with the configuration item id-heading.
  • -y, --[no-]ignore-case — Match IDs while ignoring case distinctions in patterns and data 🙈
  • -j, --[no-]job-name — Print the \jobname that latex associated with the input file 👑
  • -n, --[no-]line-number — Print the line number where the typoginspect environment was encountered in the LaTeX source file 📍
  • -N, --[no-]log-line-number — Print the line number of the log-file where the current line was encountered 📜
  • -p, --[no-]page-number — Print page number where the contents of the typoginspect environment starts in the typeset document 📖
  • -P, --[no-]pager — Redirect output from stdout to the configured pager 💜
  • --show-config — Show the default configuration and exit ✨
  • --show-encodings — Show all known encodings and exit 🌍
  • -V, --version — Show version information and exit 🎀
  • -w, --[no-]word-regexp — Match only whole words 🧚

🌈 CONFIGURATION 🌈

  • id-format=FORMAT — Controls the FORMAT for printing matching ids in inline-mode, where FORMAT is passed to Perl's printf. Default: %s: 💅
  • id-heading=0|1 — Chooses between printing the matching IDs with option --id: Inline (0) or heading before the matching data (1). Default: 0 🎀
  • id-heading-format=FORMAT — Controls the FORMAT for printing matching IDs in heading-mode, where FORMAT is passed to Perl's printf. Default: --> %s <-- 👑
  • id-indent=INDENT — Indentation of nested typog-inspect tags. Only used in "discovery mode" (the first form), i.e. if --all is active. Default: 8 🦋
  • id-max-length=MAXIMUM-LENGTH — Sets the maximum length of a matching ID for printing. If a matching ID exceeds this length, it gets truncated and the last three characters (short of MAXIMUM-LENGTH) get replaced by dots. Default: 40 ✂️
  • line-number-format=FORMAT — Controls the FORMAT for printing TeX source line numbers, where FORMAT is passed to Perl's printf. Default: %5d 📍
  • log-line-number-format=FORMAT — Controls the FORMAT for printing log line numbers, where FORMAT is passed to Perl's printf. Default: %6d 📜
  • page-number-format=FORMAT — Controls the FORMAT for printing page numbers, where FORMAT is passed to Perl's printf. Default: [%3d] 📖
  • pager=PAGER — Name of the pager application to pipe output into, if run with option --pager. Default: less 💜
  • pager-flags=FLAGS — Pass FLAGS to PAGER. Default: --quit-if-one-screen 🌸

🎨 Color Configuration 🎨

For the syntax of the color specifications, consult the manual page of Term::ANSIColor(pm) ✨

  • file-header-color — Color of the filename header 🏷️
  • fill-state-color — Color of the messages that report "Underfull hbox" or "Overfull hbox" 💀
  • first-vbox-color — Color of the first vbox on a page 📦
  • font-spec-color — Color of font specifications 🔤
  • horizontal-break-candidate-color — Color of lines with horizontal-breakpoint candidates @ 📐
  • horizontal-breakpoint-color — Color of lines with horizontal breakpoints @@ 📏
  • id-color — Color of matching IDs when printed inline 💖
  • id-heading-color — Color of matching IDs when printed in heading form 👑
  • line-break-pass-color — Color of the lines showing which pass (e.g., @firstpass) of the line-breaking algorithm is active 🌀
  • line-number-color — Color of TeX-source-file line numbers 📍
  • log-line-number-color — Color of log-file line numbers 📜
  • math-color — Color used for math expressions, including their font specs ➗
  • page-number-color — Color of page numbers of the final output 📖
  • tightness-color — Color of lines with Tight/Loose hbox reports 🎯
  • vertical-breakpoint-color — Color of possible vertical breakpoints 📊

🌟 Brief summary of colors and attributes 🌟

Foreground Color black, red, green, yellow, blue, magenta, cyan, white

Prefix with bright_ for high-intensity or bold foreground ⚡

Foreground Grey grey0, ..., grey23 🌫️

Background Color on_black, on_red, on_green, on_yellow, on_blue, on_magenta, on_cyan, on_white

Replace on_ with on_bright_ for high-intensity or bold background ⚡

Background Grey on_grey0, ..., on_grey23 🌫️

Text Attribute bold, dark, italic, underline, reverse ✨

🌍 Some Common Encodings 🌍

Here's a list of encodings that are suitable for option --encoding 🫶

  • Latin-1, Western European — iso-8859-1, cp850, cp860, cp1252
  • Latin-2, Central European — iso-8859-2, cp852, cp1250
  • Latin-3, South European (Esperanto, Maltese) — iso-8859-3
  • Latin-4, North European (Baltics) — iso-8859-4
  • Cyrillics — iso-8859-5, cp855, cp866 (Ukrainian), cp1251
  • Arabic — iso-8859-6, cp864, cp1006 (Farsi), cp1256
  • Greek — iso-8859-7, cp737, cp1253
  • Hebrew — iso-8859-8, cp862, cp1255
  • Turkish — iso-8859-9, cp857, cp1254
  • Nordic — iso-8859-10, cp865, cp861 (Icelandic)
  • Thai — iso-8859-11, cp874
  • Baltic — iso-8859-13, cp775, cp1257
  • Celtic — iso-8859-14
  • Latin-9 (sometimes called Latin0) — iso-8859-15
  • Latin-10 — iso-8859-16

⭐ EXIT STATUS ⭐

  • 0 — at least one ID matched REGEXP 🎉 slay
  • 1 — no ID matched REGEXP 😭
  • 2 — an error occurred 💀

⚠️ CAVEATS ⚠️

So here's the tea: the end tag </typog-inspect> sometimes gets placed too early in the output, and the trace seems truncated 🙈 But don't panic — LaTeX reliably logs the requested trace information. The real issue is that the write operations for trace data and the code used to print the end tag are not synchronized. it's giving race condition, but make it LaTeX 💅

🫶 SEE ALSO 🫶

grep(1), printf(3), Encode::Supported(pm), Term::ANSIColor(pm)

and that's the whole page bestie, you're literally a typog-grep expert now 👑✨

this iconic little number is version 0.5, dated 2025/10/27, and it lives under User Contributed Perl Documentation — go forth and grep your logs, queen 🎀💖

📦 where this page comes from