podtidy man page

podtidy — reformat Pod documents without affecting other text or code

Synopsis

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

Description

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.

Usage

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.

Options

Developer Notes

Why reinvent the “podwrap” wheel?

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

Subversion Working Copies

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:

    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

Efficiency concerns

See "Efficiency concerns" in Pod::Tidy.

Gotchas

See "Gotchas" in Pod::Tidy.

Credits

See "Credits" in Pod::Tidy.

Support

Please contact the author directly via e-mail.

Author

Joshua Hoblitt <jhoblitt@cpan.org>

See Also

Pod::Tidy, Pod::Wrap::Pretty, podwrap, Pod::Wrap, Perl::Tidy

Info

2017-02-11 perl v5.24.1 User Contributed Perl Documentation