Pod::A...verlay(3pm)

💖 Pod::Abstract::Filter::overlay 💖

okay bestie, gather round, because this is the filter that does method documentation overlays on a Pod document. that's the whole vibe. the manual name is Pod::Abstract::Filter::overlay and it lives in the User Contributed Perl Documentation collection, iykyk 🎀

---

✨ USAGE ✨

so like, you run this filter inline through the paf command. for example:

$ paf -p overlay sort summary Pod::Abstract::Filter::overlay

and that produces:

 NAME
 METHODS
  \ =begin :overlay =overlay METHODS Some::Class::Or::File =end :overlay
   filter
   new
   param
   require_params
   run
 AUTHOR
 COPYRIGHT AND LICENSE

like. look at it. it ate. 🔥

---

🌸 METHODS 🌸

🦋 filter

okay so filter inspects the source document for a begin/end block named :overlay. then it peeks inside that overlay block for =overlay commands, which should be structured like this, no cap:

=begin :overlay

=overlay METHODS Some::Class::Or::File

=end :overlay

every single overlay gets processed in order. it adds any headings for the matched sections in the current document from the named source — but only for any heading that is not already present in the given section. it's giving "i'm not gonna overwrite what you already wrote, bestie" 💅

the main utility of this? specifying a superclass ✨ so that every method that is not documented in your subclass becomes documented by the overlay. so basically your subclass gets to inherit the docs without you doing the work. iconic. and the sort filter makes a really good follow up, fr fr.

the start of overlaid sections will include:

=for overlay from <class-or-file>

you can use these markers to set sections to be replaced by some other document, or to repeat an overlay on an already processed Pod file. and heads up: changes to existing marked sections are made in-place — without changing document order. so the order stays exactly where it was, periodt. 👑

---

👑 AUTHOR 👑

Ben Lilburne <bnej80@gmail.com>

---

💜 COPYRIGHT AND LICENSE 💜

Copyright (C) 2009-2025 Ben Lilburne

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 🫶 this was Pod::A...verlay(3pm), perl v5.40.1, dated 2025-11-16 — mwah 💋 go document something, you main character 🌈⭐