1Pod::Tidy(3)          User Contributed Perl Documentation         Pod::Tidy(3)
2
3
4

NAME

6       Pod::Tidy - a reformatting Pod Processor
7

SYNOPSIS

9           use Pod::Tidy qw( tidy_files tidy_filehandle );
10
11           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
21           Pod::Tidy::tidy_filehandle($input);
22

DESCRIPTION

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

USAGE

28   Import Parameters
29       This module accepts no arguments to it's "import" method and exports no
30       symbols.
31
32   Exportable Subroutines
33       •   tidy_files( ... )
34
35           Accepts a mandatory hash.
36
37               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
47           •   files
48
49               An array ref to a list of files and/or directories.
50
51           •   ignore
52
53               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
61               This key is optional.
62
63           •   recursive
64
65               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
69               This key is optional.
70
71           •   verbose
72
73               Accepts "undef", 0, or 1.  1 enables verbose warnings. Defaults
74               to "undef".
75
76               This key is optional.
77
78           •   inplace
79
80               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
86               This key is optional.
87
88           •   nobackup
89
90               Accepts "undef", 0, or 1.  If set to 1 files being reformatted
91               in place will not be backed up.  Defaults to "undef".
92
93               This key is optional.
94
95           •   columns
96
97               Accepts any number. Sets the line width of the reformatted pod.
98               Defaults to 76 (Text::Wrap's default).
99
100               This key is optional.
101
102           Before processing a file it is checked for:
103
104           •   correct access permissions
105
106           •   containing Pod
107
108           •   legal Pod syntax
109
110           Any file failing to meet those criteria will not be processed.
111
112           Returns a count of processed files or "undef" if no files could be
113           processed.
114
115       •   tidy_filehandle($input)
116
117           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
124   Internal Subroutines
125       These subroutines are not exportable.
126
127       •   backup_file
128
129       •   base
130
131       •   build_pod_queue
132
133       •   process_pod_queue
134
135       •   valid_pod_syntax
136

DEVELOPER NOTES

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

GOTCHAS

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
155           =head1 foo
156
157           foobarbaz
158
159           =cut
160
161       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
165   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
171       Consider this example:
172
173           =head1 What Would Brian Boitano Do?
174
175           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
184           =cut
185
186       "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
190           =head1 What Would Brian Boitano Do?
191
192           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
197           =cut
198
199       If a single blank line is added between the two paragraphs as required
200       by perlpodspec, the original document would look like this:
201
202           =head1 What Would Brian Boitano Do?
203
204           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
209               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
214           =cut
215
216       Then the result from "podtidy" would be nice and... well... tidy.
217
218           =head1 What Would Brian Boitano Do?
219
220           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
223               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
228           =cut
229

CREDITS

231       Larry Denneau "denneau@ifa.hawaii.edu" reported test failures caused by
232       Module::Build stripping the execute bit from scripts/podtidy.
233
234       Grant McLean "grant@mclean.net.nz" caught a grammatical error in the
235       documentation.
236
237       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
243       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

SUPPORT

248       Please contact the author directly via e-mail.
249

AUTHOR

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
258       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

SEE ALSO

263       podtidy, Pod::Wrap::Pretty, podwrap, Pod::Wrap, Perl::Tidy
264
265
266
267perl v5.32.1                      2021-01-27                      Pod::Tidy(3)
Impressum