PODTIDY(1)

📦
version 0.10 · 3 versions
, in fedora 43

💖 PODTIDY(1) — the podtidy manual page, bestie edition 💖

okay so this is podtidy, from the User Contributed Perl Documentation section. it's giving "glow-up for your Pod docs" energy and honestly? we're obsessed. 💅

✨ NAME ✨

podtidy — reformat Pod documents without affecting other text or code

like, it does a makeover on your Pod and it's polite enough to leave everything else alone. queen behavior, no cap. 👑

✨ SYNOPSIS ✨

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

two whole vibes up there: the "do the thing" mode and the "just tell me how" mode. 🦋

✨ DESCRIPTION ✨

so this program takes a Pod document and attempts to tidy its formatting. rn that means it redoes the line breaks in text Pod paragraphs — that's the whole glow-up, currently. but bestie, the hope is that more features get added in the future. the vision is expanding. 🌈

✨ USAGE ✨

okay so here's the default tea ☕: podtidy reads in a list of filenames and writes the reformatted contents of those files to STDOUT. if you don't give it a file list, it reads from STDIN. simple, clean, no drama.

now, the --inplace flag? that one makes a backup of the input file and then overwrites the original with a reformatted version. important detail tho — only files that are actually having their format changed get written to. the rest just vibe untouched. ✨

when --inplace is combined with --nobackup, the backup of the original file is omitted. gone. skipped. no safety net, so know what you're doing. 💀

if --recursive is specified, then any directory names in <filelist> get recursively expanded. files and directories can be explicitly omitted from processing by using the --Ignore option with a Perl5 compatible regex — and yes, multiple --Ignore options may be specified, stack them like accessories. 🎀

lastly, the --verbose flag enables additional warnings and error messages. it's the "tell me everything" flag. 🙈

✨ OPTIONS ✨

  • --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.

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. (yes, it really says perltidy there. we report, we don't edit. 🫶)

this flag is optional. ✨

  • --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>.

this flag is optional. 🌸

  • --verbose|-v — enable additional warnings and error messages that will be sent to STDERR.

this flag is optional. 👑

  • <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.

this flag is optional. 🎀

  • --help|-h|-? — print usage info to STDERR and exit.

this flag is optional. 🦋

✨ 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

like, it's just built different. 🔥

🌀 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, it's completely safe to use the --nobackup flag. also, the above example may be shorted to just:

podtidy -rin -I .svn docs

(yeah, "shorted" — that's the original's word, we're keeping it fr fr. 😭)

⚡ Efficiency concerns

see "Efficiency concerns" in Pod::Tidy.

✨ GOTCHAS ✨

see "GOTCHAS" in Pod::Tidy.

heads up bestie, the gotchas live somewhere else. go read them, don't get caught slipping. 💀

✨ CREDITS ✨

see "CREDITS" in Pod::Tidy.

✨ SUPPORT ✨

please contact the author directly via e-mail. 📧

✨ AUTHOR ✨

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.

✨ SEE ALSO ✨

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

okay that's the whole page, you ate that 💅 this was perl v5.42.0, dated 2025-07-25, and it's the PODTIDY(1) page from the User Contributed Perl Documentation. go forth and tidy your Pods, bestie. periodt. 💖✨🎀🦋🌸

📦 where this page comes from