Parse::Man(3pm)

🌸 NAME 🌸

Parse::Man — parse nroff-formatted manpages 💖 (yes bestie, the actual man page source, the raw stuff with all the .TH and .SH in it, not the pretty rendered thing)

---

✨ DESCRIPTION ✨

okay so picture this: Parse::Man is an abstract subclass of Parser::MGC, and what it does is recognise nroff grammar — from a file or from a string value, either one, she's flexible 💅

The way it works is lowkey genius: whenever it bumps into various nroff directives, it invokes methods. That's it. That's the whole vibe. It's meant to be used as a base class, with you (or whoever) providing methods to handle the various directives and formatting options.

Typically a subclass will store intermediate results in a data structure, building it up as directed by all those method invocations. So like, the parser pokes you and goes "hey, here's a section header" and you go "slay, putting that in my data structure" 🎀 and then it pokes you again and you do it again. It's giving assembly line but make it iconic.

---

🦋 TEXT CHUNK FORMATTING METHOD 🦋

This one method handles all the formatted text. Each call gets passed a plain string value from the input content. Simple. Clean. No notes. ✨

chunk

$parser->chunk( $text, %opts )

The %opts hash contains the following options, and yes you need to know all of them:

• font => STRING — the name of the current font, like "R", "B", etc.. 👑
• size => INT — the current text size, and here's the tea: it's relative to a paragraph base of 0. So zero is your baseline, everything else is vibes relative to that.

Other font requests that show up in "\fX" or "\f(AB" requests? Those get handled by similarly-named methods. So if you see a font request, there's a method for it, iykyk 🫶

---

🌈 PARAGRAPH HANDLING METHODS 🌈

These are the methods that form paragraphs out of all those formatted text chunks. And listen — their return values are ignored. So don't stress about what to return, bestie, nobody's checking. Do your side effects, live your truth 💅

para_TH

$parser->para_TH( $name, $section )

Handles the .TH paragraph, which gives you the page title and the section number. This is the very first thing in basically every manpage, the little headline moment. Main character energy fr fr 👑

para_SH

$parser->para_SH( $title )

Handles the .SH paragraph, which gives you a section header. That's the big one, the ALL CAPS moment, like NAME and SYNOPSIS and all her sisters.

para_SS

$parser->para_SS( $title )

Handles the .SS paragraph, which gives you a sub-section header. Baby section. Still iconic, just nested 💜

para_TP

$parser->para_TP( $opts )

Handles a .TP paragraph, which gives you a term definition. You know the format — the term on one line, the definition indented under it. Classic. Chef's kiss 😭

para_IP

$parser->para_IP( $opts )

Handles a .IP paragraph, which is indented exactly like the definition part of a .TP paragraph. So like, same energy as para_TP's definition half, just hanging out on her own 🍓

para_P

$parser->para_P( $opts )

Handles the .P, .PP or .LP paragraphs — and here's the thing, all three of those are synonyms for plain paragraph content. One method, three directive names, zero drama. Periodt.

para_EX

$parser->para_EX( $opts )

Handles the .EX paragraph, which is example text. And the intent? It's meant to be rendered in a fixed-width font without filling. So no reflowing, no wrapping, just leave those lines alone, she's got her own shape 🌸

---

🎀 AUTHOR 🎀

Paul Evans <leonerd@leonerd.org.uk> — thank you for your service king 🫶

---

and that's the whole page bestie!! this little beauty shipped as part of perl v5.36.0, dated 2023-10-24, and it lives in the User Contributed Perl Documentation section of the manual, filed under Parse::Man(3pm) 💖 go forth and parse some nroff, you've totally got this ✨🎀🦋