1Pod::Tidy(3) User Contributed Perl Documentation Pod::Tidy(3)
2
6 Pod::Tidy - a reformatting Pod Processor
7
9 use Pod::Tidy qw( tidy_files tidy_filehandle );
10 my $processed = Pod::Tidy::tidy_files(
12 files => \@list,
13 ignore => [qr/foo/, qr/bar/],
14 recursive => $recursive,
15 verbose => $verbose,
16 inplace => $inplace,
17 nobackup => $nobackup,
18 columns => $columns,
19 );
20 Pod::Tidy::tidy_filehandle($input);
22
24 This module provides the heavy lifting needed by the "podtidy" utility
25 although the API should be general enough that it can be used directly.
26
28 Import Parameters
29 This module accepts no arguments to it's "import" method and exports no
30 symbols.
31 Exportable Subroutines
33 • tidy_files( ... )
34 Accepts a mandatory hash.
36 my $processed = Pod::Tidy::tidy_files(
38 files => \@list,
39 ignore => [qr/foo/, qr/bar/],
40 recursive => $recursive,
41 verbose => $verbose,
42 inplace => $inplace,
43 nobackup => $nobackup,
44 columns => $columns,
45 );
46 • files
48 An array ref to a list of files and/or directories.
50 • ignore
52 An array ref to regex objects that are used to reject files
54 and/or directories. Each pattern is tried for a match against
55 (in order) the absolute file path, the relative file path
56 (canonical), and the basename. In the case of directories, the
57 "basename" is considered to be the right most path component.
58 For example, the "basename" of "/foo/bar/baz/" would be to be
59 "baz".
60 This key is optional.
62 • recursive
64 Accepts "undef", 0, or 1. If set to 1 any directories provided
66 to the "files" key will be recursively expanded. Defaults to
67 "undef"
68 This key is optional.
70 • verbose
72 Accepts "undef", 0, or 1. 1 enables verbose warnings. Defaults
74 to "undef".
75 This key is optional.
77 • inplace
79 Accepts "undef", 0, or 1. 1 enables in place reformatting of
81 files. Updated files will be backed up unless the "nobackup"
82 key is set. The "mtime" of the file is guarenteed not to be
83 changed unless formating changes did occur. Defaults to
84 "undef".
85 This key is optional.
87 • nobackup
89 Accepts "undef", 0, or 1. If set to 1 files being reformatted
91 in place will not be backed up. Defaults to "undef".
92 This key is optional.
94 • columns
96 Accepts any number. Sets the line width of the reformatted pod.
98 Defaults to 76 (Text::Wrap's default).
99 This key is optional.
101 Before processing a file it is checked for:
103 • correct access permissions
105 • containing Pod
107 • legal Pod syntax
109 Any file failing to meet those criteria will not be processed.
111 Returns a count of processed files or "undef" if no files could be
113 processed.
114 • tidy_filehandle($input)
116 Accepts an open filehandle. Data from the filehandle is processed
118 as it is read so this subroutine can be used to filter large
119 amounts of data. Because of this behavior the input can not be
120 checked in advance to verify a) That it's actually Pod and b) that
121 the Pod document uses only valid Pod syntax. Output is set to
122 "STDOUT". Returns nothing.
123 Internal Subroutines
125 These subroutines are not exportable.
126 • backup_file
128 • base
130 • build_pod_queue
132 • process_pod_queue
134 • valid_pod_syntax
136
138 Efficiency concerns
139 The "tidy_files()" subroutine does a number of highly inefficient
140 things. Each file is opened and closed at least 3 different times as it
141 is passed through a number of different modules to see if it meets the
142 processing criteria. This shouldn't be a major performance issue with
143 an modern OS's VM subsystem but it still leaves much to be desired.
144 When doing "inplace" file reformatting a complete copy of the original
145 file and the updated file and held in memory for comparison. Thus you
146 are limited to reformatting Pod documents " < ( available_system_memory
147 / 2 )".
148
150 Pod files not identified
151 Due to a bug in the version of "contains_pod" in Pod::Find bundled with
152 Pod::Parser 1.33, Pod containing files will not be detected if the only
153 "=[foo]N" directive is on the first line of the file. For example:
154 =head1 foo
156 foobarbaz
158 =cut
160 Would not be detected unless there was a newline before "=head1 foo".
162 See CPAN bug #14871 for a patch to correct Pod::Find. This should be
163 fixed in version 1.34 of Pod::Parser
164 Mangled verbatim blocks
166 Unfortunately, the "perldoc" utility doesn't follow perlpodspec for
167 what it considers a verbatim block. As far as "perldoc" is concerned,
168 any line that begins with whitespace is in a verbatim block. While the
169 Pod spec requires that all blocks are separated by a blank line.
170 Consider this example:
172 =head1 What Would Brian Boitano Do?
174 What would Brian Boitano do
176 If he was here right now?
177 He'd make a plan and he'd follow through
178 That's what Brian Boitano'd do
179 When Brian Boitano was in the olympics
180 Skating for the gold
181 He'd do sound cows and a triple relux
182 wearin a blindfold
183 =cut
185 "perldoc" incorrectly considers the second paragraph to be indented and
187 would display it as one might be expecting. However, "podtidy" would
188 turn it into this:
189 =head1 What Would Brian Boitano Do?
191 What would Brian Boitano do If he was here right now? He'd make a plan and
193 he'd follow through That's what Brian Boitano'd do When Brian Boitano was
194 in the olympics Skating for the gold He'd do sound cows and a triple
195 relux wearin a blindfold
196 =cut
198 If a single blank line is added between the two paragraphs as required
200 by perlpodspec, the original document would look like this:
201 =head1 What Would Brian Boitano Do?
203 What would Brian Boitano do
205 If he was here right now?
206 He'd make a plan and he'd follow through
207 That's what Brian Boitano'd do
208 When Brian Boitano was in the olympics
210 Skating for the gold
211 He'd do sound cows and a triple relux
212 wearin a blindfold
213 =cut
215 Then the result from "podtidy" would be nice and... well... tidy.
217 =head1 What Would Brian Boitano Do?
219 What would Brian Boitano do If he was here right now? He'd make a plan and he'd
221 follow through That's what Brian Boitano'd do
222 When Brian Boitano was in the olympics
224 Skating for the gold
225 He'd do sound cows and a triple relux
226 wearin a blindfold
227 =cut
229
231 Larry Denneau "denneau@ifa.hawaii.edu" reported test failures caused by
232 Module::Build stripping the execute bit from scripts/podtidy.
233 Grant McLean "grant@mclean.net.nz" caught a grammatical error in the
235 documentation.
236 Michael Cartmell "Michael.Cartmell@thomson.com" provided some
238 grammatical corrections and a patch to fix
239 "Pod::Tidy::build_pod_queue()" tests on Win32, reporting test failures
240 on Win32 caused by differing newline encodings, and reporting CPANPLUS
241 playing badly with Module::Build's "build_requires".
242 Hanno Hecker <vetinari@ankh-morp.org> provided a patch to allow the
244 column width to specified in both the Pod::Tidy library and "podtidy"
245 utility.
246
248 Please contact the author directly via e-mail.
249
251 Joshua Hoblitt "jhoblitt@cpan.org"
252
254 Copyright (c) 2005 Joshua Hoblitt. All rights reserved. This program
255 is free software; you can redistribute it and/or modify it under the
256 same terms as Perl itself.
257 The full text of the licenses can be found in the LICENSE file included
259 with this module, or in perlartistic and perlgpl Pods as supplied with
260 Perl 5.8.1 and later.
261
263 podtidy, Pod::Wrap::Pretty, podwrap, Pod::Wrap, Perl::Tidy
264perl v5.34.0 2022-01-21 Pod::Tidy(3)