TYPOG-GREP(1)

✨ NAME ✨

typog-grep 💖 is a specialized grep for typog-inspect elements in LaTeX log files. It's the tailored post-processor for the typoginspect environment from the LaTeX package typog. It's giving sgrep vibes, sharing more 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. 🦋

📜 SYNOPSIS 📜

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

okay so there are two forms here 🫶

The first form, "discovery mode", shows all IDs of:

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

elements in 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 no LOG-FILE is given, it reads from stdin. The filename - means stdin too, so it's basically the same thing 🌸

💅 DESCRIPTION 💅

bestie, here's the deal. In the LaTeX source file, you wrap your text or code in a typoginspect environment:

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

ID is what identifies one or more bracketed snippets. It does not have to be unique 🙈 The REGEXP mechanism makes it easy to grab groups of related IDs, as long as you name them accordingly. Main character naming energy ✨

In LOG-FILE, the result of the environment shows up packed with tracing information, like this:

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

All the capital-letter sequences are meta-variables. The important ones: JOB-NAME is the expansion of \jobname, LINE-NUMBER is the LaTeX source file line number where the typoginspect environment begins, and PAGE-NUMBER is the page where the output of TEXT-OR-CODE-TO-INVESTIGATE shows up 📄

typog-grep reveals the contents of LOG-FILE between <typog-inspect id="ID" ...> and </typog-inspect>, excluding the XML tags themselves. You can grab the JOB-NAME, LINE-NUMBER, and PAGE-NUMBER with the commandline options --job-name, --line-number, and --page-number, respectively. Use --id to show the name of the IDs that matched REGEXP 🎀

typoginspect environments can be nested, and typog-grep respects that nesting. So if the ID of a nested environment doesn't match REGEXP, it won't show up in the program's output. no cap, that's iconic 👑

🎀 OPTIONS 🎀

The list of options is sorted by the names of the long options, so it's super easy to find what you want 🍓

• -a, --all, --any — ID-discovery mode! It finds every typog-inspect element no matter what patterns are around and prints their IDs. The results come out in the order they appear in each LOG-FILE. If you want alphabetical IDs, pipe the output into sort 🧚

Level it up with --job-name, --line-number, --log-line-number, or --page-number for more info.

• --color, colour WHEN — colorizes the specific log contents for matching IDs. WHEN decides when to color: always, never, or auto. The auto setting checks whether standard output has been redirected. This is the default 🌈
• -C, --config KEY=VALUE[:KEY=VALUE[:...]] — sets one or more configuration KEY to VALUE pairs. Check out section CONFIGURATION for all the available configuration items. Use --show-config to see the default configuration 💜
• --debug — turns on debug output on stderr 🔥
• -E, --encoding ENCODING — sets the ENCODING of LOG-FILE for translation to UTF-8. The default is unset.

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

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

• -h, --help — shows brief help, then exits 🫶
• -i, --[no-]id — prints the actual ID-name that matched REGEXP. You can control how the matching ID looks with the configuration item id-heading 🌸
• -y, --[no-]ignore-case — matches IDs while ignoring case distinctions in patterns and data 🦋
• -j, --[no-]job-name — prints the \jobname that latex associated with the input file 💅
• -n, --[no-]line-number — prints the line number where the typoginspect environment was found in the LaTeX source file 🍓
• -N, --[no-]log-line-number — prints the line number of the log file where the current line was found 📜
• -p, --[no-]page-number — prints the page number where the contents of the typoginspect environment starts in the typeset document 📄
• -P, --[no-]pager — redirects output from stdout to the configured pager 👑
• --show-config — shows the default configuration, then exits ✨
• --show-encodings — shows all known encodings, then exits 🌈
• -V, --version — shows version info, then exits 🧚
• -w, --[no-]word-regexp — matches only whole words 💖

⚙️ CONFIGURATION ⚙️

Here's how the config items slay:

• "id-format"=FORMAT — controls the FORMAT for printing matching IDs in inline mode. FORMAT gets passed to Perl's printf. Default: %s:.
• "id-heading"=0|1 — picks between printing the matching IDs with --id as inline (0) or as a heading before the matching data (1). Default: 0.
• "id-heading-format"=FORMAT — controls the FORMAT for printing matching IDs in heading mode. FORMAT gets passed to Perl's printf. Default: "--> %s <--".
• "id-indent"=INDENT — the indentation of nested typog-inspect tags. This only applies in "discovery mode" (the first form), so when --all is active. Default: 8.
• "id-max-length"=MAXIMUM-LENGTH — sets the maximum length of a matching ID for printing. If a matching ID goes over 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. FORMAT gets passed to Perl's printf. Default: %5d.
• "log-line-number-format"=FORMAT — controls the FORMAT for printing log line numbers. FORMAT gets passed to Perl's printf. Default: %6d.
• "page-number-format"=FORMAT — controls the FORMAT for printing page numbers. FORMAT gets passed to Perl's printf. Default: "[%3d]".
• "pager"=PAGER — the name of the pager app to pipe output into when you run with --pager. Default: "less".
• "pager-flags"=FLAGS — passes FLAGS to PAGER. Default: "--quit-if-one-screen".

🎨 Color Configuration

For the syntax of the color specs, check 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 in 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

These encodings are suitable for --encoding, so pick your fighter 💅

• 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 🚦

The exit status is 0 if at least one ID matched REGEXP, 1 if no ID matched REGEXP, and 2 if an error occurred.

⚠️ 2 means something went wrong, so don't ignore it, bestie 😭

🙈 CAVEATS 🙈

The end tag </typog-inspect> sometimes gets placed too early in the output, so the trace looks truncated. Lowkey annoying, but LaTeX reliably logs the requested trace information. The write operations for trace data and the code that prints the end tag just aren't synchronized 💀

🔗 SEE ALSO 🔗

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

---

That's all, bestie! 🌈 typog-grep v0.4, dated 2024/07/08, is a whole vibe 💖🧚