podtidy - reformat Pod documents without affecting other text or code
podtidy [--inplace] [--nobackup] [--recursive] [--verbose] [--columns=NUM] {[--Ignore <pattern>]} [<filelist>] podtidy [--help|-h|-?]
This program processes a Pod document and attempts to tidy it's formatting. Currently this is limited to redoing the line breaks in text Pod paragraphs but it is hoped that more features will be added in the future.
The default behavior of podtidy is to read in a list of filenames and to write the reformatted contents of these files to the STDOUT. If no file list is provided input is read from STDIN. The --inplace flag causes a backup of the input file to be made and the original file to overwritten with a reformatted version. It should be noted that only files that are actually having there format changed will to written to. When --inplace is combined with --nobackup the backup of the original file is omitted. If --recursive is specified then any directory names in <filelist> will be recursively expanded. File and directories may be explicitly omitted from processing by using the --Ignore option and specifying a Perl5 compatible regex. Multiple --Ignore options may be specified. Lastly, the --verbose flag enables additional warnings and error messages.
podtidy
STDOUT
STDIN
--inplace
--nobackup
--recursive
--Ignore
--verbose
--Ignore|I <pattern>
Causes files and directories matching pattern to be omitted from processing. Where pattern is glob(3) compatible. Each pattern is tried for a match against (in order) the absolute file path, the relative file path (canonical), and the basename. In the case of directories, the "basename" is considered to be the right most path component. For example, the "basename" of /foo/bar/baz/ would be baz. Multiple --Ignore options may be specified.
pattern
glob(3)
/foo/bar/baz/
baz
This flag is optional.
--inplace|i
Make a backup of the original file and overwrite it with a reformatted version. The backup file will have the same name as the original file with a ~ appended to it. This operation only applies to files that are having changes made to their formatting. Unmodified files will be skipped and no backup file will be created. perltidy guarantees to not change a file's mtime if no formatting changes need to be made.
~
perltidy
mtime
--nobackup|-n
When making an inplace reformatting, omit the backup file.
This flag is optional. This flag is only valid in combination with --inplace.
--recursive|-r
Recursively expand any directories included in <filelist>.
--verbose|-v
Enable additional warnings and error messages that will be sent to STDERR.
STDERR
<filelist>
This is a list of filenames and/or directories if --recursive is specified. If it is omitted input will be read from STDIN.
This list is optional.
--columns|-c NUM
Set the width of the wrapped columns to NUM, default is 76
--help|-h|-?
Print usage info to STDERR and exit.
podwrap
Primarily because podwrap is based on the Pod::Wrap module, which is mostly concerned with breaking long lines and not the production of tidy paragraphs. Further, while this utility currently only handles Pod text block reformatting it is hoped that additional functionality that would cover other parts of a Pod document will be added in the future. podwrap is also missing a couple of other features that podtidy provides for convenience, including:
recursive file/directory processing
backups of files being modified in place
file ignore patterns
preservation of the file's mtime unless the file is actually being modified
verbose warnings/diagnostics
When using podtidy on a svn Working Copy it's important to remember that copies of all working files are stored under a directory named .svn, including copies of Pod files. If you use podtidy's --recursive option Be Sure that you don't accidentally process a .svn directory. For example:
svn
podtidy --recursive --inplace --nobackup --Ignore .svn docs
Note that because any Pod files are already under revision control that it's completely safe to use the --nobackup flag. Also, the above example may be shorted to just:
podtidy -rin -I .svn docs
See "Efficiency concerns" in Pod::Tidy.
See "GOTCHAS" in Pod::Tidy.
See "CREDITS" in Pod::Tidy.
Please contact the author directly via e-mail.
Joshua Hoblitt <jhoblitt@cpan.org>
Copyright (c) 2005 Joshua Hoblitt. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the licenses can be found in the LICENSE file included with this module, or in perlartistic and perlgpl Pods as supplied with Perl 5.8.1 and later.
Pod::Tidy, Pod::Wrap::Pretty, podwrap, Pod::Wrap, Perl::Tidy
To install Pod::Tidy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Tidy
CPAN shell
perl -MCPAN -e shell install Pod::Tidy
For more information on module installation, please visit the detailed CPAN module installation guide.