1PAF(1)                User Contributed Perl Documentation               PAF(1)
2
3
4

NAME

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

SYNOPSIS

10        sh$>
11         paf summary /usr/bin/paf
12         paf add_podcmds SomeModule.pm
13         paf sort -heading=METHODS Pod/Abstract/Node.pm # METHODS is default
14         paf sort summary Pod/Abstract/Node.pm
15
16         # See Pod::Abstract::Filter::overlay
17         paf overlay sort cut clear_podcmds SomeClass.pm
18
19         # -p will emit pod source, instead of spawning perldoc.
20         paf -p sort Pod::Abstract::Node
21         paf -p find hoist Pod::Abstract::Node
22

DESCRIPTION

24       Paf is a small but powerful, modular Pod filter and transformation
25       tool. It allows full round-trip transformation of Pod documents using
26       the Pod::Abstract library, with multiple filter chains without having
27       to serialise/re-parse the document at each step.
28
29       Paf comes with a small set of useful filters, but can be extended by
30       simply writing new classes in the "Pod::Abstract::Filter" namespace.
31

FILTERS

33   add_podcmds
34       Add explicit =pod commands at the end of each cut section, so that all
35       pod sections are started with an =pod command.
36
37   clear_podcmds
38       Remove all =pod commands that are not ending cut blocks. This will
39       clean up documents that have been reduced using the "cut" filter too.
40
41   cut
42       Remove all cut nodes, so that only the pod remains.
43
44   overlay
45        paf overlay Source.pm
46
47       For overlay to work, there must be a "begin :overlay/end :overlay"
48       section in the Source file, with "=overlay SECTION Module" definitions
49       inside. The net effect is that any missing subheadings in SECTION are
50       added from the same section in the specified Modules.
51
52       Note that this will overlay the whole subheading, INCLUDING CUT NODES,
53       so it can add code to the source document. Use "cut" if you don't want
54       this.
55
56       Each overlaid section will include a "=for overlay from" marker, so
57       that it can be replaced by a subsequent overlay from the same
58       file/module. These sections will be replaced in-place, so ordering of
59       sections once first overlaid will be preserved.
60
61   unoverlay
62        paf unoverlay Source.pm
63
64       Strips all sections marked as overlaid and matching the overlay spec
65       from the source.
66
67   sort
68        paf sort [-heading=METHODS] Source.pm
69
70       Sort all of the subheadings in the named heading (METHODS if not
71       provided).
72
73       This will move cut nodes around with their headings, so your code will
74       mutate. Use "cut" if you only want pod in the output.
75
76       Alternatively, you can also cause sorting of headings to occur by
77       including "=for sorting" at the start of your section (before the first
78       subheading).
79
80   summary
81       Provide an abbreviated summary of the document. If there is a verbatim
82       node in the body of a heading containing the heading name, it will be
83       considered an example and expanded as part of the summary.
84
85   find
86        paf find [-f=]name Source.pm
87
88       Find specific sub-sections or list items mentioning name. Used to
89       restrict a larger document down to a smaller set that you're interested
90       in. If no -f is specified, then the word following find will be the
91       search term.
92
93   uncut
94        paf uncut Source.pm
95
96       Convert cut nodes in the source into verbatim text. Not the inverse of
97       cut!
98
99   number_sections
100        paf number_sections Source.pm
101
102       Applies simple multipart (3.1.2) section numbering to head1 through
103       head4 headings.
104
105       Note that number_sections will currently stuff up some of the
106       cleverness in things like summary, as the section names won't match
107       function names any more.
108
109
110
111perl v5.38.0                      2023-07-21                            PAF(1)
Impressum