paf (1p)

 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

Paf is a small but powerful, modular Pod filter and transformation tool. It allows full round-trip transformation of Pod documents using the Pod::Abstract library, with multiple filter chains without having to serialise/re-parse the document at each step.

Paf comes with a small set of useful filters, but can be extended by simply writing new classes in the \*(C`Pod::Abstract::Filter\*(C' namespace.

add_podcmds

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

clear_podcmds

Remove all =pod commands that are not ending cut blocks. This will clean up documents that have been reduced using the \*(C`cut\*(C' filter too.

cut

Remove all cut nodes, so that only the pod remains.

overlay

paf overlay Source.pm

For overlay to work, there must be a \*(C`begin :overlay/end :overlay\*(C' section in the Source file, with \*(C`=overlay SECTION Module\*(C' definitions inside. The net effect is that any missing subheadings in \s-1SECTION\s0 are added from the same section in the specified Modules.

Note that this will overlay the whole subheading, \s-1INCLUDING\s0 \s-1CUT\s0 \s-1NODES\s0, so it can add code to the source document. Use \*(C`cut\*(C' if you don't want this.

Each overlaid section will include a \*(C`=for overlay from\*(C' 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.

unoverlay

paf unoverlay Source.pm

Strips all sections marked as overlaid and matching the overlay spec from the source.

sort

paf sort [-heading=METHODS] Source.pm

Sort all of the subheadings in the named heading (\s-1METHODS\s0 if not provided).

This will move cut nodes around with their headings, so your code will mutate. Use \*(C`cut\*(C' if you only want pod in the output.

Alternatively, you can also cause sorting of headings to occur by including \*(C`=for sorting\*(C' at the start of your section (before the first subheading).

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.

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.

uncut

paf uncut Source.pm

Convert cut nodes in the source into verbatim text. Not the inverse of cut!

number_sections

paf number_sections Source.pm

Applies simple multipart (3.1.2) section numbering to head1 through head4 headings.

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.