PAF(1)

💖 PAF(1) — like, the whole vibe 💖

okay bestie, pull up a chair, because this is PAF(1) from the User Contributed Perl Documentation and honestly? it's a little icon. 🎀

---

✨ NAME ✨

paf — Pod Abstract Filter. It transforms Pod documents from the command line. That's it, that's the girl. 💅

---

🌸 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

---

🦋 DESCRIPTION 🦋

so paf is small but powerful, and it's modular — a Pod filter and transformation tool, no cap. 💖

the way it does full round-trip transformation of Pod documents using the Pod::Abstract library?? and you can chain multiple filters together without having to serialise/re-parse the document at each step. not her being efficient. 👑

she ships with a small set of useful filters, but here's the slay: you can extend her by simply writing new classes in the Pod::Abstract::Filter namespace. build-a-bear but for Perl modules. 🧚

---

👑 FILTERS 👑

🌈 add_podcmds

Adds explicit =pod commands at the end of each cut section, so that literally all pod sections are started with an =pod command. tidy. ✨

🍓 clear_podcmds

Removes every =pod command that is not ending cut blocks. This will clean up documents that have been reduced using the cut filter too. spring cleaning energy. 🧹

💀 cut

Removes all cut nodes, so that only the pod remains. pod only, no code crumbs. ✂️

💜 overlay

paf overlay Source.pm

for overlay to actually work, bestie, there must be a begin :overlay/end :overlay section in the Source file, with =overlay SECTION Module definitions inside. 🫶

the net effect? any missing subheadings in SECTION get added from the same section in the specified Modules. she's filling in the blanks, respectfully.

⚠️ note that this will overlay the whole subheading, INCLUDING CUT NODES, so it can add code to the source document. if you don't want that, use cut. 😭

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 get replaced in-place, so the ordering of sections once first overlaid will be preserved. we love a stable order. 💅

🌸 unoverlay

paf unoverlay Source.pm

strips all sections marked as overlaid and matching the overlay spec from the source. bye bye overlay, we hardly knew ye. 👋

⭐ sort

paf sort [-heading=METHODS] Source.pm

sorts 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. if you only want pod in the output, use cut. fr fr, watch out.

alternatively — plot twist — you can also cause sorting of headings to occur by including =for sorting at the start of your section (before the first subheading). iykyk. ✨

🎀 summary

provides an abbreviated summary of the document. and if there's 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. she's thorough like that. 💖

🔥 find

paf find [-f=]name Source.pm

finds 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. main character search behaviour, honestly. 🔍

🫶 uncut

paf uncut Source.pm

converts cut nodes in the source into verbatim text.

💀 and no, it is NOT the inverse of cut! she said what she said.

🌈 number_sections

paf number_sections Source.pm

applies simple multipart (3.1.2) section numbering to head1 through head4 headings. so organized. so demure. ⭐

🙈 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. it's giving "known quirk", we still love her.

---

and that's the whole page, bestie!! this was perl v5.42.0, dated 2026-01-17, and honestly she ate. periodt. 💅✨🎀🦋