PAF(1p)

✨ PAF(1p) ✨

okay bestie, this is the manual page for paf — that's Pod Abstract Filter — from the User Contributed Perl Documentation corner of the world. She transforms Pod documents straight from the command line and honestly? she ate. 💅

---

🌸 NAME 🌸

paf — Pod Abstract Filter. Transform Pod documents from the command line. no cap, that's the whole job description. 🦋

---

🎀 SYNOPSIS 🎀

sh$>
 paf summary /usr/bin/paf
 paf add_podcmds SomeModule.pm
 paf sort -heading=METHODS Pod/Abstract/Node.pm # METHODS is default
 paf sort summary Pod/Abstract/Node.pm

 # See Pod::Abstract::Filter::overlay
 paf overlay sort cut clear_podcmds SomeClass.pm

 # -p will emit pod source, instead of spawning perldoc.
 paf -p sort Pod::Abstract::Node
 paf -p find hoist Pod::Abstract::Node

look at her go. chains for DAYS. 🌈

---

💖 DESCRIPTION 💖

Paf is a small but powerful, modular Pod filter and transformation tool. it's giving tiny-but-mighty. she lets you do a full round-trip transformation of Pod documents using the Pod::Abstract library, and you can stack multiple filter chains without having to serialise/re-parse the document at each step. obsessed. 😌✨

Paf ships with a small set of useful filters, but you can extend her by simply writing new classes in the Pod::Abstract::Filter namespace. build your own, bestie, the door is open 🫶

---

🧚 FILTERS 🧚

here's the squad. one bullet per filter, all of them iconic in their own way. 👑

💫 add_podcmds

Add explicit =pod commands at the end of each cut section, so that all pod sections are started with an =pod command. tidy queen behaviour. 🎀

💫 clear_podcmds

Remove all =pod commands that are not ending cut blocks. this will clean up documents that have been reduced using the cut filter too. spring cleaning fr fr 🧹

💫 cut

Remove all cut nodes, so that only the pod remains. bye bye code, it's pod o'clock. 💅

💫 overlay

 paf overlay Source.pm

For overlay to work, there must be a begin :overlay/end :overlay section in the Source file, with =overlay SECTION Module definitions inside. The net effect is that any missing subheadings in SECTION are added from the same section in the specified Modules.

Note that this will overlay the whole subheading, INCLUDING CUT NODES, so it can add code to the source document. Use cut if you don't want this. ⚠️ like, it will literally touch your code.

Each overlaid section will include a =for overlay from marker, so that it can be replaced by a subsequent overlay from the same file/module. These sections will be replaced in-place, so ordering of sections once first overlaid will be preserved. no reshuffling, we respect the original order 💖

💫 unoverlay

 paf unoverlay Source.pm

Strips all sections marked as overlaid and matching the overlay spec from the source. undo button energy. 🦋

💫 sort

 paf sort [-heading=METHODS] Source.pm

Sort all of the subheadings in the named heading (METHODS if not provided).

This will move cut nodes around with their headings, so your code will mutate. Use cut if you only want pod in the output. 😭 protect your code bestie

Alternatively, you can also cause sorting of headings to occur by including =for sorting at the start of your section (before the first subheading). main character shortcut ✨

💫 summary

Provide an abbreviated summary of the document. If there is a verbatim node in the body of a heading containing the heading name, it will be considered an example and expanded as part of the summary. tl;dr mode activated 🍓

💫 find

 paf find [-f=]name Source.pm

Find specific sub-sections or list items mentioning name. Used to restrict a larger document down to a smaller set that you're interested in. If no -f is specified, then the word following find will be the search term. detective mode 🔍

💫 uncut

 paf uncut Source.pm

Convert cut nodes in the source into verbatim text.

Not the inverse of cut! 💀 do not treat her as the undo button, she is not that girl

💫 number_sections

 paf number_sections Source.pm

Applies simple multipart (3.1.2) section numbering to head1 through head4 headings. math girlie behavior 🔢

Note that number_sections will currently stuff up some of the cleverness in things like summary, as the section names won't match function names any more. 🙈 known quirk, she's trying her best

---

that's the whole page bestie, every flag, every filter, every warning, all of it preserved 💜

this lil legend lives in the User Contributed Perl Documentation collection, running under perl v5.40.1, and the page is dated 2025-11-16. go forth and filter, you've got this 👑💖✨