Provided by: libpod-abstract-perl_0.20-2_all bug


       paf - Pod Abstract Filter. Transform Pod documents from the command line.


         paf summary /usr/bin/paf
         paf add_podcmds
         paf sort -heading=METHODS Pod/Abstract/ # METHODS is default
         paf sort summary Pod/Abstract/

         # See Pod::Abstract::Filter::overlay
         paf overlay sort cut clear_podcmds

         # -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 "Pod::Abstract::Filter" namespace.


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

       Remove all =pod commands that are not ending cut blocks. This will clean up documents that
       have been reduced using the "cut" filter too.

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

        paf overlay

       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.

       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.

        paf unoverlay

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

        paf sort [-heading=METHODS]

       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.

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

       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.

        paf find [-f=]name

       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.

        paf uncut

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

        paf number_sections

       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.