1PAF(1) User Contributed Perl Documentation PAF(1)
2
6 paf -- Pod Abstract Filter
7
9 sh$>
10 paf summary /usr/bin/paf
11 paf add_podcmds SomeModule.pm
12 paf sort -heading=METHODS Pod/Abstract/Node.pm # METHODS is default
13 paf sort summary Pod/Abstract/Node.pm
14 # See Pod::Abstract::Filter::overlay
16 paf overlay sort cut clear_podcmds SomeClass.pm
17 # -p will emit pod source, instead of spawning perldoc.
19 paf -p sort Pod::Abstract::Node
20 paf -p find hoist Pod::Abstract::Node
21
23 Paf is a small but powerful, modular Pod filter and transformation
24 tool. It allows full round-trip transformation of Pod documents using
25 the Pod::Abstract library, with multiple filter chains without having
26 to serialise/re-parse the document at each step.
27 Paf comes with a small set of useful filters, but can be extended by
29 simply writing new classes in the "Pod::Abstract::Filter" namespace.
30
32 add_podcmds
33 Add explicit =pod commands at the end of each cut section, so that all
34 pod sections are started with an =pod command.
35 clear_podcmds
37 Remove all =pod commands that are not ending cut blocks. This will
38 clean up documents that have been reduced using the "cut" filter too.
39 cut
41 Remove all cut nodes, so that only the pod remains.
42 overlay
44 paf overlay Source.pm
45 For overlay to work, there must be a "begin :overlay/end :overlay"
47 section in the Source file, with "=overlay SECTION Module" definitions
48 inside. The net effect is that any missing subheadings in SECTION are
49 added from the same section in the specified Modules.
50 Note that this will overlay the whole subheading, INCLUDING CUT NODES,
52 so it can add code to the source document. Use "cut" if you don't want
53 this.
54 Each overlaid section will include a "=for overlay from" marker, so
56 that it can be replaced by a subsequent overlay from the same
57 file/module. These sections will be replaced in-place, so ordering of
58 sections once first overlaid will be preserved.
59 unoverlay
61 paf unoverlay Source.pm
62 Strips all sections marked as overlaid and matching the overlay spec
64 from the source.
65 sort
67 paf sort [-heading=METHODS] Source.pm
68 Sort all of the subheadings in the named heading (METHODS if not
70 provided).
71 This will move cut nodes around with their headings, so your code will
73 mutate. Use "cut" if you only want pod in the output.
74 Alternatively, you can also cause sorting of headings to occur by
76 including "=for sorting" at the start of your section (before the first
77 subheading).
78 summary
80 Provide an abbreviated summary of the document. If there is a verbatim
81 node in the body of a heading containing the heading name, it will be
82 considered an example and expanded as part of the summary.
83 find
85 paf find [-f=]name Source.pm
86 Find specific sub-sections or list items mentioning name. Used to
88 restrict a larger document down to a smaller set that you're interested
89 in. If no -f is specified, then the word following find will be the
90 search term.
91 uncut
93 paf uncut Source.pm
94 Convert cut nodes in the source into verbatim text. Not the inverse of
96 cut!
97 number_sections
99 paf number_sections Source.pm
100 Applies simple multipart (3.1.2) section numbering to head1 through
102 head4 headings.
103 Note that number_sections will currently stuff up some of the
105 cleverness in things like summary, as the section names won't match
106 function names any more.
107perl v5.12.0 2009-05-26 PAF(1)