podtidy(1)

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

NAME

6       podtidy - reformat Pod documents without affecting other text or code
7

SYNOPSIS

9           podtidy [--inplace] [--nobackup] [--recursive] [--verbose]
10                   [--columns=NUM] {[--Ignore <pattern>]} [<filelist>]
11           podtidy [--help|-h|-?]
12

DESCRIPTION

14       This program processes a Pod document and attempts to tidy it's
15       formatting.  Currently this is limited to redoing the line breaks in
16       text Pod paragraphs but it is hoped that more features will be added in
17       the future.
18

USAGE

20       The default behavior of "podtidy" is to read in a list of filenames and
21       to write the reformatted contents of these files to the "STDOUT".  If
22       no file list is provided input is read from "STDIN".  The "--inplace"
23       flag causes a backup of the input file to be made and the original file
24       to overwritten with a reformatted version.  It should be noted that
25       only files that are actually having there format changed will to
26       written to.  When "--inplace" is combined with "--nobackup" the backup
27       of the original file is omitted.  If "--recursive" is specified then
28       any directory names in <filelist> will be recursively expanded.  File
29       and directories may be explicitly omitted from processing by using the
30       "--Ignore" option and specifying a Perl5 compatible regex.  Multiple
31       "--Ignore" options may be specified.  Lastly, the "--verbose" flag
32       enables additional warnings and error messages.
33

OPTIONS

35       •   --Ignore|I <pattern>
36
37           Causes files and directories matching "pattern" to be omitted from
38           processing.  Where "pattern" is glob(3) compatible.  Each pattern
39           is tried for a match against (in order) the absolute file path, the
40           relative file path (canonical), and the basename.  In the case of
41           directories, the "basename" is considered to be the right most path
42           component.  For example, the "basename" of "/foo/bar/baz/" would be
43           "baz". Multiple "--Ignore" options may be specified.
44
45           This flag is optional.
46
47       •   --inplace|i
48
49           Make a backup of the original file and overwrite it with a
50           reformatted version.  The backup file will have the same name as
51           the original file with a "~" appended to it.  This operation only
52           applies to files that are having changes made to their formatting.
53           Unmodified files will be skipped and no backup file will be
54           created.  "perltidy" guarantees to not change a file's "mtime" if
55           no formatting changes need to be made.
56
57           This flag is optional.
58
59       •   --nobackup|-n
60
61           When making an inplace reformatting, omit the backup file.
62
63           This flag is optional.  This flag is only valid in combination with
64           "--inplace".
65
66       •   --recursive|-r
67
68           Recursively expand any directories included in <filelist>.
69
70           This flag is optional.
71
72       •   --verbose|-v
73
74           Enable additional warnings and error messages that will be sent to
75           "STDERR".
76
77           This flag is optional.
78
79       •   <filelist>
80
81           This is a list of filenames and/or directories if "--recursive" is
82           specified.  If it is omitted input will be read from "STDIN".
83
84           This list is optional.
85
86       •   --columns|-c NUM
87
88           Set the width of the wrapped columns to NUM, default is 76
89
90           This flag is optional.
91
92       •   --help|-h|-?
93
94           Print usage info to "STDERR" and exit.
95
96           This flag is optional.
97

DEVELOPER NOTES

99   Why reinvent the "podwrap" wheel?
100       Primarily because "podwrap" is based on the Pod::Wrap module, which is
101       mostly concerned with breaking long lines and not the production of
102       tidy paragraphs.  Further, while this utility currently only handles
103       Pod text block reformatting it is hoped that additional functionality
104       that would cover other parts of a Pod document will be added in the
105       future.  "podwrap" is also missing a couple of other features that
106       "podtidy" provides for convenience, including:
107
108       •   recursive file/directory processing
109
110       •   backups of files being modified in place
111
112       •   file ignore patterns
113
114       •   preservation of the file's "mtime" unless the file is actually
115           being modified
116
117       •   verbose warnings/diagnostics
118
119   Subversion Working Copies
120       When using "podtidy" on a "svn" Working Copy it's important to remember
121       that copies of all working files are stored under a directory named
122       .svn, including copies of Pod files.  If you use "podtidy"'s
123       "--recursive" option Be Sure that you don't accidentally process a .svn
124       directory. For example:
125
126           podtidy --recursive --inplace --nobackup --Ignore .svn docs
127
128       Note that because any Pod files are already under revision control that
129       it's completely safe to use the "--nobackup" flag.  Also, the above
130       example may be shorted to just:
131
132           podtidy -rin -I .svn docs
133
134   Efficiency concerns
135       See "Efficiency concerns" in Pod::Tidy.
136

GOTCHAS

138       See "GOTCHAS" in Pod::Tidy.
139

CREDITS

141       See "CREDITS" in Pod::Tidy.
142

SUPPORT

144       Please contact the author directly via e-mail.
145

AUTHOR

147       Joshua Hoblitt <jhoblitt@cpan.org>
148

COPYRIGHT

150       Copyright (c) 2005  Joshua Hoblitt. All rights reserved. This program
151       is free software; you can redistribute it and/or modify it under the
152       same terms as Perl itself.
153
154       The full text of the licenses can be found in the LICENSE file included
155       with this module, or in perlartistic and perlgpl Pods as supplied with
156       Perl 5.8.1 and later.
157